- name
- spec-to-adr
- description
- >-
spec-to-adr
Convert execution plans into numbered MADR Architecture Decision Records stored in docs/adr/.
Workflow
Follow these steps in order:
- Locate the plan -- identify the source plan using the detection rules below.
- Extract decisions -- pull structured data from the plan into MADR fields.
- Generate the ADR -- write the file using the template in references/madr-template.md.
- Update the index -- append an entry to
docs/adr/README.md. - 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, andtodos - 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
- List existing files in
docs/adr/matching the patternNNNN-*.md. - Find the highest number. If no ADRs exist, start at
0001. - 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, useproposed. - Date: use today's date in
YYYY-MM-DDformat. - Decision-makers: use the git user name (
git config user.name) if available, otherwise leave asTODO. - Consulted / Informed: leave as
TODOunless 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:
| 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
acceptedand update the old ADR's status tosuperseded 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.