Open spec

[pelikhan]

Investigate how to support https://github.com/Fission-AI/OpenSpec

/scout

[pelikhan]

/scout

[github-actions]

🏕️ Lost in the wilderness! Scout failed. Sending search party...

[pelikhan]

/scout

[github-actions]

🏕️ Lost in the wilderness! Scout failed. Sending search party...

[pelikhan]

/scout

[github-actions]

🔭 Recon complete! Scout has charted the territory. Map ready! 🗺️

[github-actions]

🔍 Scout Research Report

Triggered by @pelikhan

Executive Summary

OpenSpec is a spec-driven development (SDD) framework that aligns humans and AI coding assistants by establishing specifications as the source of truth before code is written. It addresses the unpredictability of AI agents working from scattered chat history by providing a structured workflow with explicit change tracking.

Integration Opportunity: gh-aw could support OpenSpec by recognizing its folder structure (openspec/specs/, openspec/changes/) and providing AI agents access to specifications during workflow execution, enabling spec-driven agentic workflows in GitHub Actions.

Click to expand detailed findings

Research Findings

What is OpenSpec?

Core Concept: OpenSpec implements specification-driven development where requirements are defined and agreed upon before implementation begins. This contrasts with "vibe coding" where AI agents generate code from vague prompts.

Key Features:

• Lightweight: No API keys required, minimal setup
• Brownfield-first: Excellent for modifying existing codebases (1→n), not just greenfield (0→1)
• Change tracking: Separates current truth (openspec/specs/) from proposed changes (openspec/changes/)
• Delta-based storage: Changes are stored as diffs (ADDED/MODIFIED/REMOVED requirements)
• Universal compatibility: Works with Claude Code, Cursor, GitHub Copilot, and other AI tools via AGENTS.md

OpenSpec Directory Structure

openspec/
├── AGENTS.md              # "README for Robots" - AI agent instructions
├── project.md             # Global project context, tech stack, conventions
├── specs/                 # Current system "source of truth"
│   └── feature-name/
│       └── spec.md        # Current specification
└── changes/               # Active change proposals (workspace)
    └── add-feature/
        ├── proposal.md    # Change intent & design
        ├── tasks.md       # Implementation checklist
        ├── design.md      # Technical decisions (optional)
        └── specs/         # Spec deltas (patches)
            └── feature-name/
                └── spec.md # ADDED/MODIFIED/REMOVED requirements

OpenSpec Workflow

1. Draft Proposal: AI creates a change proposal with spec deltas
2. Review & Align: Human reviews and refines until specs match intent
3. Implement Tasks: AI implements code following agreed specifications
4. Archive: Merge approved spec deltas back into source-of-truth specs

Why OpenSpec Matters

Problems it solves:

• AI agents hallucinating features when context lives in chat history
• Inconsistent outputs across sessions
• Difficulty maintaining context in complex projects
• Lack of reviewable, auditable AI decisions

Benefits:

• Deterministic outputs: Specs lock intent before implementation
• Better AI accuracy: Detailed specs reduce hallucinations
• Improved reviews: Stakeholders approve specs before code exists
• Persistent context: Specs carry forward everything AI needs
• Team collaboration: Multiple developers/agents work from same source of truth

AGENTS.md Convention

OpenSpec uses AGENTS.md as a "README for Robots" - a file containing instructions for AI models on how to:

• Read project context
• Format output
• Follow OpenSpec's workflow state machine

This makes OpenSpec highly portable - even tools without native support can follow specs by reading this file.

Integration with gh-aw

Potential Integration Points:

1. Specification Context Access

   • AI agents in gh-aw workflows could read openspec/specs/ to understand system requirements
   • Agents could access active changes in openspec/changes/ to see what's being worked on
   • The AGENTS.md file could guide agent behavior in workflows

2. Spec-Driven Workflow Types

   • Create agentic workflows that validate implementations against specs
   • Generate reports comparing code changes to specification requirements
   • Auto-check that PRs have corresponding spec updates

3. Safe Outputs Integration

   • Use gh-aw's safe-outputs to create/update OpenSpec changes
   • Enable workflows to propose spec changes via issues/discussions
   • Validate spec delta format before archiving

4. MCP Integration

   • Create an MCP server for OpenSpec (similar to spec-workflow-mcp)
   • Allow agents to query specs, list changes, validate deltas
   • Enable spec-driven context injection for AI agents

Example Use Cases:

---
on:
  pull_request:
    types: [opened, synchronize]
permissions:
  contents: read
  pull-requests: write
safe-outputs:
  add-comment:
---

## Spec Compliance Check

