Skill

implement-plan-preflight

Creates MADR-format ADR files and design specs with cross-links, optional feature branches, and verification for ITP workflow preflight phase.

Bash

Git

Python

documentation

From itp

Install

Run in your terminal

npx claudepluginhub terrylica/cc-skills --plugin itp

Tool Access

This skill is limited to using the following tools:

BashReadWriteEditGlobGrep

Supporting Assets

View in Repository

references/adr-template.md

references/claude-code-ephemeral-context.md

references/evolution-log.md

references/perspectives-taxonomy.md

references/workflow-steps.md

scripts/preflight_validator.py

Skill Content

Similar Skills

skill-lookup

Searches, retrieves, and installs Agent Skills from prompts.chat registry using MCP tools like search_skills and get_skill. Activates for finding skills, browsing catalogs, or extending Claude.

prompts.chat

157.5k

prompt-lookup

Searches prompts.chat for AI prompt templates by keyword or category, retrieves by ID with variable handling, and improves prompts via AI. Use for discovering or enhancing prompts.

prompts.chat

157.5k

brainstorming

7 files

Guides idea refinement into designs: explores context, asks questions one-by-one, proposes approaches, presents sections for approval, writes/review specs before coding.

superpowers

134.2k

Stats

Parent Repo Stars28

Parent Repo Forks4

Last CommitApr 1, 2026

Actions

View Source View Plugin View on GitHub View README

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:

**Design Spec**: [Implementation Spec](/docs/design/YYYY-MM-DD-slug/spec.md)

In spec.md header:

**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 for details.

Step P.2: Create ADR File

Create /docs/adr/$ADR_ID.md
Use template from ADR Template
Populate frontmatter from session context
Select perspectives from Perspectives Taxonomy
Use Skill tool to invoke adr-graph-easy-architect for diagrams

Step P.3: Create Design Spec

Create folder: mkdir -p docs/design/$ADR_ID
Copy global plan: cp ~/.claude/plans/<adj-verb-noun>.md docs/design/$ADR_ID/spec.md
Add ADR backlink to spec header

Step P.4: Verify Checkpoint

Run validator or manual checklist:

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

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

SKILL INVOCATION: Invoke adr-graph-easy-architect skill NOW to create BOTH diagrams.

BLOCKING GATE: Do NOT proceed to design spec until BOTH diagrams are embedded in ADR.

Reference Documentation

ADR Template - Complete MADR 4.0 template
Perspectives Taxonomy - 11 perspective types
Workflow Steps - Detailed step-by-step guide

Validation Script

# 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
Diagram not rendering	graph-easy not installed	Run `brew install graph-easy`
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:

Did the command succeed? — If not, fix the instruction or error table that caused the failure.
Did parameters or output change? — If the underlying tool's interface drifted, update Usage examples and Parameters table to match.
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.