From blueprint-plugin
Generates Architecture Decision Records (ADRs) by analyzing project structure, dependencies, and documentation. Use for onboarding existing projects to Blueprint system and documenting implicit decisions.
npx claudepluginhub laurigates/claude-plugins --plugin blueprint-pluginThis skill is limited to using the following tools:
Generate Architecture Decision Records (ADRs) for an existing project by analyzing code structure, dependencies, and documentation.
Creates isolated Git worktrees for feature branches with prioritized directory selection, gitignore safety checks, auto project setup for Node/Python/Rust/Go, and baseline verification.
Executes implementation plans in current session by dispatching fresh subagents per independent task, with two-stage reviews: spec compliance then code quality.
Dispatches parallel agents to independently tackle 2+ tasks like separate test failures or subsystems without shared state or dependencies.
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:
docs/blueprint/ exists)/blueprint:derive-prd first)Steps:
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)
mkdir -p docs/adrs
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:
Before generating new ADRs, check for existing decisions that may conflict or relate.
ls docs/adrs/*.md 2>/dev/null | wc -l
If ADRs exist, analyze for potential conflicts with decisions about to be documented.
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 |
For each domain being documented:
grep -l "^domain: {domain}" docs/adrs/*.md
For each matching ADR with status: Accepted:
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.
If multiple potential conflicts in same domain:
| 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 |
For each identified technology choice:
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
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*
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 |
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:
## 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})
If any new ADR supersedes an existing ADR:
Read the superseded ADR file
Update its frontmatter:
status: Accepted to status: Supersededsuperseded_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:
supersedes: ADR-0003status: Supersededsuperseded_by: ADR-0012Update 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}"
}
}
}
}
✅ 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
/blueprint:derive-prd/blueprint:prp-createUpdate docs/blueprint/manifest.json:
has_adrs: true to structuregenerated_artifactsupdated_at timestampTips:
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:
/blueprint:prp-create (ask for feature name)/blueprint:generate-skillsError Handling: