specframe

<div align="center">

# specframe

**Decision-driven scaffolding for AI-ready repos.**

[![npm version](https://img.shields.io/npm/v/specframe.svg)](https://www.npmjs.com/package/specframe)
[![npm downloads](https://img.shields.io/npm/dm/specframe.svg)](https://www.npmjs.com/package/specframe)
[![node](https://img.shields.io/badge/node-%3E%3D18-brightgreen)](https://nodejs.org)
[![dependencies](https://img.shields.io/badge/dependencies-zero-brightgreen.svg)](#)
[![license: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)

*Zero install. Zero config. Zero lock-in. Run it in any repo and answer a few prompts.*

</div>

---

## The repo is the spec

Most repos accumulate context by accident — a `CLAUDE.md` here, an `AGENTS.md` there, a stray ADR, half a convention buried in a PR thread. The result is **drift**: agents guess, decisions get lost, and six months in nobody remembers *why* the code looks the way it does.

**specframe flips that around.** It scaffolds a decision-first structure in seconds and wires every agent's tooling to it: your decisions, rules, conventions, runbooks and glossary *are* the source of truth.

- 🎯 **Decision-driven.** ADRs capture *what & why*, rules *what's non-negotiable*, guidelines *how you build*. Agents read intent instead of reverse-engineering it.
- 🧭 **Three ways in.** A **blank** log with every template; a **guided** pass where each answer becomes an ADR plus the rules it implies; or a **blueprint** — the architecture you already have in mind, walked as that same pass. Skip a section with one key; what you skip stays open.
- 🏗️ **Works on existing repos.** `/specframe-bootstrap` reconstructs the log from code you already shipped, citing `path:line` and leaving what it can't prove open.
- 📌 **One source of truth.** `AGENTS.md` + `docs/` are canonical; every agent's native config points back at them. Claude, Copilot and Codex get subagents, commands and skills in each tool's *current* convention; Cursor, Windsurf, Zed, Roo Code, Kiro, Junie, Devin and Jules read `AGENTS.md` natively.
- 🧩 **Complements your spec/plan harness** rather than competing with it: specframe owns the layer Spec Kit, BMAD and OpenSpec leave empty — [the decision that outlives the change](#working-alongside-a-specplan-harness).
- 🛡️ **Safe by design.** Idempotent, re-runnable, zero dependencies, and it **never overwrites your files**: a manifest tracks what was generated, so updates stay surgical.

---

## The structure

Every section answers exactly one question, the same way for humans and agents:

| Section | Answers | Contains |
| --- | --- | --- |
| `docs/adr/` | *What did we decide, and why?* | Architecture Decision Records: context, options, trade-offs. |
| `docs/rules/` | *What's non-negotiable?* | Hard constraints: security, compliance, invariants. |
| `docs/guidelines/` | *How do we usually build this?* | Conventions and patterns to follow by default. |
| `docs/runbook/` | *What do we do when it breaks?* | Diagnostics and recovery procedures. |
| `docs/glossary/` | *What do words mean here?* | Domain terms, grouped by area. |
| `docs/DECISIONS.md` | *What haven't we decided — or ruled out?* | The open backlog, each with a reserved ADR number, plus what's dismissed as not applicable. |
| `docs/README.md` | *What goes where?* | When to write a rule vs a guideline vs an ADR. |
| `AGENTS.md` | *Where do I find all of this?* | The canonical index every agent reads first. |

`DECISIONS.md` closes the loop the others leave open: an agent asked to add persistence to a repo that never chose a persistence model will pick one, silently, in a diff. Listing that decision as open makes it a question instead of an accident.

---

## Quick start

```bash
npx specframe                # run without installing
# or
npm install -g specframe     # then: specframe
```

Requires **Node.js ≥ 18**. specframe always scaffolds at the **repo root** (nearest ancestor with `.git`), even from a deep subdirectory; with no `.git` it warns and falls back to the current folder. Ran it only through `npx`? The scaffolded skills fall back to `npx --yes specframe` rather than writing an ADR by hand.

On a terminal, bare `specframe` in a repo it hasn't scaffolded yet opens a one-line menu first — a summary of what onboarding does, with **Start onboarding** the only row — rather than dropping straight into the wizard; `specframe init` skips that and goes straight in. Off a terminal, or with `-y`, both act the same.

After the project name, package manager and agent assistants, you pick one of **three ways in**.

### Blank — templates only

Every section index, a `0000-template.md` with field-by-field instructions, a worked example per section, `docs/README.md` explaining what belongs where, and `docs/DECISIONS.md` listing the whole catalog as open — each entry with its options and a reserved ADR number. Nothing decided for you, nothing left to guess about *how* to decide.

### Blueprint — start from a known a

... (truncated)