/plan-crafting

name: plan-crafting
description: Use when a task's scope is clear and multi-step implementation is needed, before touching code. Triggered after clarification is complete, or when the user explicitly requests plan creation with a clear prompt.

Plan Crafting

Writes an executable plan document from a clearly defined work scope. Designed so tasks can be spawned as "worker-validator" pairs in parallel.

Core Principle

A plan document must be executable by a worker with zero codebase context, without any additional questions. All ambiguity must be resolved at the planning stage.

Hard Gates

1. **Every step must be executable.** Placeholders (TBD, TODO, "implement later") are never allowed. 2. **Task conflicts must be prevented.** Tasks modifying the same file must not run in parallel. Tasks with dependencies must wait for predecessor completion. 3. **Self-Review is mandatory.** After writing the plan, verify its completeness yourself. 4. **Tasks decompose to minimal feature units.** One task produces one clear deliverable.

When To Use

• After the clarification skill completes and a Context Brief file has been generated
• When the user explicitly requests plan creation with a clear prompt
• When multi-step implementation is needed and task ordering with dependencies must be defined

Input

This skill takes a **Context Brief file** as input. The Context Brief generated by the `clarification` skill is used to populate the plan header:

| Context Brief Field | Plan Header Mapping | |---|---| | Goal | **Goal** | | Scope (In/Out) | **Work Scope** (included/excluded) | | Technical Context | **Architecture** + **Tech Stack** + basis for file structure mapping | | Constraints | Reflected as constraints during task decomposition | | Success Criteria | Used as Self-Review criteria | | Open Questions | Reflected as assumptions in the plan, then confirmed with the user |

If no Context Brief file exists (user directly requests a plan): confirm essential information (goal, work scope, tech stack) with the user before writing the plan.

When NOT To Use

• When work scope is still ambiguous (return to the clarification skill)
• Single-file edits, simple bug fixes, or other single-step tasks
• When the user explicitly says "skip the plan, just do it"

Plan Document Structure

Save Location

docs/engineering-discipline/plans/YYYY-MM-DD-<feature-name>.md

(User preferences for plan location override this default.)

Header

# [Feature Name] Implementation Plan

> **Worker note:** Execute this plan task-by-task using the run-plan skill or subagents. Each step uses checkbox (`- [ ]`) syntax for progress tracking.

**Goal:** [One sentence describing what this plan builds]

**Architecture:** [2-3 sentences about approach]

**Tech Stack:** [Key technologies/libraries]

**Work Scope:**
- **In scope:** [What will be implemented]
- **Out of scope:** [What is explicitly excluded]

---

File Structure Mapping

Before defining tasks, map out which files will be created or modified. Decomposition decisions are locked in at this stage.

• Each file should have one clear responsibility.
• Files that change together should live together. Split by responsibility, not by technical layer.
• Follow existing codebase patterns. If the codebase uses large files, don't unilaterally restructure — but if a file you're modifying has grown unwieldy, including a split in the plan is reasonable.
• File structure informs task decomposition. Each task should produce a self-contained change that makes sense independently.

Verification Discovery

Before decomposing tasks, discover the project's highest-level verification capability. This determines the **Final Verification Task** that closes every plan.

**Discovery order (use the first match):**

1. **Existing e2e tests** — search for `e2e/`, `tests/e2e/`, `cypress/`, `playwright/`, `test:e2e` in package.json, `e2e` targets in Makefile/Taskfile 2. **Integration tests** — search for `tests/integration/`, `integration_test`, `test:integration` scripts 3. **Verification skill or agent** — check `.claude/skills/`, `.claude/agents/`, and installed plugins for anything named `verify`, `validate`, `e2e`, or `test` 4. **Project test suite** — any test runner (`pytest`, `jest`, `go test`, `cargo test`, etc.) with broad coverage 5. **Build + lint** — if no tests exist, the highest available verification is a successful build + lint pass

**If no meaningful verification exists (level 5 only):** Add a **Task 0: Create Verification Infrastructure** that sets up the minimal verification needed for this plan:

• Identify the project's tech stack and appropriate test framework
• Create an e2e or integration test that exercises the plan's core success criteria
• This test should fail before implementation and pass after all tasks complete

**Record the discovery result** in the plan header:

**Verification Strategy:**
- **Level:** [e2e | integration | skill/agent | test-suite | build-only]
- **Command:** [exact command to run the verification]
- **What it validates:** [what passing this verification proves]

Project Capability Discovery

Before decomposing tasks, also discover project-level agents and skills that workers can leverage:

1. **Project agents** — check `.claude/agents/` for agents relevant to the task domain (e.g., a `test-runner` agent, a `db-migration` agent) 2. **Plugin agents** — check installed plugins for specialized agents (e.g., `build-validator`, `lint-fixer`) 3. **Project skills** — check `.claude/skills/` for skills that match task operations

If useful agents/skills are found, reference them in task steps where applicable:

- [ ] **Step N: Run migration**

Use the project's `db-migration` agent for this step if available.
Run: `<migration command>`

Workers are not required to use discovered agents — they are hints for efficiency. The worker may execute steps directly if the ag