Generate Architecture Decision Records (ADRs) for an existing project by analyzing code structure, dependencies, and documentation.

Use Case: Onboarding existing projects to Blueprint Development system, documenting implicit architecture decisions.

Prerequisites:

• Blueprint Development initialized (docs/blueprint/ exists)

• Ideally PRD exists (run /blueprint:derive-prd first)

Steps:

Phase 1: Discovery

1.1 Check Prerequisites

ls docs/blueprint/manifest.json ls docs/prds/

If blueprint not initialized → suggest /blueprint:init

If no PRD → suggest /blueprint:derive-prd first (recommended, not required)

1.2 Create ADR Directory

mkdir -p docs/adrs

1.3 Analyze Project Structure

Explore the codebase to identify architectural patterns:

Use Explore agent:

<Task subagent_type="Explore" prompt="Analyze project architecture: directory structure, major components, frameworks used, design patterns">

Key areas to examine:

• Directory structure: How code is organized

• Entry points: Main files, index files

• Configuration: Config files, environment handling

• Dependencies: Package manifests, imports

• Data layer: Database, ORM, data models

• API layer: Routes, controllers, handlers

• Testing: Test structure and frameworks

Phase 1.5: Conflict Analysis

Before generating new ADRs, check for existing decisions that may conflict or relate.

1.5.1 Check for Existing ADRs

