Skip to main content
skill CX Codex

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

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add terrylica/cc-skills --skill implement-plan-preflight -a claude-code
Open on GitHub

What 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-code

2Manually: put the files in place

~/.claude/skills/implement-plan-preflight/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/implement-plan-preflight/

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

Similar skills

All skills for Agent setup: memory, context, orchestration →

From the same set79

The whole set →
asciinema-converter asciinema-converter turns asciinema .cast recordings into clean .txt files for reading and search. It handles one file or a directory batch. CX Codex +1 126installs multi-agent-performance-profiling multi-agent-performance-profiling spawns five parallel profiling agents to investigate system layers: instrumentation, database config, client library, batch sizing, and synthesis. CX Codex +1 126installs clickhouse-cloud-management clickhouse-cloud-management manages ClickHouse Cloud database users and access permissions using SQL statements over HTTPS. CX Codex +1 126installs booking-notify booking-notify sends notifications for new bookings, cancellations and reschedules via Telegram and Pushover. 6-hour polling sync, real-time webhook for urgent events. CX Codex +1 125installs issues-workflow issues-workflow puts plan, hierarchy and status into GitHub Issues: sub-issues under a parent, an issue linked to its branch and pull request, and a close on merge. CX Codex +1 124installs ml-failfast-validation ml-failfast-validation is a Claude Code skill that runs preflight checks for machine learning experiments, catching tensor, schema, and gradient errors before long training jobs. CX Codex +1 124installs pr-gfm-validator pr-gfm-validator turns relative markdown links in a pull request body into absolute blob URLs pinned to your feature branch, so reviewers stop landing on 404s. CX Codex +1 123installs pypi-doppler pypi-doppler — a skill for Claude Code and five other platforms that publishes Python packages to PyPI using a token stored in Doppler — local machine only. The bundled script detects CI environments and exits immediately if one is found. CX Codex +1 123installs

Project sponsors

Companies that keep this analytics open