framework-chief 0.2.0

Decides and installs the right spec-driven-development framework stack for Claude Code, Codex, and Copilot

Decides and installs the right spec-driven-development framework stack — for Claude Code, Codex, and Copilot.

A lightweight meta-layer that classifies a request, recommends the right spec-driven-development framework (or hybrid stack), and installs it behind a human confirmation gate. It knows how spec-kit, OpenSpec, BMAD, GSD-2, and Superpowers compose — and how they don't.

It does not orchestrate the framework it picks. It decides, installs, and hands off.

---

The problem

You open a repo. There's a CLAUDE.md, a .specify/, half an openspec/, and someone mentioned Superpowers in standup. Five spec-driven-development frameworks exist, they all sound similar, and the usual outcome is ceremony mismatch — running a seven-phase spec flow on a ten-line bugfix, or stacking two frameworks that quietly fight for the same phases.

The frameworks aren't interchangeable. They occupy three different slots, and most pairs collide. Picking well is a real decision — so framework-chief makes it a deliberate one.

What it looks like

You describe what you're building. The chief classifies it, asks one question if it's unsure, shows you exactly what will be installed and why, and waits for a "yes" before touching anything.

> /chief
I want to add audit-trail compliance to an existing Node API.
Three devs, brownfield, we need sign-off artifacts per feature.

Chief:  Verdict: spec-kit + brownfield extension. High confidence.
        Brownfield + audit traceability is spec-kit's strongest case.

        Stack:         spec-kit (Plan/Spec slot)
        Extension:     brownfield
        Install order: spec-kit → brownfield extension
        Commands:
          specify install
          specify extension add brownfield

        Confirm? (yes / no, but…)

> yes

[prereqs ok — node 20.19, git 2.39]
[spec-kit: installing…  done]
[brownfield extension: installing…  done]
[decision logged → .chief/decision.md]

Hand-off: start with /spec to capture the existing system's state.

The chief then steps back. It does not run /spec for you.

Get started

Prerequisites

Requirement	Why
Python 3.11+ and uv	framework-chief CLI
git	project detection and decision log
Node 20+	only when installing spec-kit, OpenSpec, or BMAD

1. Add framework-chief to your project

No persistent install needed — run it directly in any project:

uvx framework-chief init .

If you use it regularly, install the chief CLI once:

uv tool install framework-chief   # recommended
pip install framework-chief        # pip also works

Then in any project:

chief init .

chief init copies AGENTS.md, .chief/ (adapters + composition blocks), and scripts/ into your project, and wires every agent automatically:

Agent	How it's wired
Claude Code	CLAUDE.md symlink + /chief slash command
Copilot	.github/copilot-instructions.md pointer
Codex	reads AGENTS.md natively

All idempotent — safe to re-run after updating.

2. Describe what you're building

Open your agent and invoke the chief:

• Claude Code / Codex: type /chief, then describe what you're building
• Copilot: ask a framework-selection question — it reads AGENTS.md directly

The chief classifies, asks one clarifying question if confidence is low, and presents the gate: stack, rationale, and exact commands. See the example above.

3. Confirm — the chief installs and steps back

Type yes. The chief checks prereqs, installs each framework in the agreed order, writes any composition blocks for hybrids, appends to the decision log, and hands off. It does not run the chosen framework's workflow — that's yours to start.

Advanced CLI (power users)

chief sync                           # re-wire agents after moving or updating AGENTS.md
chief dry-run openspec-superpowers   # preview the exact install sequence without running it
chief check spec-kit                 # verify prereqs before installing
chief install openspec               # run one framework's install directly (after the gate)
chief log stack=openspec date=2026-05-19  # append a structured entry to .chief/decision.md

chief route — conversational routing outside an agent session

Describe your project from the terminal and get a stack recommendation without opening an agent. Requires the [route] extra and an API key:

pip install 'framework-chief[route]'
export ANTHROPIC_API_KEY=sk-...        # or OPENAI_API_KEY / GITHUB_TOKEN
chief route                            # interactive — prompts for project description
chief route "greenfield SaaS, need audit trail per feature"  # one-shot
chief route --provider openai          # use GPT-4o instead
chief route --provider github          # use GitHub Copilot via GitHub Models

chief compose — write a hybrid composition block

Appends the demotion block for a hybrid stack to your project's AGENTS.md. The agent session does this automatically during INSTALL; this command is for manual or scripted use:

chief compose openspec-superpowers .   # write the demotion block for OpenSpec + Superpowers
chief compose bmad-superpowers . --request-summary "greenfield SaaS with role handoffs"

