Spec to ADR

Convert agent execution plans into MADR-format Architecture Decision Records for audit trails and architecture progression. Use when the user asks to create...

Convert execution plans into numbered MADR Architecture Decision Records stored in docs/adr/.

Workflow

Follow these steps in order:

1. Locate the plan -- identify the source plan using the detection rules below.
2. Extract decisions -- pull structured data from the plan into MADR fields.
3. Generate the ADR -- write the file using the template in references/madr-template.md.
4. Update the index -- append an entry to docs/adr/README.md.
5. Report -- show the user the ADR path, number, and a one-line summary.

Step 1: Locate the Plan

Determine the plan format by checking in this order:

GSD Phase Plan

Present when any of these exist relative to the workspace root:

• .planning/phases/*/PLAN.md
• .planning/ROADMAP.md
• .planning/phases/*/RESEARCH.md

Use the most recent PLAN.md unless the user specifies a phase. If multiple phases exist, ask which one to record.

Cursor CreatePlan

A .plan.md file (often in .cursor/plans/) with this structure:

• YAML frontmatter containing name, overview, and todos
• Markdown body with headings describing the approach

Generic Markdown Plan

Any markdown document the user points to that contains:

• A problem or goal statement
• One or more approaches, options, or alternatives
• A chosen direction or recommendation

If the user says "create an ADR" without pointing to a plan, ask: "Which plan or decision should I record? Point me to a file, or describe the decision."

Step 2: Extract Decisions

Map plan content to MADR fields. Not every field will have a direct source -- infer where reasonable, leave blank with a TODO marker where not.

MADR Field	GSD Plan Source	CreatePlan Source	Generic Source
Title	Phase name / goal	name from frontmatter	First H1 or user-provided
Context and Problem	RESEARCH.md problem section, or PLAN.md overview	overview from frontmatter	Opening paragraphs or problem statement
Decision Drivers	Constraints, requirements from RESEARCH	Trade-offs discussed in body	Bullet lists of requirements or constraints
Considered Options	Alternative approaches in RESEARCH or PLAN	Multiple approaches in body sections	Sections describing different options
Decision Outcome	The chosen plan/approach in PLAN.md	The plan body (the chosen path)	The recommended or selected approach
Consequences	Risk sections, known trade-offs	Noted risks or caveats	Stated pros/cons of chosen path

Extraction guidelines

• Preserve the plan's original language where possible; do not over-paraphrase.
• If the plan only describes one option (the chosen path) with no alternatives, set "Considered Options" to just that option and note in "More Information" that no alternatives were documented.
• For GSD plans with a VERIFICATION.md, pull verification criteria into Consequences.
• For CreatePlan todos, summarize them under "Decision Outcome" as the implementation approach.
• Always populate "More Information" with a relative link back to the source plan file.

Step 3: Generate the ADR

Numbering

1. List existing files in docs/adr/ matching the pattern NNNN-*.md.
2. Find the highest number. If no ADRs exist, start at 0001.
3. Increment by 1. Pad to 4 digits.

Filename

NNNN-kebab-case-title.md where the title is derived from the decision title, lowercased, spaces replaced with hyphens, non-alphanumeric characters removed, truncated to 60 characters.

Content

Read references/madr-template.md and fill in the extracted fields. Rules:

• Status: default to accepted. If the user says the decision is still under review, use proposed.
• Date: use today's date in YYYY-MM-DD format.
• Decision-makers: use the git user name (git config user.name) if available, otherwise leave as TODO.
• Consulted / Informed: leave as TODO unless the user specifies.
• Omit empty optional sections rather than leaving placeholder text, except for "More Information" which must always link to the source plan.

Output location

Write to docs/adr/NNNN-kebab-case-title.md. Create the docs/adr/ directory if it does not exist.

If the user has a different ADR directory convention (check for existing adr/, doc/adr/, architecture/decisions/), use that instead.

Step 4: Update the Index

Maintain a docs/adr/README.md that lists all ADRs. If it does not exist, create it using the template in assets/adr-index-template.md.

Append a row to the table:

text

| NNNN | Title | accepted | YYYY-MM-DD |

Step 5: Report

After writing the ADR, tell the user:

• The file path (e.g., docs/adr/0003-use-postgres-for-persistence.md)
• The ADR number
• A one-sentence summary of the recorded decision
• Remind them they can change the status later (proposed, deprecated, superseded by ADR-NNNN)

Edge Cases

• Multiple decisions in one plan: If a plan contains several distinct architectural decisions, ask the user whether to create one ADR per decision or a single combined ADR. Default to one-per-decision.
• Superseding an existing ADR: If the user says this decision replaces a previous one, set the new ADR status to accepted and update the old ADR's status to superseded by ADR-NNNN.
• Thin plans: If the source plan is too brief to populate most MADR fields, generate what you can and mark sparse sections with <!-- TODO: fill in after implementation -->. Warn the user the ADR is incomplete.
• No docs/adr/ directory: Create it. Do not ask for permission -- this is a standard convention.