Automatically convert agent execution plans into structured MADR Architecture Decision Records for permanent documentation and audit trails.
Install & Download
1. ClawHub CLI
The fastest way to install a skill directly from the registry.
npx clawhub@latest install spec-to-adr
2. Manual Installation
Copy the skill folder to one of these locations
~/.openclaw/skills/ <project>/skills/ Priority: Workspace > Local > Bundled
3. Prompt Installation
Copy this prompt to OpenClaw to install it automatically.
Help me install spec-to-adr using Clawhub. If Clawhub is not installed, install it first (npm i -g clawhub).
Prefer to download?
Get the raw skill files in a ZIP archive.
What is Spec to ADR?
Spec to ADR bridges the gap between ephemeral AI agent planning and long-term architectural documentation. By integrating with Openclaw Skills, it allows developers to capture the rationale behind technical decisions automatically. It parses various formats like GSD plans and Cursor CreatePlans to generate standardized MADR files, ensuring that the why behind every change is preserved in your repository.
This skill is essential for teams using AI agents who need to maintain a professional audit trail without the manual overhead of drafting documentation from scratch. It transforms raw planning data into a readable, searchable, and version-controlled history of your project's evolution.
Spec to ADR Use Cases
- Converting an AI agent phase plan into a formal architecture record for stakeholder review.
- Documenting the rationale for choosing a specific database or cloud provider during the planning phase.
- Maintaining a chronological audit trail of technical decisions for compliance and team transparency.
- Transitioning from temporary Cursor plan files to permanent documentation in a docs/adr directory.
How Spec to ADR Works
- Locate the source plan by automatically searching for GSD phase files, Cursor plan files, or generic markdown documents containing problem statements.
- Extract structured decisions by mapping existing plan content to specific MADR fields such as Decision Drivers, Considered Options, and Consequences.
- Generate a numbered ADR file using a standardized template and semantic kebab-case naming based on the decision title.
- Update the ADR index in the project repository to maintain a searchable and organized registry of all decisions.
- Provide a summary report to the user including the new file path, ADR number, and a reminder for future status updates.
Spec to ADR Setup
The spec-to-adr skill is designed to work seamlessly within your development environment. To begin using this functionality via Openclaw Skills, ensure your project is prepared for ADR storage:
mkdir -p docs/adr/
The skill will automatically look for templates in references/madr-template.md and assets/adr-index-template.md. If these do not exist, it will use standard defaults to ensure your architecture records remain consistent.
Spec to ADR Data Schema & Taxonomy
The skill organizes architectural data using a standardized file structure and metadata taxonomy:
| Location | Format | Purpose |
|---|---|---|
docs/adr/NNNN-*.md |
MADR Markdown | Individual decision records with status, context, and outcomes. |
docs/adr/README.md |
Markdown Table | A master index of all ADRs for quick navigation. |
.planning/ |
Markdown | Source files for GSD phase plans and roadmaps. |
.cursor/plans/ |
YAML/Markdown | Source files for Cursor-specific execution plans. |
Spec to ADR Advanced Features
- Automatic detection of GSD Phase Plans and Cursor CreatePlan formats for zero-config extraction.
- Support for superseding existing records to maintain a clear and linear architecture history.
- Intelligent field mapping that infers technical context and risk factors from raw planning data.
- Multi-decision handling to split complex plans into several distinct architectural records.
- Seamless integration with git configurations to automatically attribute decision-makers.
SKILL.md
Loading
Related Openclaw Skills
FPF Actualize Knowledge Base
Synchronizes the project's knowledge base with recent repository changes to eliminate context drift and stale evidence.
Terms Checker
A specialized tool for auditing Terms of Service documents to identify unfair clauses and generate concise summaries.
Tech Stack: TypeScript Best Practices
A specialized skill designed to automate the injection of strict TypeScript standards and modern code style rules into your AI agent configuration.
SDD: Add Task
A specialized skill for AI coding agents to capture user intent and generate structured draft task files within a standardized specification directory.
BTC Chain Data API
A comprehensive Python-based API tool for querying Bitcoin on-chain structural data including UTXO, large flows, and valuation metrics.
Privacy Policy Generator
A specialized automation tool for generating and auditing GDPR and CCPA compliant privacy policies.
Featured*