What lands in your project

After chief init ., your project gets:

your-project/
├── AGENTS.md                        the router — single source of truth for all agents
├── CLAUDE.md → AGENTS.md           symlink — Claude Code reads this
├── .chief/
│   ├── adapters/                    per-framework: prereqs, detection, install commands
│   │   ├── spec-kit.md
│   │   ├── openspec.md
│   │   ├── bmad.md
│   │   ├── superpowers.md
│   │   └── gsd2.md
│   ├── composition-blocks/          demotion blocks for hybrid stacks
│   │   ├── openspec-superpowers.md  the model pair (GREEN)
│   │   └── bmad-superpowers.md      the advanced pair (YELLOW)
│   └── decision.md                  append-only audit log of every install event
├── .github/
│   └── copilot-instructions.md      pointer — Copilot reads this
└── scripts/
    ├── chief-install.sh             prereq checks, dry-run, install, log subcommands
    └── chief-sync.sh               re-wires agents after AGENTS.md changes

Nothing else. The chief does not scaffold your application or add framework files — those come from the frameworks themselves after the gate passes.

See CONTRIBUTING.md for the full repository structure.

---

The five frameworks

The chief picks between these. One sentence on each so the routing table makes sense:

Framework	What it does	Pick it when
spec-kit	Spec-first workflow: intent → requirements → architecture → stories → tasks. Extensions add brownfield audit, full lifecycle, retro-spec, and more.	Governance, regulatory traceability, multi-artifact sign-off, or any greenfield with rigor needs.
OpenSpec	Lightweight spec layer: request → spec → tasks. Minimal ceremony.	Brownfield, well-scoped features, fast iteration — no governance overhead needed.
BMAD	Full lifecycle rail with role personas: brainstorm → plan → architecture → code → review. Forces each phase.	Multi-role discovery, heavy process discipline, full lifecycle with explicit persona handoffs.
GSD-2	Autonomous execution CLI that reads a pre-seeded context tree (.gsd/). Runs separately, not inside an agent.	Long autonomous builds; typically receives spec-kit's output via the ingestion handoff.
Superpowers	Discipline add-on: enforces TDD, code review protocol, and debugging structure on each unit of work.	Composable with one Plan/Spec layer when you want testing discipline enforced, not just planned.

The model in 30 seconds

Three slots, not one pick:

Slot	Owns	Candidates
Plan/Spec	intent → spec → tasks	spec-kit, OpenSpec, BMAD — pick exactly one
Execute	running tasks → code	GSD-2, or the bare agent
Discipline	how each unit of work is done — TDD, review, debugging	Superpowers

The non-obvious parts:

• spec-kit, OpenSpec, and BMAD all claim the Plan/Spec slot. Two of them means two sets of slash commands and colliding artifact conventions. Never compose them.
• Superpowers and BMAD aren't "layers" — they're full rails. Each runs its own brainstorm → plan → execute flow and forces the next phase. Composing either with a separate Plan/Spec layer needs a bridge — without one, two rails fight for the planning phases.
• Extensions can change a routing decision. spec-kit's fleet, canon, brownfield, and ralph extensions are routing-relevant — they make spec-kit the right answer for cases that would otherwise go to BMAD (lifecycle structure), OpenSpec (brownfield), or GSD-2 (lightweight automation). The chief surfaces them at the classify stage, not as post-install add-ons.

What composes — the verified matrix

Checked against the five projects' actual task templates, skill files, and workflow docs — not just their READMEs.

Combination	Verdict	Note
OpenSpec + Superpowers	🟢 GREEN	The model pair. Lowest ceremony that still enforces testing.
BMAD + Superpowers	🟡 YELLOW	Works, but you surgically disable half of each rail. Advanced.
spec-kit → GSD-2	🟡 YELLOW	Not a running stack — a one-directional migration handoff.
spec-kit + Superpowers	🟡 YELLOW	Discouraged — spec-kit already enforces TDD + code review natively via its constitution and native extensions (Review, SpecTest, QA Testing). If the user insists, use the community Superpowers Bridge extension (specify extension add superpowers-bridge), not a manual demotion block.
spec-kit ⇄ OpenSpec ⇄ BMAD	🔴 RED	Same slot. Namespace collision. Never.
GSD-2 + Superpowers	🔴 RED	Both own the execution harness. Conflict.
GSD-2 co-running with any Plan/Spec layer	🔴 RED	GSD-2 reads only its own .gsd/ tree. Handoff only.

