[FEATURE] Add Documentation for Integrating Spec-Kit with OpenAgents

[taqtiqa-mark]

Repository: darrenhinde/OpenAgents (primary target, as OpenAgents extends OpenCode functionality)
Alternative Repository: github/spec-kit (cross-reference or linked guide)
Type: Documentation Enhancement
Priority: Medium (improves usability for hybrid workflows without code changes)

Summary

Provide a dedicated documentation section (e.g., a new Markdown file such as docs/integrations/spec-kit.md or an addition to README.md under a "Integrations" heading) explaining how to combine Spec-Kit with OpenAgents. This integration leverages Spec-Kit's explicit support for the OpenCode CLI, enabling its slash commands (/speckit.*) within OpenAgents sessions launched via opencode --agent openagent or opencode --agent opencoder. The guide would demonstrate a hybrid workflow where Spec-Kit's specification-driven phases ground OpenAgents' plan-first execution, enhancing accuracy through structured artifacts and phased validation.

Motivation

• Spec-Kit is explicitly designed for compatibility with OpenCode, including full slash-command integration when initialized with --ai opencode.
• OpenAgents builds directly on OpenCode, inheriting its terminal user interface (TUI) and command system.
• Users can achieve a powerful spec-first to plan-first pipeline: Use Spec-Kit for upfront executable specifications (e.g., constitution.md, spec.md, tasks.md) and OpenAgents for approval-gated execution, testing, and subagent delegation.
• Current documentation in both repositories lacks explicit guidance on this combination, despite natural compatibility. Adding this would reduce setup friction, promote best practices, and highlight synergies for multi-language, validation-heavy projects.
• As of December 2025, Spec-Kit supports numerous agents (including opencode), making this a addition to encourage adoption.

Proposed Content Outline for the Documentation

The new section should include clear, step-by-step instructions with code examples, substantiated by references to existing repository features.

1. Prerequisites

   • Install OpenCode CLI (per https://opencode.ai/docs).
   • Install OpenAgents (via interactive installer or profile-based script).
   • Install Spec-Kit CLI (using uv tool install specify-cli --from git+https://github.com/github/spec-kit.git).

2. Project Initialization

   • Initialize a Spec-Kit project selecting OpenCode as the AI agent:

     specify init my-project --ai opencode --here  # Use --here for existing repositories
     

   • This scaffolds the .specify/ directory and enables /speckit.* commands in compatible agents.

3. Launching a Hybrid Session

   • Start an OpenAgents session:

     opencode --agent openagent  # Or opencoder for complex coding tasks
     

   • Within the TUI, Spec-Kit slash commands are now available alongside OpenAgents commands (e.g., /commit, /test).

4. Recommended Workflow

   • Phase 1: Specification (Spec-Kit)
     Use /speckit.constitution, /speckit.specify, /speckit.plan, and /speckit.tasks to generate artifacts like specs/<feature>/spec.md and tasks.md.
   • Phase 2: Execution (OpenAgents)
     Delegate implementation to OpenAgents' hierarchical subagents (e.g., prompt for task breakdown, then approve plans for incremental execution with automatic testing via @tester and @reviewer).
   • Synergies:
     • Reference Spec-Kit artifacts in OpenAgents context (e.g., via .opencode/context/ files or direct prompts).
     • Use /speckit.implement to initiate code generation, then leverage OpenAgents' approval gates for validation.
     • Enhance accuracy by validating OpenAgents-generated code against Spec-Kit checklists and contracts.

5. Example Session
   Provide a sample transcript:

   /speckit.specify Build a photo album app with upload and organization features.
   /speckit.plan Use TypeScript and SQLite.
   /speckit.tasks
   # Review tasks.md, then:
   Implement the tasks using opencoder subagents with full testing.
   

6. Advanced Tips

   • Load Spec-Kit artifacts into OpenAgents context files for persistent standards enforcement.
   • Use OpenAgents' System Builder (Advanced profile) to create custom agents that incorporate Spec-Kit phases.
   • Troubleshooting: Ensure no command conflicts; Spec-Kit commands are prefixed distinctly.

7. Benefits

   • Improves requirement fidelity and reduces rework.
   • Combines Spec-Kit's upfront governance with OpenAgents' runtime safeguards.

Implementation Notes

• No code changes required; this is purely documentation.
• Cross-link to Spec-Kit's spec-driven.md and agent compatibility table.
• Optionally, add a note in Spec-Kit's documentation linking back for OpenAgents-specific execution tips.

This addition would significantly enhance the ecosystem's value for professional developers adopting AI-driven workflows. Thank you for considering this request.

Would You Like to Contribute?

• I'm just suggesting the idea

[shaunpatel]

This may also be very useful for creating a shared memory within a repo since these specs and updates could be committed to git alongside the code changes.

[darrenhinde]

I like the idea but have a few questions.

Do you only use Speck-kit as commands or does it need more prompting enforced behaviour?
Is it up to the user to decide when to use it or would it be better to make this more forced and followed? So the user doesn't need to know when to use each command?

If its the later, I think I have a good way to include this an option but will ned some testing with feadback from you once version 1 is out.

If you can give me the best ROI for using spec-kit with a good example it will help me think of best ways to implement this.

[taqtiqa-mark]

This may also be very useful for creating a shared memory within a repo since these specs and updates could be committed to git alongside the code changes.

I generally prefer taking a modular approach, rather than trying to be all things. Especially when the tech, the functionality it unlocks, and best practices, are evolving so rapidly.

Memory is probably best delegated. In some cases Serena may be the preferred memory manager, in another case, bead, etc. etc.
Spec-kit does have some of its own memory so there is that to disentagle - if it is possible.

[taqtiqa-mark]

Do you only use Speck-kit as commands or does it need more prompting enforced behaviour?

It is a bit more sophisticated.

https://github.com/github/spec-kit?tab=readme-ov-file#-core-philosophy

Definitely a human-in-the-loop workflow (see PocketFlow cookbook for implementation details), but is more sophisticated. When I thought things through, I couldn't see a reasonable way to implement a more helpful workflow (e.g. "With these changes, the tasks list needs to be updated. Can I do that now?")

Is it up to the user to decide when to use it or would it be better to make this more forced and followed?

Both. Honestly, PocketFlow is the only Framework I've seen that looks sane, and powerful enough to handle this - added advantage is the cookbook has MVP implementations for most features.

So the user doesn't need to know when to use each command?

No, they do. And that won't change, IMO, except for trivial cases. Trivial will be expanded, but non-trivial will never go away - it'll expand at a faster rate (in my current experience).

If it is adopted you'll probably need some degree of integration, I don't think these projects have arrived at a agreed module management approach.

[taqtiqa-mark]

If you did want to offer more than docs... one way to thread the needle is to adopt an plugin approach. OpenAgent value-add would then be not to offer/allow conflicting plugins. Again keep coming back to PocketFlow (likely with A2A implementation) as the way to keep the implementation effort sane.

I spiked some python code as an attempt to understand, but have run out of time.

[stdweird]

i am also interested in this, but using openspec instead of speckit.

imho, it would be ideal that openagents can somehow use eg the whateverspec commands to do it's planning and building, where functionality overlaps ofcourse; instead of users having to know the whateverspec internals (but still having access to the internal whateverspec commands for advanced usage).

having some of the internals of openagents using a portable whateverspec has a serious advantage imho.

trying to port the contextscout magic to eg openspec is not to correct way (openspec should focus on the spec flow; an overall context can also be useful for that; and it feels like openspec has something similar with the sync building up context from the changes, but it's not quite the same). i think context + spec is winner combo