You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
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
Draft Proposal: AI creates a change proposal with spec deltas
Review & Align: Human reviews and refines until specs match intent
Implement Tasks: AI implements code following agreed specifications
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:
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
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
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
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: readpull-requests: writesafe-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
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
Prototype Integration: Create an experimental MCP server or workflow that reads OpenSpec structure
Document Compatibility: Add OpenSpec to gh-aw documentation as a compatible framework
Example Workflows: Build sample workflows demonstrating OpenSpec + gh-aw usage
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_requestpermissions:
contents: readpull-requests: writeenv:
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' labelif: contains(github.event.issue.labels.*.name, 'spec-change')---## Create OpenSpec Change Proposal
Generate an OpenSpec change proposal for this issue
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.
Activity
pelikhan commentedon Jan 26, 2026
/scout
github-actions commentedon Jan 26, 2026
🏕️ Lost in the wilderness! Scout failed. Sending search party...
pelikhan commentedon Jan 26, 2026
/scout
github-actions commentedon Jan 26, 2026
🏕️ Lost in the wilderness! Scout failed. Sending search party...
pelikhan commentedon Jan 26, 2026
/scout
github-actions commentedon Jan 26, 2026
🔭 Recon complete! Scout has charted the territory. Map ready! 🗺️
github-actions commentedon Jan 26, 2026
🔍 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:
openspec/specs/) from proposed changes (openspec/changes/)OpenSpec Directory Structure
OpenSpec Workflow
Why OpenSpec Matters
Problems it solves:
Benefits:
AGENTS.md Convention
OpenSpec uses
AGENTS.mdas a "README for Robots" - a file containing instructions for AI models on how to:This makes OpenSpec highly portable - even tools without native support can follow specs by reading this file.
Integration with gh-aw
Potential Integration Points:
Specification Context Access
openspec/specs/to understand system requirementsopenspec/changes/to see what's being worked onAGENTS.mdfile could guide agent behavior in workflowsSpec-Driven Workflow Types
Safe Outputs Integration
MCP Integration
spec-workflow-mcp)Example Use Cases:
Related Tools & Ecosystem
Similar frameworks:
Key Differentiators:
Technical Architecture
File Format: Markdown with structured sections
### Requirement:headers#### Scenario:blocks## ADDED/MODIFIED/REMOVED RequirementssectionsCLI Commands:
openspec init- Initialize projectopenspec list- View active changesopenspec validate (change)- Check spec formattingopenspec archive (change)- Merge change into specsopenspec show (change)- Display change detailsSlash Commands (for supported tools):
/openspec:proposal- Draft change proposal/openspec:apply- Implement tasks/openspec:archive- Archive completed changeImplementation Considerations
For gh-aw Support:
openspec/directory andAGENTS.mdPotential Challenges:
Community & Adoption
Recommendations
Immediate Actions
Integration Approach
Phase 1 - Basic Support:
openspec/directory presenceAGENTS.mdand include in agent contextPhase 2 - Enhanced Features:
Phase 3 - Deep Integration:
Architecture Patterns
Spec-Aware Workflows:
Change Tracking:
Key Sources
Suggested Next Steps
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.