blueprint-derive-adr_skill

This skill derives Architecture Decision Records from an existing project by analyzing code structure, dependencies, and documentation to onboard Blueprint.

Shell

7

GitHub Stars

1

Bundled Files

2 months ago

Catalog Refreshed

4 months ago

First Indexed

Readme & install

Copy the install command, review bundled files from the catalogue, and read any extended description pulled from the listing source.

Installation

Preview and clipboard use veilstrat where the catalogue uses aiagentskills.

npx veilstrat add skill laurigates/claude-plugins --skill blueprint-derive-adr

SKILL.md12.5 KB

Overview

This skill derives Architecture Decision Records (ADRs) for an existing project by analyzing its code structure, dependencies, and documentation. It automates discovery, conflict analysis, and MADR-style ADR generation so implicit architecture choices become recorded and actionable. The output includes ADR files, an ADR README, and manifest updates for Blueprint Development.

How this skill works

The skill inspects project files (directory layout, package manifests, config, imports, test folders) and runs an Explore agent to surface frameworks, data layers, API styles, and other patterns. It checks existing ADRs for conflicts, calculates conflict scores, prompts for relationships, and generates MADR-formatted ADRs plus an ADR README and manifest updates. Superseded ADRs are updated bidirectionally and a summary report is produced.

When to use it

Onboarding an existing codebase into the Blueprint Development system
Documenting implicit or legacy architecture decisions for traceability
Preparing architecture artifacts before major refactors or handoffs
When you want a programmatic ADR index and consistent manifest entries
After running /blueprint:derive-prd (recommended) or when PRD is missing

Best practices

Run the discovery phase with the Explore agent to capture evidence from code and configs
Run /blueprint:derive-prd first if a PRD exists to link requirements to ADRs
Resolve high conflict-score ADRs interactively: supersede, extend, or relate
Document only decisions with real alternatives; mark unclear rationales as 'needs rationale'
Keep ADRs concise and focused on 'why' rather than implementation details

Example use cases

Generating ADRs for language, framework, and testing choices in a migrated repo
Detecting and resolving conflicting database or deployment decisions across ADRs
Producing an ADR README that auto-indexes records for team reference
Marking inherited decisions as legacy and flagging items needing team rationale
Creating a set of standard ADRs (0001–0008) for a monorepo during onboarding

FAQ

The project should have docs/blueprint/ present. A PRD is recommended but not required; if missing the skill can prompt to run /blueprint:derive-prd first.

How does the skill handle existing ADR conflicts?

It scores potential conflicts, surfaces those with high scores, and prompts you to supersede, extend, relate, or ignore each conflicting ADR. Superseded ADRs are updated for bidirectional consistency.

Which ADRs does the skill create by default?

If applicable, it creates standard ADRs such as project-language, framework-choice, testing-strategy, styling-approach, state-management, database-choice, api-design, and deployment-strategy.