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:

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?}

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}

✅

✅

❌ {con 1}

{Option 2}

✅

❌

❌ {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}

](

./{filename}.md

)

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