# Spec-Framework Bootstrap — agent instructions

**You are an AI agent. A human dropped this file into a project's working directory and asked you to set up its documentation/specification framework.** This file tells you the framework to build and the interview to run first. Follow it top to bottom.

The project may be **greenfield** (no code yet) or an **existing codebase** (often with little or no documentation). The humans may be a dev team, project managers, business analysts, or an owner. The framework below adapts to all of them.

> **The framework structure is fixed and opinionated. Do not "improve", simplify, or re-architect it.** It is the product of a deliberate design pass. The interview tailors *content and a few toggles* — never the shape. If you think you have a better structure, you are wrong here; build this one.

---

## What this framework is (one paragraph)

A lightweight, in-repo knowledge system. **Three layers, fixed:** `sources/` = immutable raw inputs (never hand-edited for meaning); `specs/` = curated, human-approved module pages that are the source of truth; `decisions/` = ADRs, one immutable file per decision. Every rule in a spec traces back to a source or an ADR via inline tags. One `index.md` is the dashboard. Retrieval is `grep` + the index — **no RAG, no vector store, no embeddings** (unnecessary at a single project's scale; the point is compounding, human-readable synthesis). It borrows the immutable-sources-vs-curated-pages split from Karpathy's "LLM wiki" but **inverts his AI-owns-the-wiki rule**: here specs need human sign-off — the AI drafts, the human approves.

---

## How to proceed (4 phases — do them in order)

### Phase 0 — Recon (before asking anything)
Silently inspect the repo so your questions are informed, not generic:
- Greenfield or existing? (look for source dirs, package manifests, git history depth)
- Detect stack/domain from the codebase.
- Find any existing docs (`README`, `docs/`, wikis, `*.md` at root, design files).
- Find any existing findings/audit/issues lists, decision logs, meeting notes — candidate `sources/`.
- Infer the likely **modules** (major product areas) from routes, folders, or domain terms.
Bring these inferences into the interview as proposed defaults.

### Phase 1 — Interview (ask before building)
Ask the human the questions in **§ Interview** below. Present them as one batch, grouped, each with a sensible default drawn from Phase 0 so they can answer fast or say "defaults are fine." Do **not** scaffold until answered. If a tool for structured questions is available, use it; otherwise ask in plain text.

### Phase 2 — Scaffold
Using the answers, create the structure in **§ The fixed structure** with the templates in **§ Templates**. Specifically:
1. Create `docs/sources/`, `docs/specs/`, `docs/specs/_platform/`, `docs/decisions/`. (Use the framework root they chose; default `docs/`.)
2. Move/copy any existing raw inputs into `sources/` (use `git mv` for tracked files). Add placeholder pointers for inputs that don't exist yet (e.g. a decision-log export, a survey).
3. If a findings/issues list with stable IDs exists, **reuse those IDs as trace anchors** — do not invent new ones. Map each finding to exactly one primary module page.
4. Create one `specs/<module>.md` per module (+ `_platform/` cross-cutting pages they selected), each pre-seeded with the **Approved rules / Open to resolve / Edge cases & invariants / Sources** shape, and any assigned findings listed under "Open to resolve."
5. Write one ADR per non-negotiable decision they gave you (Nygard format, `Accepted`).
6. Generate `index.md` — the dashboard (sources list, module + finding tracker with a grep coverage audit, open-questions pointer).
7. Add the framework rules + moved paths to the repo's agent-instructions file (`AGENTS.md` / `CLAUDE.md`, create if absent) so future agents follow it.

### Phase 3 — Handoff
Do **not** rewrite the existing specs/README into module pages yet — that's the human's module-by-module work. Report what you created, the finding/module counts, and the exact next step: "pick a module page, write rules, tag origins, flip the tracker."

---

## The fixed structure

```
<docs-root>/                         # default: docs/
  PRODUCT-SPEC.md  TECH-SPEC.md      # keep any existing top-level specs as overview/truth until module pages mature
  index.md                           # the one dashboard
  sources/                           # IMMUTABLE raw inputs — append-only, never hand-edited for meaning
    <research / findings / audits / decision-log export / survey replies / meeting notes>
  specs/                             # CURATED, one page per module — the approved source of truth
    <module>.md ...
    _platform/                       # cross-cutting pages (only the ones the project needs)
      security-authz.md data-integrity.md privacy-<regime>.md ops-reliability.md
  decisions/                         # ADRs — one immutable file per decision
    0000-template.md
    NNNN-<kebab-title>.md
```

**Rules that never change:**
- **Sources are immutable.** Inputs land here verbatim and are never edited for meaning (typo/format fixes only). Everything else traces back to them.
- **Specs are human-approved.** The AI drafts; a named human signs off. An Accepted module page is **authoritative for its module** — at that point the matching section in any top-level spec is trimmed to a one-line pointer (so each fact lives in exactly one place).
- **Decisions are ADRs, immutable once Accepted.** Changing a decision = a new ADR that supersedes the old one. Never silently edit an Accepted ADR.
- **Traceability is inline tags, no matrix file.** Every spec rule tags its origin: `(PRODUCT-SPEC §x)`, `(resolves <FindingID>)`, `(ADR-NNNN)`. Audit coverage with grep.
- **Doc concision.** Specs are comprehensive but maximally terse: state each fact exactly once, no filler words/sentences/paragraphs, no duplication across pages. Comprehensive ≠ verbose.
- **No RAG.** `grep` + `index.md` is the retrieval layer. Do not add embeddings/vector tooling.

---

## Interview (ask these — ~16 questions, grouped)

Mark each with the default you inferred in Phase 0. Accept "defaults are fine" for any group.

**A. Project & people**
1. One line: what is this project / product?
2. Greenfield or existing codebase? (confirm your Phase-0 guess)
3. Who has **sign-off authority** on specs and decisions? (name/role — this is the approver in every ADR and page header)
4. Who is the **audience** for these docs? (dev team / PMs / BAs / clients / mixed) — affects whether `_platform/` privacy & client pages matter.

**B. Existing inputs → sources/**
5. What raw inputs exist to seed `sources/`? (research notes, a requirements doc, an audit/stress-test, a decision log or sheet, meeting transcripts, ticket exports). Point me at them.
6. Is there a **findings/issues list with stable IDs** already? If yes, I'll reuse those IDs as trace anchors instead of inventing new ones.
7. Any inputs that *will* exist later but don't yet? (I'll leave placeholder pointers.)

**C. Modules (the spec pages)**
8. What are the **major modules / areas** of the product? (I propose these from the codebase: `<list>`. Edit the list.)
9. Which **cross-cutting `_platform/` pages** apply? Options: security-authz, data-integrity, privacy/compliance, ops-reliability. (Default: include the ones your domain clearly needs; skip the rest.)
10. Any **compliance/privacy regime** in scope (GDPR, HIPAA, SOC2, none)? Names the privacy page and seeds its open items.

**D. Decisions → ADRs**
11. What **non-negotiable decisions** are already made and shouldn't be relitigated? Each becomes a seeded ADR. (I'll also scan existing docs for these.)
12. Any decisions currently **open/contested**? I'll log them as open questions, not ADRs.

**E. Conventions & toggles** (safe defaults shown — change only if needed)
13. Docs root folder? (**default `docs/`**)
14. Truth model: **module-page-wins** (approved page becomes authoritative; top-level spec section trimmed to a pointer) — *recommended default* — or monolith-stays-authoritative (module pages are working drafts folded back into one big spec)?
15. ADR numbering start and language? (**default: `0001`, English**)
16. Apply the **doc-concision rule**? (**default: yes**)

---

## Skip as overengineering (guardrails — don't add these)
- GitHub Spec Kit `.specify/` machinery, a separate `constitution.md`, per-feature `research.md`/`contracts/`/`quickstart.md` folders.
- EARS notation ("WHEN…THEN the system SHALL…") — prose rules are fine.
- RAG / vector DB / embeddings.
- A formal traceability matrix file — inline tags + grep replace it.
- Pure "AI maintains the wiki" autonomy — specs need human sign-off.
- Shattering existing specs into dozens of micro-files on day one — module pages take over a section only as they mature.
- ADRs for trivial/reversible calls — only non-negotiables and decisions worth citing later.
- Spec'ing tiny features or bug fixes.

---

## Templates (copy-paste; adapt names, not shape)

### `docs/decisions/0000-template.md`
```markdown
# ADR-0000: <title>
Status: Proposed | Accepted | Superseded by ADR-NNNN
Date: YYYY-MM-DD

## Context
Why this came up; the forces. Cite source: `(<FindingID>)`, `<SPEC> §x`.

## Decision
The call, stated once.

## Consequences
What this makes easy/hard; what it forecloses. Edits after Accepted = typos/links only; a changed decision is a NEW ADR that supersedes this one.
```

### `docs/specs/<module>.md`
```markdown
# <Module> — module spec
Status: ☐ not started | ◐ drafting | ☑ approved · Owner: <approver> · Supersedes: <SPEC §x refs>

## Approved rules
_Written rule-by-rule. Each rule tags its origin: `(<SPEC> §x)`, `(resolves <FindingID>)`, `(ADR-NNNN)`. No fact stated twice across pages._

## Open / to resolve
- [ ] **<FindingID>** (<severity>) — <one-line problem>. → <recommended direction>

## Edge cases & invariants
_Filled as decided._

## Sources
`sources/<file>` (<FindingIDs>) · <SPEC §x refs>
```

### `docs/index.md`
```markdown
# <Project> — spec index & finding tracker
> The one dashboard. Sources = immutable inputs; spec pages = curated approved truth; decisions/ = ADRs.
> Truth model: an approved module page is authoritative for its module; the matching top-level §section is trimmed to a pointer.

## Sources (immutable — append-only)
- `sources/<file>` — <what it is>
  ...

## Finding processing — 0 / <N> resolved
Severity totals: <...>. Legend: ☐ unprocessed · ◐ drafting · ☑ resolved (rule written + traced).

| Module page | Findings (by severity) | Done |
|---|---|---|
| `specs/<module>.md` | ☐<ID> ☐<ID> ... | 0/<n> |
| ...

*Coverage audit:* `grep -roh '<ID-pattern>' docs/specs | sort -u | wc -l` vs <N>. A finding is done when its page states the rule and tags `(resolves <ID>)`.

## Open questions (<N>)
Resolve each into an ADR or a module rule. Tracked there; not duplicated here.
```

### Agent-instructions snippet to add to `AGENTS.md` / `CLAUDE.md`
```markdown
## Docs framework
- `docs/specs/<module>.md` — curated per-module specs; an Accepted page is authoritative for its module (top-level §section trimmed to a pointer).
- `docs/decisions/NNNN-*.md` — ADRs; Accepted = immutable, supersede don't edit.
- `docs/sources/` — immutable raw inputs; append-only; every spec rule traces back here.
- `docs/index.md` — dashboard: module list + finding tracker + open questions.
- Flow: source → rule on a module page → ADR if it's a real decision. Tag every rule: `(<SPEC> §x)`, `(resolves <ID>)`, `(ADR-NNNN)`.
- Doc concision: comprehensive but maximally terse; each fact once; no duplication. No RAG — grep + index.md is retrieval.
```
```