ls docs/adrs/*.md 2>/dev/null | wc -l

If ADRs exist, analyze for potential conflicts with decisions about to be documented.

1.5.2 Determine Domain for New ADR

Map decision categories to domains:

Decision Category Domain Tag

State Management state-management

Database/ORM data-layer

Framework Choice frontend-framework

API Design api-design

Authentication authentication

Testing Strategy testing

Styling Approach styling

Build Tooling build-tooling

Deployment deployment

1.5.3 Scan Existing ADRs in Same Domain

For each domain being documented:

grep -l "^domain: {domain}" docs/adrs/*.md

For each matching ADR with status: Accepted :

• Extract ADR number and title

• Extract decision outcome (chosen option)

• Calculate conflict score:

• Same domain: +0.3

• Both Accepted: +0.2

• Opposite/different outcomes: +0.4

• Age > 6 months: +0.1

1.5.4 Surface Potential Conflicts

If conflict score >= 0.7, prompt user:

question: "Found existing ADR in same domain: ADR-{XXXX} - {title}. How should the new decision relate?" options:

• label: "Supersede ADR-{XXXX}" description: "New ADR replaces the existing decision"
• label: "Extend ADR-{XXXX}" description: "New ADR builds on the existing decision"
• label: "Mark as related" description: "Decisions are connected but independent"
• label: "No relationship" description: "Continue without linking"

Store the relationship choice for inclusion in the generated ADR frontmatter.

1.5.5 Handle Multiple Conflicts

If multiple potential conflicts in same domain:

• Present each for user decision

• Allow bulk "supersede all" option for replacing multiple outdated decisions

Phase 2: Identify Architecture Decisions

2.1 Common Decision Categories

Category What to Look For Example Decisions

Framework package.json, imports React vs Vue, Express vs Fastify

Language File extensions, tsconfig TypeScript vs JavaScript

State Management Store patterns, context Redux vs Zustand vs Context

Styling CSS files, styled imports Tailwind vs CSS-in-JS vs SCSS

Testing Test files, test config Vitest vs Jest, Playwright vs Cypress

Build Build config, bundlers Vite vs Webpack, esbuild

Database ORM config, migrations PostgreSQL vs MongoDB, Prisma vs Drizzle

API Style Route patterns, schemas REST vs GraphQL, tRPC

Deployment Docker, CI config Container vs serverless

Monorepo Workspace config Turborepo vs Nx vs none

2.2 Infer Decisions from Code

For each identified technology choice:

• Note the current implementation

• Consider common alternatives

• Infer rationale from context/comments

2.3 Confirm with User

Use AskUserQuestion for key decisions:

question: "I found the project uses {technology}. Why was this chosen over alternatives?" options:

• "Performance requirements" → document performance rationale
• "Team familiarity" → document team expertise factor
• "Ecosystem/community" → document ecosystem benefits
• "Specific feature needs" → ask for details
• "Legacy/inherited decision" → document as inherited
• "Other" → custom rationale

question: "Are there any architecture decisions you'd like to document that aren't visible in the code?" options:

• "Yes, let me describe" → capture additional decisions
• "No, the inferred decisions are sufficient" → proceed

Phase 3: ADR Generation

3.1 ADR Template (MADR format)

For each significant decision, create an ADR:

id: ADR-{NNNN} # Derived from filename (0003-*.md → ADR-0003) date: {YYYY-MM-DD} status: Accepted | Superseded | Deprecated | Proposed deciders: {who made the decision} domain: {domain-tag} # Optional: state-management, data-layer, etc. supersedes: ADR-{XXXX} # Optional: if superseding another ADR extends: ADR-{XXXX} # Optional: if extending another ADR relates-to: # Cross-document references

• PRD-{NNN} # Related PRDs
• ADR-{YYYY} # Related ADRs github-issues: [] # Linked GitHub issues name: blueprint-derive-adr

ADR-{number}: {Title}

Context

{Describe the issue motivating this decision} {What is the problem we're trying to solve?} {What constraints exist?}

Decision Drivers

• {driver 1, e.g., "Performance under high load"}
• {driver 2, e.g., "Developer experience"}
• {driver 3, e.g., "Maintainability"}

Considered Options

1. {Option 1} - {brief description}
2. {Option 2} - {brief description}
3. {Option 3} - {brief description}

Decision Outcome

Chosen option: "{Option X}" because {justification}.

Positive Consequences

• {positive outcome 1}
• {positive outcome 2}

Negative Consequences

• {negative outcome / tradeoff 1}
• {negative outcome / tradeoff 2}

Pros and Cons of Options

{Option 1}

• ✅ {pro 1}
• ✅ {pro 2}
• ❌ {con 1}

{Option 2}

• ✅ {pro 1}
• ❌ {con 1}
• ❌ {con 2}

Links

• {Related ADRs}
• {External documentation}
• {Discussion threads}

Generated from project analysis via /blueprint:derive-adr

3.2 Standard ADRs to Generate

Generate ADRs for these common decisions (if applicable):

ADR When to Create

0001-project-language.md

Language/runtime choice

0002-framework-choice.md

Main framework selection

0003-testing-strategy.md

Test framework and approach

0004-styling-approach.md

CSS/styling methodology

0005-state-management.md

State handling (if applicable)

0006-database-choice.md

Database and ORM (if applicable)

0007-api-design.md

API style and patterns

0008-deployment-strategy.md

Deployment approach

3.3 Create ADR README

Write the ADR README template to docs/adrs/README.md using the template from blueprint-plugin/templates/adr-readme.md .

The README is self-documenting: it includes a programmatic fd

• awk command that generates the ADR index on demand, eliminating static tables that drift out of sync.

Customizations when writing:

• If undocumented decisions were identified during Phase 2 analysis that the user chose not to create full ADRs for, add them to the Proposed ADRs section:

Proposed ADRs

Decisions identified but not yet documented as full ADRs:

• {Decision topic} — {brief context} (identified {YYYY-MM-DD})

• {Decision topic} — {brief context} (identified {YYYY-MM-DD})

• Keep the programmatic listing command intact — it replaces the need for a static index

Phase 4: Relationship Updates & Validation

4.0 Update Superseded ADRs (Bidirectional Consistency)

If any new ADR supersedes an existing ADR:

Read the superseded ADR file

Update its frontmatter:

• Change status: Accepted to status: Superseded

• Add superseded_by: ADR-{new_number}

Update the Links section (add if missing):

Links

• Superseded by ADR-{number}

Report the update:

Updated ADR-{old_number}:

• Status: Accepted → Superseded
• Added: superseded_by: ADR-{new_number}
• Updated Links section

Example: If ADR-0012 supersedes ADR-0003:

• In ADR-0012: supersedes: ADR-0003

• In ADR-0003:

• status: Superseded

• superseded_by: ADR-0012

• Links section references ADR-0012

4.1 Update Manifest

Update docs/blueprint/manifest.json ID registry for each ADR:

{ "id_registry": { "documents": { "ADR-0003": { "path": "docs/adrs/0003-database-choice.md", "title": "Database Choice", "status": "Accepted", "domain": "data-layer", "relates_to": ["PRD-001"], "github_issues": [], "created": "{date}" } } } }

4.2 Present Summary

✅ ADRs Generated: {count} records

Location: docs/adrs/

Decisions documented:

• ADR-0001: {title} - {status} [{domain}]
• ADR-0002: {title} - {status} [{domain}] ...

Relationships established:

• ADR-{new} supersedes ADR-{old} (status updated)
• ADR-{new} extends ADR-{existing}
• ADR-{new} related to ADR-{other}

ADRs updated (bidirectional consistency):

• ADR-{old}: status → Superseded, superseded_by → ADR-{new}

Sources analyzed:

• {list of analyzed files/patterns}

Confidence levels:

• High confidence: {list - clear from code}
• Inferred: {list - reasonable assumptions}
• Needs review: {list - uncertain}

Recommended next steps:

1. Review generated ADRs for accuracy
2. Add rationale where marked as "inferred"
3. Run /blueprint:derive-adr-validate to check relationship consistency
4. Run /blueprint:prp-create for feature implementation
5. Run /blueprint:generate-skills for project skills

4.2 Suggest Next Steps

• If PRD missing → suggest /blueprint:derive-prd

• If ready for implementation → suggest /blueprint:prp-create

• If architecture evolving → explain how to add new ADRs

Phase 5: Update Manifest

Update docs/blueprint/manifest.json :

• Add has_adrs: true to structure

• Add ADRs to generated_artifacts

• Update updated_at timestamp

Tips:

• Focus on decisions with real alternatives (not obvious choices)

• Document inherited/legacy decisions as such

• Mark uncertain rationales for user review

• Keep ADRs concise - focus on "why", not implementation details

• Reference related ADRs when decisions are connected

4.3 Prompt for next action (use AskUserQuestion):

question: "ADRs generated. What would you like to do next?" options:

• label: "Create a PRP for feature work (Recommended)" description: "Start implementing a specific feature with /blueprint:prp-create"
• label: "Generate project skills" description: "Create skills from PRDs for Claude context"
• label: "Review and add rationale" description: "Edit ADRs marked as 'inferred' or 'needs rationale'"
• label: "Document another architecture decision" description: "Manually add a new ADR"
• label: "I'm done for now" description: "Exit - ADRs are saved"

Based on selection:

• "Create a PRP" → Run /blueprint:prp-create (ask for feature name)

• "Generate project skills" → Run /blueprint:generate-skills

• "Review and add rationale" → Show ADR files needing attention

• "Document another decision" → Restart Phase 2 for a specific decision

• "I'm done" → Exit

Error Handling:

• If minimal codebase → create fewer, broader ADRs

• If conflicting patterns → ask user which is intentional

• If rationale unclear → mark as "needs rationale" for user input