Metadata-Version: 2.4
Name: framework-chief
Version: 0.1.0
Summary: Decides and installs the right spec-driven-development framework stack for Claude Code, Codex, and Copilot
Project-URL: Repository, https://github.com/lucasmadrid/framework-chief
License: MIT
License-File: LICENSE
Keywords: ai,claude,codex,copilot,framework,spec-driven-development
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Requires-Python: >=3.11
Requires-Dist: pydantic>=2.0
Requires-Dist: pyyaml>=6.0
Requires-Dist: rich>=13
Description-Content-Type: text/markdown

<p align="center"><img src="docs/assets/header.svg" alt="Framework Chief"/></p>

<p align="center">
  <a href="https://github.com/LucasMadrid/framework-chief/actions/workflows/ci.yml"><img src="https://github.com/LucasMadrid/framework-chief/actions/workflows/ci.yml/badge.svg" alt="CI"/></a>
  <a href="https://github.com/LucasMadrid/framework-chief/actions/workflows/routing-eval.yml"><img src="https://github.com/LucasMadrid/framework-chief/actions/workflows/routing-eval.yml/badge.svg" alt="Routing Eval"/></a>
  <a href="https://www.python.org/downloads/"><img src="https://img.shields.io/badge/python-3.11%2B-blue" alt="Python 3.11+"/></a>
  <img src="https://img.shields.io/badge/license-MIT-green" alt="MIT License"/>
  <a href="https://github.com/astral-sh/uv"><img src="https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/uv/main/assets/badge/v0.json" alt="uv"/></a>
</p>

> **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:

```bash
uvx framework-chief init .
```

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

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

Then in any project:

```bash
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](#what-it-looks-like).

### 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.

<details>
<summary>Advanced CLI (power users)</summary>

```bash
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)
```

</details>

## 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](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".

<p align="center"><img src="docs/assets/decision-flow.svg" alt="Decision loop"/></p>

- **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.** 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 only executable surface is `chief-sync.sh` and the
install commands the chief shells out to, all of which already exist upstream.

**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](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](https://github.com/github/spec-kit) ·
[OpenSpec](https://github.com/Fission-AI/OpenSpec) ·
[BMAD-METHOD](https://github.com/bmad-code-org/BMAD-METHOD) ·
[GSD-2](https://github.com/gsd-build/GSD-2) ·
[Superpowers](https://github.com/obra/superpowers)
