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...

Security Scan

The skill's requirements and instructions are consistent with its stated purpose (converting plans to MADR ADR files in the repo); it reads and writes project files but asks for no unrelated credentials or installs.

Purpose & Capability

Name and description match the instructions: the skill locates plan files in the workspace, extracts decision content, generates ADR markdown, and updates an ADR index. No unrelated credentials, binaries, or external services are requested.

Instruction Scope

Runtime instructions operate on repository files (e.g., .planning/, .cursor/plans/, generic markdown, docs/adr/). They direct reading source plan files and writing ADR files and an index. The scope is limited to documentation/architecture artifacts and includes sensible edge-case handling (multiple decisions, superseding ADRs). The instructions do not direct data to external endpoints or request reading unrelated system secrets.

Install Mechanism

This is an instruction-only skill with no install spec and no code files to execute. That minimizes disk/installation risk.

Credentials

The skill declares no required environment variables or credentials. It suggests using the git user name (git config user.name) as a convenience, which is proportional to populating 'Decision-makers'. No secrets or unrelated tokens are requested.

Persistence & Privilege

The skill does not request always: true and does not modify other skills or global agent settings. It writes ADR files into the repository workspace (docs/adr/ or equivalent), which is appropriate for its function; persistent presence is not requested.

Assessment

This skill appears coherent and limited to creating ADR files from plans in your repository. Before installing or invoking it, consider: (1) Are you comfortable allowing the agent to read project files and write into your repo workspace? (2) Prefer running it in a branch or sandbox so generated ADRs can be reviewed before committing. (3) The tool may run git-config lookups for the user.name to populate fields—no credentials are required. (4) If your project uses a different ADR location or naming convention, confirm or provide that to the agent to avoid unexpected file writes. Finally, review any generated ADR and updated README.md before merging to ensure accuracy.

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:

| 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.