spec-to-adr#

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 FieldGSD Plan SourceCreatePlan SourceGeneric SourceTitlePhase name / goalname from frontmatterFirst H1 or user-providedContext and ProblemRESEARCH.md problem section, or PLAN.md overviewoverview from frontmatterOpening paragraphs or problem statementDecision DriversConstraints, requirements from RESEARCHTrade-offs discussed in bodyBullet lists of requirements or constraintsConsidered OptionsAlternative approaches in RESEARCH or PLANMultiple approaches in body sectionsSections describing different optionsDecision OutcomeThe chosen plan/approach in PLAN.mdThe plan body (the chosen path)The recommended or selected approachConsequencesRisk sections, known trade-offsNoted risks or caveatsStated 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.