claude-blueprint 1.0.0

package/commands/init.md

@@ -0,0 +1,229 @@
+---
+name: blueprint:init
+description: >
+  Bootstrap blueprint onto an existing codebase. Scans for existing architecture context
+  (.planning/, .research/, CLAUDE.md, existing code, git history), creates the ADR directory
+  with template and lifecycle docs, infers ADRs from discovered decisions, and generates
+  ARCHITECTURE.md. Use when: starting blueprint on a new project, "init blueprint",
+  "bootstrap adrs", "set up architecture docs", "onboard blueprint", or first time using
+  blueprint in a project.
+---
+
+# Initialize Blueprint
+
+Bootstraps the full blueprint documentation system onto an existing codebase. Scans every
+available source of architectural context and produces:
+
+1. **ADR directory** with template, lifecycle README, and index
+2. **Inferred ADRs** from existing decisions found in the codebase
+3. **ARCHITECTURE.md** via the architect-cartographer agent
+4. **Populated config** (state.toml with detected paths, relationships.toml seeded)
+
+This is a one-time setup command. If `docs/adr/` already exists with ADRs, suggest
+`/blueprint:help` instead.
+
+## Process
+
+### Step 1: Detect Existing Context
+
+Scan the project root for every source of architectural decisions. Cast a wide net —
+the goal is to find decisions that were made but never formally documented.
+
+**Scan these locations (in order of richness):**
+
+```
+.planning/PROJECT.md          — GSD project context, key decisions table
+.planning/REQUIREMENTS.md     — what was scoped in/out and why
+.planning/ROADMAP.md          — phase structure decisions
+.planning/research/           — STACK.md, ARCHITECTURE.md, FEATURES.md, PITFALLS.md
+.planning/STATE.md            — current project state
+.planning/config.json         — workflow preferences (tech stack, parallelization)
+CLAUDE.md                     — project conventions, constraints, stack
+README.md                     — project description, sometimes tech choices
+docs/                         — any existing architecture docs
+package.json / pyproject.toml / go.mod / Cargo.toml  — tech stack, dependencies
+docker-compose.yml / Dockerfile — deployment decisions
+.env.example                  — configuration approach
+tsconfig.json / .eslintrc     — tooling decisions
+```
+
+**From git history:**
+
+```bash
+# Key decisions often in early commits
+git log --oneline --reverse | head -30
+
+# Commit messages mentioning "choose", "switch to", "use", "adopt", "replace"
+git log --oneline --all --grep="choose\|switch to\|adopt\|replace\|migrate" | head -20
+```
+
+For each source found, extract:
+- What decision was made (technology, pattern, boundary, constraint)
+- Why (if documented — rationale, trade-offs)
+- When (commit date or file date)
+- What alternatives were considered (if documented)
+
+### Step 2: Classify Discovered Decisions
+
+Group discovered decisions into categories from `config/taxonomy.toml`:
+
+- Technology Choice (stack, database, framework, libraries)
+- Architecture Pattern (monolith/microservice, API style, data flow)
+- Data Model (schema decisions, storage strategy)
+- Deployment Strategy (containerization, hosting, CI/CD)
+- Authentication / Authorization (auth approach, deferred or implemented)
+- Testing Strategy (framework choice, coverage approach)
+- Process / Workflow (coding conventions, branching strategy)
+- Integration Strategy (external APIs, data sources)
+- Out-of-scope decisions (explicit exclusions with reasoning)
+
+**Prioritize by impact:** High-impact decisions that constrain future work get ADRs first.
+Low-impact decisions (linter config, date formatting library) get skipped.
+
+### Step 3: Present Discovery Report
+
+Before creating anything, present what was found to the user:
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ BLUEPRINT ► INITIALIZATION
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+## Context Discovered
+
+| Source | Found | Decisions Extracted |
+|--------|-------|-------------------|
+| .planning/PROJECT.md | Yes/No | [N] |
+| .planning/research/ | Yes/No | [N] |
+| CLAUDE.md | Yes/No | [N] |
+| package.json | Yes/No | [N] |
+| git history | Yes/No | [N] |
+| ... | ... | ... |
+
+## Proposed ADRs ([N] total)
+
+| # | Title | Source | Category |
+|---|-------|--------|----------|
+| 0001 | Use ADRs for architectural decisions | (meta) | Process |
+| 0002 | [inferred decision] | [source file] | [category] |
+| 0003 | [inferred decision] | [source file] | [category] |
+| ... | ... | ... | ... |
+
+## Will Also Create
+
+- docs/adr/README.md — lifecycle documentation and index
+- docs/adr/template.md — ADR template
+- docs/ARCHITECTURE.md — bird's-eye codemap (via architect agent)
+- config/state.toml — populated with detected paths
+```
+
+Ask the user:
+- "Create all proposed ADRs?" / "Let me pick" / "Adjust"
+- If "Let me pick" — present list with checkboxes
+- If "Adjust" — let user add, remove, or modify proposed ADRs
+
+### Step 4: Create ADR Directory Structure
+
+```bash
+mkdir -p docs/adr
+```
+
+Write `docs/adr/template.md` — the standard ADR template with Metadata table, Context,
+Options Considered, Decision (Alexandrian prologue), Rationale, Consequences, References.
+
+Write `docs/adr/README.md` — lifecycle documentation with:
+- State machine diagram (Proposed → Accepted/Rejected/Deferred → Deprecated/Superseded)
+- Status definitions and transition rules
+- File naming convention (NNNN-kebab-case-title.md)
+- Principles (one decision per ADR, immutable history, honest consequences)
+- Index table (initially populated with the ADRs about to be created)
+
+### Step 5: Generate ADRs
+
+For each approved ADR:
+
+1. Write the ADR file: `docs/adr/NNNN-title.md`
+2. Status: `Accepted` (these are decisions already in effect, not proposals)
+3. Context: extracted from the source where the decision was found
+4. Options Considered: if the source documented alternatives, include them.
+   If not, include at minimum the chosen option and "Status quo / do nothing"
+5. Decision: Alexandrian prologue format
+6. Consequences: infer from what's observable in the codebase
+7. References: link to the source file where the decision was found
+
+**ADR-0001 is always "Use ADRs for architectural decisions"** — the meta-ADR that
+establishes the process. Include it automatically.
+
+**Quality bar:** Even inferred ADRs must have real context and consequences. Don't
+generate vacuous ADRs like "Use JavaScript" with no context. If a decision is too
+trivial to have meaningful context, skip it.
+
+### Step 6: Generate ARCHITECTURE.md
+
+After ADRs are written, spawn the architect-cartographer agent to generate
+`docs/ARCHITECTURE.md`:
+
+- Read `agents/adr-architect-cartographer.md` and `agents/persona.md`
+- Spawn with: project root, ADR directory, list of newly created ADR filenames
+- The agent produces the codemap, invariants (from the new ADRs), and cross-cutting concerns
+
+### Step 7: Populate Config
+
+Update `config/state.toml`:
+- Set `adr_directory` to the detected/created path
+- Set `project_root` to the current working directory
+- Set `last_adr_created` to today
+
+Seed `config/relationships.toml` with nodes for all created ADRs.
+
+### Step 8: Commit
+
+Commit all created files in a single atomic commit:
+
+```
+docs: initialize blueprint — [N] ADRs, ARCHITECTURE.md, lifecycle docs
+```
+
+Include: all ADR files, README.md, template.md, ARCHITECTURE.md.
+
+### Step 9: Present Summary
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ BLUEPRINT ► INITIALIZED ✓
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+| Artifact | Location |
+|----------|----------|
+| ADRs | docs/adr/ ([N] decisions) |
+| Template | docs/adr/template.md |
+| Lifecycle | docs/adr/README.md |
+| Architecture | docs/ARCHITECTURE.md |
+| Index | docs/adr/README.md |
+
+Run /blueprint:help for the full command reference.
+Run /blueprint:evaluate to assess architecture health.
+Run /blueprint:list to see all decisions.
+```
+
+## Edge Cases
+
+**No existing decisions found:** Create just ADR-0001 (meta-ADR), the template, lifecycle
+README, and ARCHITECTURE.md. Suggest `/blueprint:new --research` for the first real decision.
+
+**ADR directory already exists:** Check if it has ADRs. If yes, abort with "Blueprint is
+already initialized. Use `/blueprint:help` for commands." If the directory exists but is
+empty, proceed with initialization.
+
+**Conflicting documentation:** If .planning/PROJECT.md and CLAUDE.md disagree on tech stack,
+flag the conflict and ask the user which is authoritative before creating the ADR.
+
+**.planning/research/ is rich:** GSD research files (STACK.md, FEATURES.md, ARCHITECTURE.md,
+PITFALLS.md) are goldmines. Extract:
+- From STACK.md: technology choices with rationale
+- From FEATURES.md: scope decisions (what's in v1, what's deferred, what's excluded)
+- From ARCHITECTURE.md: structural decisions (components, boundaries, data flow)
+- From PITFALLS.md: constraint decisions (what to avoid and why)
+
+**Large existing codebase:** Don't try to create an ADR for every library import. Focus on
+decisions that constrain future work — the things a new developer needs to know.

package/commands/list.md

@@ -0,0 +1,51 @@
+---
+name: blueprint:list
+description: >
+  List all ADRs with status, date, and contextual next-action suggestions. Use when:
+  "list adrs", "show decisions", "what adrs do we have", "decision status", "show accepted
+  decisions", "any proposed adrs?", "list deferred". Supports filtering by status.
+---
+
+# List ADRs
+
+Display all ADRs in a summary table with contextual suggestions for next actions.
+
+## Process
+
+### Step 1: Read ADR State
+
+1. Read `config/state.toml` from the parent `adr/` directory for ADR directory location
+2. If no directory cached, detect: `docs/adr/` → `docs/decisions/` → `adr/` → `decisions/`
+3. Glob for all ADR files (`[0-9][0-9][0-9][0-9]-*.md`)
+4. For each file, extract: number, title (from heading), status, date proposed, date decided
+
+### Step 2: Apply Filters
+
+If the user specified a filter ("list proposed", "show accepted", "any deferred?"), filter
+the results to matching statuses only.
+
+### Step 3: Display Table
+
+```
+| #    | Title                                    | Status    | Date       |
+|------|------------------------------------------|-----------|------------|
+| 0001 | Use ADRs for architectural decisions      | Accepted  | 2026-03-30 |
+| 0002 | Use React and FastAPI stack               | Accepted  | 2026-03-30 |
+| 0009 | Use Redis for session caching             | Proposed  | 2026-04-02 |
+```
+
+If filtering, show the filter: "Showing [N] [status] ADRs (of [total] total)"
+
+### Step 4: Contextual Suggestions
+
+Append a `▶ Suggested next actions` section using the same rules as `/blueprint:help` Step 3:
+
+1. Proposed ADRs exist → suggest `/blueprint:review N`
+2. Conversation has undocumented architectural topic → suggest `/blueprint:new`
+3. Application code + no recent audit → suggest `/blueprint:audit`
+4. Application code + no recent evaluation → suggest `/blueprint:evaluate`
+5. Recent fix committed → suggest `/blueprint:retro`
+6. No ADRs → suggest `/blueprint:new`
+7. All Accepted, nothing pending → "No pending actions"
+
+This ensures the user always sees what to do next after viewing the list.

package/commands/new.md

@@ -0,0 +1,74 @@
+---
+name: blueprint:new
+description: >
+  Create a new Architecture Decision Record. Use when: the user says "new adr", "create adr",
+  "document this decision", "we should record this"; or when you notice a significant architectural
+  choice being made without an ADR. Add --research to spawn a researcher agent first.
+  Examples: "/blueprint:new use Redis for caching", "/blueprint:new --research session management strategy".
+---
+
+# Create a New ADR
+
+Create a new Architecture Decision Record, optionally with research-backed evidence gathering.
+
+## Shared Context
+
+Before starting, read these files from the parent `adr/` skill directory:
+- `config/lifecycle.toml` — valid statuses (new ADRs start as Proposed)
+- `config/taxonomy.toml` — decision categories, severity levels
+- `config/state.toml` — ADR directory location (if previously detected)
+- `config/relationships.toml` — existing ADR relationships (for impact awareness)
+- `agents/persona.md` — your personality
+
+## Directory Detection
+
+If `config/state.toml` has an `adr_directory`, use it. Otherwise detect:
+1. `docs/adr/` (preferred)
+2. `docs/decisions/`
+3. `adr/`
+4. `decisions/`
+
+If found, update `config/state.toml` with the detected path.
+Read `template.md` from the ADR directory if it exists.
+
+## Process
+
+1. **Determine next sequence number** — glob `[0-9][0-9][0-9][0-9]-*.md` in ADR directory
+2. **Interview the user** if context is insufficient:
+   - What decision needs to be made?
+   - What alternatives were considered?
+   - What constraints or forces are at play?
+   - User can say "you fill it in" for parts you can infer
+3. **Research (if `--research` flag or user requests):**
+   - Read `agents/adr-researcher.md` from the parent skill directory
+   - Spawn a `general-purpose` agent with the researcher instructions + `agents/persona.md`
+   - Provide: decision topic, constraints, ADR directory path, existing ADR filenames
+   - Present the research brief to the user
+   - Pre-populate Options Considered from research
+4. **Draft the ADR** using the project's template, status = `Proposed`
+5. **Write the file** — `NNNN-short-descriptive-title.md`
+6. **Update the index** in README.md
+7. **Update `config/relationships.toml`** — add the new ADR as a node
+8. **Update `config/state.toml`** — set `last_adr_created` to today
+9. **Present** to user for review before commit
+10. **Commit** with message: `docs(adr): propose ADR-NNNN <title>`
+
+## Quality Checks
+
+Read `config/taxonomy.toml` for decision categories and severity levels. Verify:
+- Title uses present-tense imperative verb phrase
+- Context explains forces/constraints
+- At least 2 options considered
+- Consequences include positive AND negative
+- Category assigned from taxonomy
+
+If thin on alternatives or consequences, push back — a rubber-stamp ADR is worse than none.
+
+## File Naming
+
+`NNNN-short-descriptive-title.md` — zero-padded, kebab-case, imperative verb phrase.
+
+## Commit Convention
+
+`docs(adr): propose ADR-NNNN <title>`
+Include both the ADR file and updated README.md.

package/commands/rearchitect.md

@@ -0,0 +1,45 @@
+---
+name: blueprint:rearchitect
+description: >
+  Revisit and replace an existing architectural decision. Researches new approach, drafts
+  superseding ADR, runs impact analysis, and transitions old ADR(s) to Superseded. Use when:
+  "rearchitect X", "rethink our approach to X", "replace decision about X", "supersede the
+  auth decision with a new approach".
+---
+
+# Rearchitect
+
+Compound workflow for revisiting and replacing an architectural decision. Combines research,
+drafting, impact analysis, and lifecycle transitions into a single flow.
+
+## Shared Context
+
+Read from parent `adr/` skill directory:
+- `config/lifecycle.toml` — transition rules for superseding
+- `config/relationships.toml` — existing ADR relationships
+- `config/state.toml` — ADR directory
+- `agents/persona.md` — personality
+- `agents/adr-researcher.md` — for researching the new approach
+- `agents/adr-impact-analyzer.md` — for checking cascading effects
+
+## Process
+
+1. **Search existing ADRs** for the topic
+2. **Present related ADRs** — ask user to confirm which to supersede
+3. **Spawn researcher** — investigate the new approach
+   - Read `agents/adr-researcher.md` + `agents/persona.md`
+   - Spawn with topic, constraints, existing ADRs
+4. **Present research** — conduct interview for the new ADR
+5. **Draft the superseding ADR** with cross-references:
+   - "Supersedes ADR-NNNN" in metadata
+6. **Spawn impact analyzer** on the new draft:
+   - Read `agents/adr-impact-analyzer.md` + `agents/persona.md`
+   - Check for cascading conflicts with other accepted ADRs
+7. **Present impact analysis** to user
+8. **If user approves:**
+   - Write the new ADR file
+   - Transition old ADR(s) to Superseded (per lifecycle.toml)
+   - Cross-link: old ADR gets "Superseded by ADR-NNNN"
+   - Update README.md index for both
+   - Update `config/relationships.toml` with SUPERSEDES edge
+   - Commit: `docs(adr): supersede ADR-NNNN with ADR-MMMM <title>`

package/commands/retro.md

@@ -0,0 +1,50 @@
+---
+name: blueprint:retro
+description: >
+  Post-fix retrospective — evaluates whether recent changes are band-aids or systemic fixes,
+  classifies root causes, verifies proposed improvements against external sources, and proposes
+  ADRs for architectural improvements worth formalizing. Use after: /gsd:quick, /rapid:quick,
+  /rapid:bug-fix, manual fixes, or any commit that patches a symptom. Also triggered by:
+  "was that a band-aid?", "should we document that?", "review this fix", "retrospective".
+---
+
+# Post-Fix Retrospective
+
+Evaluates recent changes for band-aid vs systemic quality. Answers two questions:
+1. Was this fix a band-aid? Could the bug class be prevented by design, not just this instance?
+2. Are the proposed improvements real? Verified against external sources, not confabulated.
+
+## Shared Context
+
+Read from parent `adr/` skill directory:
+- `config/taxonomy.toml` — root cause categories (the classification system)
+- `config/state.toml` — ADR directory, retro history
+- `agents/persona.md` — personality
+- `agents/adr-retrospective.md` — agent instructions
+
+## Process
+
+1. **Determine what was fixed:**
+   - If a commit range is provided, use that
+   - Otherwise, read last 3 commits: `git log --oneline -3` and `git diff HEAD~3..HEAD`
+   - Include conversation context about what was fixed
+2. **Spawn retrospective agent:**
+   - Read `agents/adr-retrospective.md` and `agents/persona.md`
+   - Spawn `general-purpose` agent with:
+     - Diff / commit messages
+     - Root cause categories from `config/taxonomy.toml`
+     - ADR directory path and existing ADR filenames
+     - Full agent instructions + persona
+3. **Present retrospective report** to the user
+4. **If ADR recommended:**
+   - Ask user if they want to create it now
+   - If yes, invoke `/blueprint:new` with the proposed title and context pre-filled
+5. **Update state:**
+   - Set `last_retro` in `config/state.toml` to today
+   - Append to `retro_history` with date, verdict, and ADR created (if any)
+
+## Proactive Triggering
+
+After observing a quick fix workflow (gsd:quick, rapid:quick, rapid:bug-fix, manual patch),
+suggest: "That fix is in. Want to run `/blueprint:retro` to check if it warrants an ADR?"
+Don't force it — just offer.

package/commands/review.md

@@ -0,0 +1,50 @@
+---
+name: blueprint:review
+description: >
+  Review a Proposed ADR with devil's advocate challenge before acceptance. Use when:
+  "review adr N", "let's review the proposed adrs", "challenge adr N". Spawns a devil's
+  advocate agent to find blind spots before the decision becomes binding. For direct
+  acceptance without challenge, use the lifecycle transitions in the root /blueprint skill.
+---
+
+# Review a Proposed ADR
+
+Review a Proposed ADR through a devil's advocate challenge process. This is the gate
+between "someone wrote a decision" and "the team committed to it."
+
+## Shared Context
+
+Read from parent `adr/` skill directory:
+- `config/lifecycle.toml` — valid transitions (Proposed → Accepted/Rejected/Deferred)
+- `config/state.toml` — ADR directory location
+- `agents/persona.md` — personality
+- `agents/adr-devils-advocate.md` — agent instructions
+
+## Process
+
+1. **Read the target ADR** — user specifies by number or title
+2. **Validate status** — must be `Proposed` (read lifecycle.toml for valid transitions)
+3. **Spawn devil's advocate:**
+   - Read `agents/adr-devils-advocate.md` and `agents/persona.md`
+   - Spawn `general-purpose` agent with:
+     - Full text of the Proposed ADR
+     - ADR file path and directory path
+     - List of all ADR filenames (for cross-reference)
+     - Full content of both agent files as instructions
+4. **Present the challenge report** to the user
+5. **Ask for verdict** using AskUserQuestion:
+   - **Accept** — Challenges noted, decision stands. Transition to Accepted.
+   - **Reject** — Fatal flaw found. Ask for rejection reason. Transition to Rejected.
+   - **Defer** — Need more information. Ask for trigger condition. Transition to Deferred.
+   - **Revise** — Address specific challenges, re-review later.
+6. **Execute transition** per `config/lifecycle.toml`:
+   - Update ADR status and metadata
+   - Update README.md index
+   - Update `config/relationships.toml` if applicable
+   - Commit with: `docs(adr): [accept|reject|defer] ADR-NNNN <title>`
+
+## Skip Challenge
+
+If the user says "just accept ADR N" or "accept adr N" without "review", this skill
+should NOT be invoked — that's a direct lifecycle transition handled by the root `/blueprint` skill.
+The challenge step is part of *review*, not *accept*.

package/commands/search.md

@@ -0,0 +1,28 @@
+---
+name: blueprint:search
+description: >
+  Search ADRs by topic, technology, or keyword. Use when: "why did we choose X?", "is there an
+  adr about X?", "what did we decide about X?", "search adrs for X", "find decision about auth".
+  Searches titles, context, decision sections, and the relationship graph.
+---
+
+# Search ADRs
+
+Find ADRs relevant to a topic by searching content and the relationship graph.
+
+## Process
+
+1. Read `config/state.toml` for ADR directory location
+2. Read `config/relationships.toml` for the ADR dependency graph
+3. Parse the search term from the user's query
+4. **Search ADR files:**
+   - Grep for the term in ADR filenames (title match)
+   - Grep for the term within ADR file content (context, decision, consequences sections)
+   - Rank by relevance: title match > decision section > context > consequences
+5. **Search relationship graph:**
+   - Check if the term matches any node labels or edge descriptions in `relationships.toml`
+   - Include related ADRs (DEPENDS_ON, CONFLICTS, SUPERSEDES) in results
+6. **Present results:**
+   - Show matching ADRs with status, title, and the matching snippet (1-2 lines of context)
+   - If relationship graph has relevant edges, show them: "ADR-0003 DEPENDS ON ADR-0002"
+   - If no matches: "No ADRs found for '[term]'. Run `/blueprint:new \"[term]\"` to create one."