A side-by-side look at two of the most influential frameworks for structured, agentic AI coding β plus a step-by-step playbook for using them together:
- github/spec-kit β GitHub's toolkit for Spec-Driven Development (SDD).
- obra/superpowers β Jesse Vincent's agentic skills framework for disciplined agent-driven development.
Both projects address the same underlying problem β AI coding agents are powerful but unstructured β but they solve it from very different angles. Spec Kit treats the specification as the source of truth; Superpowers treats the development workflow as the source of truth.
π Table of Contents
- β‘ TL;DR
- 1. π§ Philosophy
- 2. π Workflow & Mental Model
- 3. ποΈ Architecture & Primary Unit
- 4. π€ Agent / Tool Compatibility
- 5. π¦ Installation & Distribution
- 6. π§© Customization & Extensibility
- 7. π What Each Does Especially Well
- 8. βοΈ Tradeoffs & Limitations
- 9. π€ How They Could Coexist
- 9a. π οΈ The Best Way to Combine Both β A Practical Guide
- 10. π§ Quick Decision Guide
- 11. π At-a-Glance Summary
β‘ TL;DR
| Spec Kit | Superpowers | |
|---|---|---|
| Author / Owner | GitHub (org-backed) | Jesse Vincent + Prime Radiant team |
| Core idea | Specs are executable; code is generated from specs | Skills enforce a disciplined dev workflow |
| Primary artifact | The specification document | The skill (a triggered procedure) |
| Trigger model | User-invoked slash commands (/speckit.*) |
Auto-triggered skills based on context |
| Methodology | Spec-Driven Development (SDD) | Agentic SDLC (brainstorm β design β plan β TDD β review β ship) |
| Best for | Greenfield features, brownfield enhancements, spec-to-code traceability | Multi-hour autonomous work, parallel subagents, TDD discipline |
| Distribution | Python CLI (uv tool install specify-cli) |
Plugin marketplaces (Claude, Codex, Cursor, etc.) |
| License | MIT | MIT |
| Maturity | 90.8k stars, 136 releases, 100+ community extensions | 167k stars, active releases, Discord community |
1. π§ Philosophy
π Spec Kit β "The spec is the source of truth"
Spec Kit flips the traditional flow: instead of writing code that loosely tracks a spec, the spec directly generates the implementation. Changes happen at the spec layer first; code is regenerated to match. Quoting the README: "specifications become executable, directly generating working implementations rather than just guiding them."
Foundational principles:
- Intent first β what & why before how
- Rich, guard-railed specifications with organizational principles
- Multi-step refinement instead of one-shot generation
- AI-native workflows that lean on advanced model capabilities
π¦Έ Superpowers β "The workflow is the source of truth"
Superpowers prevents agents from immediately jumping into code. It enforces a disciplined sequence: discovery β design validation β planning β implementation β review β completion. From the README: "As soon as it sees that you're building something, it doesn't just jump into trying to write code."
Four core principles:
- Test-Driven Development β tests precede all code
- Systematic over ad-hoc β process replaces guessing
- Complexity reduction β simplicity is the primary goal
- Evidence over claims β verify before declaring success
π The philosophical split
- Spec Kit is artifact-centric. The spec persists, evolves, and is the contract.
- Superpowers is process-centric. The procedure persists; the artifact is whatever the procedure produces.
2. π Workflow & Mental Model
π Spec Kit's 7-step workflow
-
/speckit.constitutionβ Establish project governing principles -
/speckit.specifyβ Define requirements and user stories -
/speckit.clarifyβ Clarify underspecified requirements -
/speckit.planβ Create technical implementation plans - Validate the plan for completeness
-
/speckit.tasksβ Generate actionable task breakdowns -
/speckit.implementβ Execute tasks to build features
Three modes: 0-to-1 (greenfield), Creative Exploration (parallel implementations across stacks), Iterative Enhancement (brownfield).
π¦Έ Superpowers' 7 workflow stages
- Brainstorming β Socratic questioning to refine ideas
- Using Git Worktrees β Isolated branches with verified test baselines
- Writing Plans β Break work into 2β5 minute tasks with exact specs
- Subagent-Driven Development β Fresh subagent per task, two-stage review
- Test-Driven Development β Strict RED-GREEN-REFACTOR
- Requesting Code Review β Pre-review checklists, severity-based tracking
- Finishing Development Branches β Merge/PR decision + cleanup
π― Key contrast
- Spec Kit's workflow is linear and document-producing: each command emits an artifact (constitution, spec, plan, tasks).
- Superpowers' workflow is stateful and execution-producing: each stage manipulates code, tests, branches, and subagent state.
3. ποΈ Architecture & Primary Unit
π Spec Kit β Slash commands + templates
Six explicit, user-invoked slash commands (/speckit.constitution, /speckit.specify, /speckit.clarify, /speckit.plan, /speckit.tasks, /speckit.implement). Each is a template that produces a structured artifact stored under .specify/.
.specify/
βββ memory/ # Constitution and governance
βββ specs/ # Feature specifications by ID
βββ scripts/ # Helper automation scripts
βββ extensions/ # Custom extensions
βββ presets/ # Workflow customizations
βββ templates/ # Command templates
π¦Έ Superpowers β Skills + agents + plugins
14+ composable skills organized by category:
-
Testing:
test-driven-development -
Debugging:
systematic-debugging,verification-before-completion -
Collaboration:
brainstorming,writing-plans,executing-plans,dispatching-parallel-agents,requesting-code-review,receiving-code-review,using-git-worktrees,finishing-a-development-branch,subagent-driven-development -
Meta:
writing-skills,using-superpowers
agents/ # Agent definitions
skills/ # Skill implementations (auto-triggered)
commands/ # CLI command definitions
.claude-plugin/, .codex-plugin/, .cursor-plugin/ # Per-host configs
π¬ Trigger model β the deepest difference
-
Spec Kit: human types
/speckit.plan. Explicit, deterministic. - Superpowers: skill auto-fires when its description matches the situation. The agent doesn't decide to brainstorm; the brainstorming skill triggers because the user mentioned a vague idea.
This makes Spec Kit feel like a CLI you drive, and Superpowers feel like an operating system the agent inhabits.
4. π€ Agent / Tool Compatibility
| Agent / Tool | Spec Kit | Superpowers |
|---|---|---|
| Claude Code | β | β (official + Superpowers marketplace) |
| GitHub Copilot CLI | β | β |
| Gemini CLI | β | β |
| Cursor (CLI / IDE) | β | β (plugin marketplace) |
| OpenAI Codex CLI / Codex App | β | β |
| OpenCode | β | β |
| Qwen / Mistral / others | β (30+ agents total) | β |
Spec Kit casts a wider net (30+ agents), selected at install time via --integration. Superpowers goes deeper per host, with first-class plugin packages tailored to each ecosystem.
5. π¦ Installation & Distribution
π Spec Kit
uv tool install specify-cli --from git+https://github.com/github/spec-kit.git@vX.Y.Z
- Python 3.11+, Git,
uvorpipx - Cross-platform (Linux/macOS/Windows)
- Distributed only from GitHub β PyPI packages with the same name are not official
π¦Έ Superpowers
- Claude plugin marketplace:
/plugin install superpowers@claude-plugins-official - Superpowers marketplace registration
- Per-agent installation flows for Codex, Cursor, OpenCode, Copilot CLI, Gemini CLI
Spec Kit is a single CLI you install once and configure per project. Superpowers is a plugin you install per agent host, with the host's plugin system managing updates.
6. π§© Customization & Extensibility
π Spec Kit
- Extensions β add new capabilities (Jira sync, post-implementation review, β¦)
- Presets β customize existing workflows (compliance formats, terminology localization)
-
100+ community-contributed extensions across
docs,code,process,integration,visibilitycategories
π¦Έ Superpowers
-
Skills are the extension primitive β write your own
SKILL.mdwith a description that triggers in your situation - The
writing-skillsmeta-skill teaches the agent how to author new skills -
using-superpowersdocuments how skills compose
π Comparison
- Spec Kit's extension model is catalog-driven β you browse and adopt prebuilt pieces.
- Superpowers' extension model is author-driven β the framework actively supports you writing the next skill.
7. π What Each Does Especially Well
π Spec Kit shines whenβ¦
- You need traceability from requirement to code (audits, compliance, regulated industries)
- A product manager / non-engineer owns the spec and engineers consume it
- You want to swap stacks: regenerate the same spec into Go, Python, TypeScript
- Your org already thinks in terms of PRDs, RFCs, and design docs
- You need enterprise-style governance with constitution-level constraints
π¦Έ Superpowers shines whenβ¦
- You want the agent to run autonomously for hours without going off-rails
- You want strict TDD baked into the agent's behavior, not just hoped for
- You're orchestrating parallel subagents and need built-in review patterns
- You need evidence-based completion β agent must prove it worked, not claim it
- You're operating at the frontier of agent autonomy and want guardrails by default
8. βοΈ Tradeoffs & Limitations
π Spec Kit
- Heavier upfront cost β writing a constitution and spec before any code feels slow for small tasks
- Less suited for exploratory hacking β the workflow assumes you know roughly what you want
- Spec drift risk β if the team edits code without updating specs, the "single source of truth" erodes
- Document-heavy β generates many markdown artifacts that need maintenance
π¦Έ Superpowers
- Opinionated β the workflow assumes you want TDD, worktrees, subagent orchestration; if you don't, friction is high
- Complexity floor β even small tasks pay some procedural overhead
- Learning curve β 14+ skills and a meta-vocabulary (subagent-driven-development, verification-before-completion) take time to internalize
- Auto-triggering can surprise β a skill firing unexpectedly can derail a session if descriptions are loose
9. π€ How They Could Coexist
These are not mutually exclusive. A team could realistically:
- Use Spec Kit for the what β constitution, spec, plan, tasks committed to the repo as durable artifacts
- Use Superpowers for the how β once tasks exist, Superpowers' TDD, worktree, subagent, and review skills execute them
The artifacts Spec Kit produces (.specify/specs/<id>/tasks.md) are exactly the kind of plan Superpowers' executing-plans skill is designed to consume. The two systems target different layers of the same problem.
9a. π οΈ The Best Way to Combine Both β A Practical Guide
The mental model in one sentence:
Spec Kit plans WHAT to build. Superpowers controls HOW it gets built.
Spec Kit gives you durable, human-readable artifacts (constitution β spec β plan β tasks). Superpowers takes those tasks and executes them with TDD, worktrees, subagents, and review baked in. You hand off at the task list.
βοΈ One-time setup (do this once per machine + once per repo)
On your machine:
- Install Spec Kit:
uv tool install specify-cli --from git+https://github.com/github/spec-kit.git
- Install Superpowers in your agent host. For Claude Code:
/plugin install superpowers@claude-plugins-official
In your repo (once):
- Initialize Spec Kit with your agent:
specify init --integration claude-code(or whichever agent you use). - Run
/speckit.constitutiononce to set project-wide rules. Add a single line that bridges the two systems: > "Implementation of any task list MUST follow the Superpowers workflow: worktree β TDD (red-green-refactor) β subagent-driven execution β code review β finish-branch." - Commit
.specify/to the repo. Add.claude/(or your host's plugin dir) per your team's policy.
That's the entire setup. From here on, every feature follows the same loop.
π The per-feature loop (the one you actually use)
Run these in order. Each step is a single command or short prompt.
| Step | Tool | Command / Prompt | What you get |
|---|---|---|---|
| 1 | Superpowers |
"Let's brainstorm: I want to add X." (triggers brainstorming skill) |
Clarified idea, alternatives considered |
| 2 | Spec Kit | /speckit.specify |
specs/<id>/spec.md β the requirements |
| 3 | Spec Kit | /speckit.clarify |
Open questions resolved |
| 4 | Spec Kit | /speckit.plan |
specs/<id>/plan.md β technical approach |
| 5 | Spec Kit | /speckit.tasks |
specs/<id>/tasks.md β ordered, small tasks |
| 6 | Superpowers |
"Use git worktree for this feature." (triggers using-git-worktrees) |
Isolated branch with green test baseline |
| 7 | Superpowers | "Execute specs/<id>/tasks.md using subagent-driven development with TDD." |
Code, written test-first, one subagent per task |
| 8 | Superpowers |
"Request code review." (triggers requesting-code-review) |
Severity-tagged punch list |
| 9 | Superpowers |
"Finish the development branch." (triggers finishing-a-development-branch) |
PR opened or merged + cleanup |
That's it. Spec Kit owns steps 2β5. Superpowers owns steps 1, 6β9. The handoff happens at tasks.md.
π The two non-obvious rules that make this combo work
Rule 1 β Don't skip /speckit.tasks, even when you're tempted.
Superpowers' executing-plans skill is designed to consume small (2β5 minute) tasks. Spec Kit's /speckit.tasks produces exactly that shape. Skipping it forces Superpowers to break the work down at execution time, which is slower and lower quality.
Rule 2 β Don't let Superpowers re-plan what Spec Kit already planned.
When you start step 7, explicitly say: "The plan is already in specs/<id>/tasks.md. Don't re-plan β execute." Otherwise Superpowers' writing-plans skill may auto-fire and duplicate work.
π One-line prompt template for the execution handoff
Paste this when you're ready to switch from Spec Kit (planning) to Superpowers (execution):
Execute specs/<feature-id>/tasks.md using the Superpowers workflow:
create a worktree, follow strict TDD per task, dispatch one subagent per
task, run code review at the end, then finish the branch. Do not re-plan β
the task list is the contract.
π When to scale down (don't over-engineer small work)
For a one-line bug fix or a typo, both frameworks are overkill. A reasonable size cutoff:
| Task size | Use |
|---|---|
| < 30 minutes, < 3 files | Just prompt directly. Skip both. |
| 30 min β 2 hours, single concern | Superpowers only β brainstorm + TDD + finish-branch |
| > 2 hours, multi-component, or shipped to users | Both β full Spec Kit planning, then Superpowers execution |
| Anything regulated / audited | Both, mandatory β the spec trail is part of compliance |
π« Anti-patterns to avoid
- β Running
/speckit.implementAND Superpowers. Pick one for execution./speckit.implementis Spec Kit's own executor; Superpowers replaces it for this combo. - β Editing code without updating the spec. If reality diverges from
spec.md, your audit trail dies. Re-run/speckit.specifyfor the changed area. - β Letting subagents read the whole
.specify/tree. Pass them only the specific task they're executing β context discipline still matters. - β Skipping the constitution. Without it, Superpowers and Spec Kit each impose their own defaults and you'll feel the friction.
β A 60-second mental checklist before starting any feature
- Is there a spec? If no β
/speckit.specify. - Are tasks small and ordered? If no β
/speckit.tasks. - Am I on a worktree with green tests? If no β trigger
using-git-worktrees. - Did I tell the agent "don't re-plan, execute"? If no β say it now.
- Will I review the PR diff myself before merging? If no β stop.
If all five are yes, you're using the combo correctly.
10. π§ Quick Decision Guide
π Pick Spec Kit if youβ¦
- Want specs as durable, reviewable artifacts
- Need cross-stack portability (regenerate same spec β different language)
- Work in an environment where PRDs/RFCs are already a norm
- Value broad agent compatibility (30+ tools)
- Want a GitHub-backed, enterprise-friendly project
π¦Έ Pick Superpowers if youβ¦
- Want the agent itself to behave more like a senior engineer
- Need strict TDD, worktree isolation, subagent orchestration out of the box
- Run long, autonomous sessions and need guardrails
- Prefer auto-triggered skills over user-invoked commands
- Want a writable, composable skill system you can extend yourself
π€ Pick both if youβ¦
- Want artifact-driven planning + workflow-driven execution
- Are willing to invest in setup for a more rigorous overall pipeline
11. π At-a-Glance Summary
| Dimension | Spec Kit | Superpowers |
|---|---|---|
| Owner | GitHub | Jesse Vincent / Prime Radiant |
| Methodology | Spec-Driven Development | Agentic SDLC w/ enforced workflow |
| Primary unit | Slash command + spec template | Auto-triggered skill |
| Trigger model | User-invoked | Context-matched |
| Output | Spec β plan β tasks β code | Branch + tests + code + review |
| TDD enforcement | Optional | Mandatory (built-in skill) |
| Subagent orchestration | Not core | First-class |
| Worktree management | Not core | First-class |
| Constitution / governance | Built-in (/speckit.constitution) |
Not core |
| Stack swapping | Strong (regen from spec) | Weak (workflow is stack-agnostic but no regen) |
| Agent reach | 30+ agents | ~6 first-class hosts |
| Install | uv tool install |
Plugin marketplace per host |
| Extensibility | Extensions + presets (catalog) | Skills (author-it-yourself) |
| Best fit | Greenfield, brownfield, regulated work | Long autonomous sessions, parallel agents |
| License | MIT | MIT |
Generated 2026-04-25. Both projects are evolving rapidly β verify version-specific details against their READMEs before adopting.
If you found this helpful, let me know by leaving a π or a comment!, or if you think this post could help someone, feel free to share it! Thank you very much! π
Top comments (2)
Really useful breakdown, especially the βwhen to pick whichβ part. Iβve been writing about Spec Kit and Iβm about to compare it with BMAD. Did you ever track token usage per workflow? Iβm thinking of using it as a consumption metric. Any thoughts?
Hello @rosidotidev , thank you for your feedback and sharing, regarding to token usage tracking you can have a look this project (particularly track-tokens.sh script there) to see the approach being applied, hope that helps github.com/truongpx396/supspec-orc...