Review this PR against OpenSpec specifications in `openspec/specs/`.

1. Check if there's a corresponding change in `openspec/changes/`
2. Validate that code changes align with spec requirements
3. Identify any spec violations or missing requirements
4. Comment on the PR with findings

Related Tools & Ecosystem

Similar frameworks:

• GitHub Spec Kit: GitHub's official spec-driven framework, greenfield-focused
• Agent OS: Spec-driven system with 3-layer context (Standards/Product/Specs)
• BMAD Method: Agile AI-driven development with specialized agent roles
• Kiro: Continuous validation between spec and implementation

Key Differentiators:

• OpenSpec: Brownfield-first, delta-based, change-folder organization
• Spec Kit: Greenfield-focused, 4-phase gated workflow
• Agent OS: 3-layer context system, emphasizes coding standards
• BMAD: 21 specialized agents, enterprise/agile methodology

Technical Architecture

File Format: Markdown with structured sections

• Requirements use ### Requirement: headers
• Scenarios use #### Scenario: blocks
• Deltas use ## ADDED/MODIFIED/REMOVED Requirements sections

CLI Commands:

• openspec init - Initialize project
• openspec list - View active changes
• openspec validate (change) - Check spec formatting
• openspec archive (change) - Merge change into specs
• openspec show (change) - Display change details

Slash Commands (for supported tools):

• /openspec:proposal - Draft change proposal
• /openspec:apply - Implement tasks
• /openspec:archive - Archive completed change

Implementation Considerations

For gh-aw Support:

1. Detection: Check for openspec/ directory and AGENTS.md
2. Context Injection: Automatically include relevant specs in agent context
3. Validation Tools: Provide commands to validate spec format
4. Workflow Templates: Offer pre-built OpenSpec-aware workflows
5. Documentation: Guide users on combining gh-aw + OpenSpec

Potential Challenges:

• Context size management (specs can be large)
• Determining which specs are relevant for a given workflow
• Keeping specs in sync across workflow runs
• Avoiding conflicts between workflow changes and local changes

Community & Adoption

• Active development (latest release: v0.23.0, Jan 2026)
• Supports 20+ AI coding tools
• Growing ecosystem of extensions and MCPs
• Discord community for support
• MIT licensed, open source

Recommendations

Immediate Actions

1. Prototype Integration: Create an experimental MCP server or workflow that reads OpenSpec structure
2. Document Compatibility: Add OpenSpec to gh-aw documentation as a compatible framework
3. Example Workflows: Build sample workflows demonstrating OpenSpec + gh-aw usage
4. Community Engagement: Reach out to OpenSpec maintainers about collaboration

Integration Approach

Phase 1 - Basic Support:

• Detect openspec/ directory presence
• Read AGENTS.md and include in agent context
• Provide workflow examples using OpenSpec specs

Phase 2 - Enhanced Features:

• MCP server for OpenSpec operations
• Workflow templates for spec validation
• Safe-outputs for creating/updating changes

Phase 3 - Deep Integration:

• Automatic spec-to-workflow mapping
• Continuous spec validation workflows
• Spec-driven test generation

Architecture Patterns

Spec-Aware Workflows:

---
on: pull_request
permissions:
  contents: read
  pull-requests: write
env:
  OPENSPEC_ENABLED: true
---

## Context
Read openspec/AGENTS.md and openspec/project.md for project guidelines.

## Task
Review PR against specifications in openspec/specs/

Change Tracking:

---
on:
  issues:
    types: [labeled]
  # Only run on issues with 'spec-change' label
if: contains(github.event.issue.labels.*.name, 'spec-change')
---

## Create OpenSpec Change Proposal
Generate an OpenSpec change proposal for this issue

Key Sources

• OpenSpec GitHub Repository
• [OpenSpec NPM Package]((redacted)
• [OpenSpec Deep Dive Guide]((redacted)
• [Spec-Driven Development Overview]((redacted)
• [GitHub Blog: Spec-Driven Development]((redacted)
• Spec-Workflow-MCP - Existing MCP implementation

Suggested Next Steps

1. Investigate: Clone OpenSpec repo and run through workflow locally
2. Design: Sketch out MCP server or workflow integration architecture
3. Prototype: Build minimal proof-of-concept integration
4. Test: Validate with real OpenSpec projects
5. Document: Create integration guide for users
6. Collaborate: Engage with Fission-AI team on official support

---

Key Insight: OpenSpec and gh-aw are highly complementary - OpenSpec provides the "what to build" (specifications) while gh-aw provides the "how to automate" (agentic workflows). Integration would enable specification-driven agentic workflows in GitHub Actions.

AI generated by Scout