implement-plan-preflight — Claude Code skill: how to install
implement-plan-preflight runs the ITP workflow preflight phase to generate MADR 4.0 architecture records, design specs, and linked diagrams.
MIT 125 installs ★ 3 updated 2026-10-25
npx skills add terrylica/cc-skills --skill implement-plan-preflight -a claude-codeWhat implement-plan-preflight does
The skill executes the preparation phase for the /itp:go workflow. It writes an Architecture Decision Record (ADR) under /docs/adr/$ADR_ID.md and copies the global plan from ~/.claude/plans/ into /docs/design/$ADR_ID/spec.md.
Both files receive mutual header links. Each ADR requires seven frontmatter parameters alongside two diagrams: a before-and-after comparison and an architecture chart. Execution cannot advance to Phase 1 until the preflight checkpoint passes.
Running the mandatory verification step requires uv to execute scripts/preflight_validator.py.
What it helps with
- generate MADR 4.0 architecture records with standard metadata
- convert global session plans into project design specs
- enforce cross-linking between design documents and ADRs
- verify required context and architecture diagrams before coding
Example prompts for the agent
- Create an ADR and design spec for the new ingestion service
- Run the preflight phase for my current plan
- Generate a MADR format record for the caching layer
How to install implement-plan-preflight
1Skills CLI (Vercel)
npx skills add terrylica/cc-skills --skill implement-plan-preflight -a claude-code2Manually: put the files in place
~/.claude/skills/implement-plan-preflight/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/implement-plan-preflight/
1Skills CLI (Vercel)
npx skills add terrylica/cc-skills --skill implement-plan-preflight -a codex2Manually: put the files in place
.agents/skills/implement-plan-preflight/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add terrylica/cc-skills --skill implement-plan-preflight -a cursor2Manually: put the files in place
.cursor/skills/implement-plan-preflight/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install terrylica/cc-skills plugins/itp/skills/implement-plan-preflight2Manually: put the files in place
.github/skills/implement-plan-preflight/SKILL.md1Skills CLI (Vercel)
npx skills add terrylica/cc-skills --skill implement-plan-preflight -a gemini-cli2Platform CLI
gemini skills install https://github.com/terrylica/cc-skills --path plugins/itp/skills/implement-plan-preflightManually: put the files in place
.devin/skills/implement-plan-preflight/SKILL.mdThe legacy .windsurf/skills/ path still works
Skills CLI (Vercel)
npx skills add terrylica/cc-skills --skill implement-plan-preflight -a opencodeClaude.ai
Zip the folder and upload it in Settings → Capabilities → Skills
Step by step, with commands for each platform: How to install skills in Claude Code: five ways
Questions about implement-plan-preflight
How do I install implement-plan-preflight in Claude Code?
Run npx skills add terrylica/cc-skills --skill implement-plan-preflight -a claude-code. The file will be placed in ~/.claude/skills/implement-plan-preflight/SKILL.md.
What does implement-plan-preflight do?
It prepares planning artifacts: optionally creates a git branch with -b, generates an ADR file, embeds two required diagrams, and mirrors the global plan as a local design spec.
What does the validator script verify?
Running uv run scripts/preflight_validator.py $ADR_ID checks that both files exist, frontmatter has all seven fields, header backlinks are present, and both diagrams are included.
Source text
SKILL.md · MIT
---
name: implement-plan-preflight
description: Run the Preflight phase of the ITP workflow to create ADR and design spec artifacts. Use whenever the user asks to create an ADR, write a design.
allowed-tools: Bash, Read, Write, Edit, Glob, Grep
---
# Implement Plan Preflight
Execute the Preflight phase of the `/itp:go` workflow. Creates ADR and Design Spec artifacts with proper cross-linking and verification.
> **Self-Evolving Skill**: This skill improves through use. If instructions are wrong, parameters drifted, or a workaround was needed — fix this file immediately, don't defer. Only update for real, reproducible issues.
## When to Use This Skill
- Invoked by `/itp:go` command during Preflight phase
- User asks to create an ADR for a feature
- User mentions "design spec" or "MADR format"
- Manual preflight verification needed
## Preflight Workflow Overview
```
P.1: Create Feature Branch (if -b flag)
│
▼
P.2: Create ADR File (MADR 4.0)
│
▼
P.3: Create Design Spec (from global plan)
│
▼
P.4: Verify Checkpoint (MANDATORY)
```
**CRITICAL**: Do NOT proceed to Phase 1 implementation until ALL preflight steps are complete and verified.
---
## Quick Reference
### ADR ID Format
```
YYYY-MM-DD-slug
```
Example: `2025-12-01-clickhouse-aws-ohlcv-ingestion`
### File Locations
| Artifact | Path |
| ----------- | ------------------------------------ |
| ADR | `/docs/adr/$ADR_ID.md` |
| Design Spec | `/docs/design/$ADR_ID/spec.md` |
| Global Plan | `~/.claude/plans/<adj-verb-noun>.md` |
### Cross-Links (MANDATORY)
**In ADR header**:
```markdown
**Design Spec**: [Implementation Spec](/docs/design/YYYY-MM-DD-slug/spec.md)
```
**In spec.md header**:
```markdown
**ADR**: [Feature Name ADR](/docs/adr/YYYY-MM-DD-slug.md)
```
---
## Execution Steps
### Step P.1: Create Feature Branch (Optional)
Only if `-b` flag specified. See [Workflow Steps](./references/workflow-steps.md) for details.
### Step P.2: Create ADR File
1. Create `/docs/adr/$ADR_ID.md`
2. Use template from [ADR Template](./references/adr-template.md)
3. Populate frontmatter from session context
4. Select perspectives from [Perspectives Taxonomy](./references/perspectives-taxonomy.md)
### Step P.3: Create Design Spec
1. Create folder: `mkdir -p docs/design/$ADR_ID`
2. Copy global plan: `cp ~/.claude/plans/<adj-verb-noun>.md docs/design/$ADR_ID/spec.md`
3. Add ADR backlink to spec header
### Step P.4: Verify Checkpoint
Run validator or manual checklist:
```bash
uv run scripts/preflight_validator.py $ADR_ID
```
**Checklist** (ALL must be true):
- [ ] ADR file exists at `/docs/adr/$ADR_ID.md`
- [ ] ADR has YAML frontmatter with all 7 required fields
- [ ] ADR has `**Design Spec**:` link in header
- [ ] **DIAGRAM CHECK 1**: ADR has **Before/After diagram** (Context section)
- [ ] **DIAGRAM CHECK 2**: ADR has **Architecture diagram** (Architecture section)
- [ ] Design spec exists at `/docs/design/$ADR_ID/spec.md`
- [ ] Design spec has `**ADR**:` backlink in header
**If any item is missing**: Create it now. Do NOT proceed to Phase 1.
---
## YAML Frontmatter Quick Reference
```yaml
---
status: proposed
date: YYYY-MM-DD
decision-maker: [User Name]
consulted: [Agent-1, Agent-2]
research-method: single-agent
clarification-iterations: N
perspectives: [Perspective1, Perspective2]
---
```
See [ADR Template](./references/adr-template.md) for full field descriptions.
---
## Diagram Requirements (2 DIAGRAMS REQUIRED)
**⛔ MANDATORY**: Every ADR must include EXACTLY 2 diagrams:
| Diagram | Location | Purpose |
| ---------------- | -------------------- | ----------------------------- |
| **Before/After** | Context section | Shows system state change |
| **Architecture** | Architecture section | Shows component relationships |
**BLOCKING GATE**: Do NOT proceed to design spec until BOTH diagrams are embedded in ADR.
---
## Reference Documentation
- [ADR Template](./references/adr-template.md) - Complete MADR 4.0 template
- [Perspectives Taxonomy](./references/perspectives-taxonomy.md) - 11 perspective types
- [Workflow Steps](./references/workflow-steps.md) - Detailed step-by-step guide
---
## Validation Script
```bash
# Verify preflight artifacts
uv run scripts/preflight_validator.py <adr-id>
# Example
uv run scripts/preflight_validator.py 2025-12-01-my-feature
```
---
## Troubleshooting
| Issue | Cause | Solution |
| --------------------- | ----------------------- | -------------------------------------------- |
| Validator fails | Missing ADR or spec | Create both files before running validator |
| Frontmatter invalid | Missing required fields | Check all 7 ADR fields and 5 spec fields |
| Spec phase mismatch | Wrong phase value | Use: preflight, phase-1, phase-2, or phase-3 |
| ADR status wrong | Manual status edit | Let workflow manage status transitions |
| Design folder missing | Wrong path structure | Use docs/design/YYYY-MM-DD-slug/spec.md |
## Post-Execution Reflection
After this skill completes, check before closing:
1. **Did the command succeed?** — If not, fix the instruction or error table that caused the failure.
2. **Did parameters or output change?** — If the underlying tool's interface drifted, update Usage examples and Parameters table to match.
3. **Was a workaround needed?** — If you had to improvise (different flags, extra steps), update this SKILL.md so the next invocation doesn't need the same workaround.
Only update if the issue is real and reproducible — not speculative.
© terrylica · MIT · terrylica/cc-skills