Default bias: a single clean rail beats a hybrid. The chief only proposes a hybrid when the request genuinely needs both planning structure and enforced execution discipline.

The routing rubric

The chief classifies the request against this table and produces a verdict + confidence read:

Request shape	Route to
Tiny/local change, bugfix, single file	No framework — direct, or Superpowers' discipline skills only
Well-scoped feature, brownfield, fast iteration	OpenSpec (+ Superpowers discipline subset)
Brownfield, needs audit/regulatory traceability or multi-artifact sign-off	spec-kit + brownfield extension (or + brownkit if security/QA risk surface unknown)
Greenfield, governance / regulatory traceability / multi-artifact	spec-kit
Process & role discipline, multi-role discovery, full lifecycle with persona handoffs	BMAD (+ Superpowers discipline subset)
Full lifecycle structure without multi-role persona discipline	spec-kit + fleet extension (monorepos/V-Model: + product-forge)
Has working code, wants to retrofit spec coverage or detect spec drift	spec-kit + canon extension
Long autonomous build, separate CLI	GSD-2 — recommend only, user installs
Clean specs already, wants hands-off execution	spec-kit → GSD-2 handoff

When two rows are both plausible, the chief drops into a single discriminating question rather than a generic intake form. Hard cap: 4 clarify iterations, then the user picks.

The loop

framework-chief runs a classify → clarify → agree → install loop with exactly one human gate. Nothing installs before "yes".

• Classify — run the rubric, produce a verdict and a confidence read.
• Clarify — only when confidence is low. Ask the single discriminating question that would move the verdict, fold the answer back into classify. Capped at 4 iterations; the user can say "just pick" to escape anytime.
• Agree — the gate. State the stack, install order, exact commands, and any composition block. Wait for an explicit "yes". "No, but…" routes back to clarify.
• Install — per-framework adapters check prerequisites and existing installs, run the install commands, write composition blocks for hybrids, and append to the decision log.

The bridges

Friction between hybrids isn't uniform, so the bridges aren't either:

1. Demotion block — for OpenSpec + Superpowers and BMAD + Superpowers. Two rails want the planning phases; the bridge is a generated AGENTS.md block that turns the contended skills OFF and leaves the discipline subset ON. It works because Superpowers' own rule says user instructions in AGENTS.md outrank skills.
2. Ingestion handoff — for spec-kit → GSD-2. They can't co-run; GSD-2 reads only its own .gsd/ tree. The bridge pre-seeds GSD-2's startup files (.gsd/REQUIREMENTS.md, .gsd/PROJECT.md, .gsd/KNOWLEDGE.md, .gsd/RUNTIME.md) from spec-kit's artifacts before the first GSD-2 session. Once the database is populated, spec-kit is done.

(A format-transform shim between a spec layer's tasks and Superpowers' plan format was considered and deliberately not built — a transform between two independently-evolving tools rots silently. The demotion block's re-plan approach replaces it.)

Why "chief"

Because the job isn't to do the spec-driven development — it's to walk in, size up the work, decide what tools the job needs, and get them set up. Then it steps back. A good chief doesn't pick up the hammer.

Status

v0.1. The compatibility matrix and bridge design are verified against the five projects' actual internals. The loop, gate, and composition blocks are instruction-level — they live in AGENTS.md and the block files.

The Python CLI (pip install framework-chief) covers the full surface: init, sync, dry-run, check, install, log, compose, and route. chief route makes real AI API calls (Anthropic, OpenAI, or GitHub Models) and requires the [route] extra. chief compose writes composition blocks atomically to AGENTS.md. The shell scripts (chief-install.sh, chief-sync.sh) are bundled data — the CLI delegates to them.

Two seams to watch when you integrate it:

• The composition blocks demote Superpowers skills by name. Superpowers renames and consolidates skills between versions — each block now has superpowers_version (and bmad_version for the BMAD pair) fields to fill in at install time, making a version mismatch visible instead of silent. A mismatched skill name is silently ignored, not an error, so the version field is the only signal that a block is stale.
• The writing-plans re-pointing is an instruction, not enforced wiring. It relies on the agent honoring the AGENTS.md block over the skill's default — exactly the priority rule Superpowers documents, but the spot most worth watching in a real run.

See CONTRIBUTING.md for test architecture, routing eval harness usage, and CI details.

Credits

framework-chief is a router over five independent projects — it installs and composes them, it doesn't replace them. Go star the originals: spec-kit · OpenSpec · BMAD-METHOD · GSD-2 · Superpowers