Skip to content

Open spec #11813

Closed as not planned
Closed as not planned

Description

@pelikhan

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

/scout

Activity

  1. pelikhan commented on Jan 26, 2026

    @pelikhan
    CollaboratorAuthor

    /scout

  2. github-actions commented on Jan 26, 2026

    @github-actions
    Contributor

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

  3. pelikhan commented on Jan 26, 2026

    @pelikhan
    CollaboratorAuthor

    /scout

  4. github-actions commented on Jan 26, 2026

    @github-actions
    Contributor

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

  5. pelikhan commented on Jan 26, 2026

    @pelikhan
    CollaboratorAuthor

    /scout

  6. github-actions commented on Jan 26, 2026

    @github-actions
    Contributor

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

  7. github-actions commented on Jan 26, 2026

    @github-actions
    Contributor

    🔍 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

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions