Plan a Phase

Creates a KICKOFF.md (phase contract) and PLAN.md (task list) for a phase from the roadmap. The kickoff prevents vague phases from producing wrong implementations. The plan breaks the goal into concrete, verifiable tasks.

Trace marker (when running under eval hooks): write plan-phase to .planning/.trace-active-skill at start, clear at end. See skills/create-skill/SKILL.md → "Trace marker contract" for the why.

Step 1: Bootstrap context

gad snapshot --projectid <id>

This gives you state, roadmap, tasks, decisions, and file refs in one low-token command. Identify the target phase from the snapshot.

Which phase? If the user specified one, use that. Otherwise, find the next planned phase in the roadmap (shown in the snapshot).

If you need more detail on requirements, run gad requirements --projectid <id>. Do NOT manually read STATE, ROADMAP, DECISIONS, or TASK-REGISTRY files — the snapshot already gave you that.

Step 2: Run the kickoff

A kickoff is required when any of these are true:

• The phase goal is vague ("improve performance", "refactor auth")
• The phase has been idle (assumptions may have changed)
• The phase is large (rough estimate > 1 day of work)
• The phase has dependencies that aren't clearly met

Even for clear phases, a kickoff is cheap insurance against scope creep.

Ask (inline):

• "What's the specific goal of this phase? What will someone be able to do when it's done?"
• "What's explicitly not included in this phase?"
• "What are the testable conditions that make this phase complete?"
• "Any open questions before we define tasks?"

Fill in the kickoff template. See references/kickoff-template.md for the full structure.

Write .planning/phases/<phase-id>/KICKOFF.md:

## Kickoff: `<phase-id>`

| Field | Value |
|-------|-------|
| `goal` | [one sentence] |
| `scope` | [what's included, specifically] |
| `non-goals` | [what's explicitly not in this phase] |
| `definition-of-done` | [observable conditions — tests pass, build passes, what a human can verify] |
| `tests-required` | [which tests must exist before this closes] |
| `dependencies` | [phase IDs or named things that must be done first] |
| `open-questions` | [questions to answer before or during execution] |
| `first-tasks` | [the first 2–4 task IDs] |

Step 3: Break down tasks

Derive tasks from the kickoff scope and requirements. Good tasks:

• Are atomic (one logical change, one PR if needed)
• Have a clear verification command (pnpm test, pnpm build, etc.)
• Are ordered by dependency
• Use the phase ID format: <namespace>-<stream>-<phase>-<task>

Write .planning/phases/<phase-id>/PLAN.md:

# Phase `<phase-id>`: <Phase Name>

**Goal:** [from kickoff]

## Tasks

| Id | Status | Goal | Depends | Verify |
|----|--------|------|---------|--------|
| `<phase-id>-01` | `planned` | [task goal] | `-` | `pnpm test` |
| `<phase-id>-02` | `planned` | [task goal] | `<phase-id>-01` | `pnpm test` |
| `<phase-id>-03` | `planned` | [task goal] | `<phase-id>-02` | `pnpm test && pnpm build` |

## Definition of done

[From kickoff — what a human verifies when this phase closes]

## Tests required

[From kickoff — specific test files or coverage requirements]

Step 4: Update planning docs

Add the tasks to the main task registry.

In TASK-REGISTRY (XML or MD, whichever the project uses), add a new section:

## Phase `<phase-id>`

**Goal:** [phase goal]

| Id | Status | Goal | Depends | Verify |
|----|--------|------|---------|--------|
| `<phase-id>-01` | `planned` | [task goal] | `-` | `pnpm test` |
...

Update ROADMAP (XML or MD) to show the phase as active (if starting now) or leave as planned with a link to the kickoff.

Update STATE (XML or MD):

## Current cycle

| Field | Value |
|-------|-------|
| `phase` | `<phase-id>` — [goal] |
| `focus` | kickoff complete; first tasks are <phase-id>-01, <phase-id>-02 |

## Next queue

| Priority | Action | Type |
|----------|--------|------|
| `1` | `<phase-id>-01`: [task goal] | `implementation` |
| `2` | `<phase-id>-02`: [task goal] | `implementation` |

Step 5: Commit and present

git add .planning/
git commit -m "docs(<phase-id>): kickoff and task plan"

Present the outcome:

Phase `<phase-id>` planned.

Goal: [goal]

Tasks:
  <phase-id>-01: [goal]
  <phase-id>-02: [goal] (depends: -01)
  <phase-id>-03: [goal] (depends: -02)

Definition of done: [summary]
Tests required: [summary]

Start with task <phase-id>-01.
After each task: flip status in TASK-REGISTRY.md, update STATE.md focus.
When all tasks done: verify DoD, then mark phase done in ROADMAP.md.

For MDX-based monorepos

Write kickoff and plan to:

docs/<section>/planning/plans/<phase-id>/KICKOFF.mdx
docs/<section>/planning/plans/<phase-id>/PLAN.mdx

Add frontmatter:

---
title: <Phase Name> (kickoff)
taskPhase: <phase-id>
repoPath: docs/<section>/planning/plans/<phase-id>/KICKOFF.mdx
---

Closing a phase

When all tasks are done:

1. Verify the definition of done — tests pass, build passes, the human check works
2. Write a SUMMARY.mdx/md: what was built, what changed, decisions made
3. Update ROADMAP.md: status → done, focus → "maintain only"
4. Update STATE.md: advance to next phase
5. Update TASK-REGISTRY.md: all tasks → done
6. Record any decisions in DECISIONS.md
7. Record any failed approaches in ERRORS-AND-ATTEMPTS.md
8. Commit: git commit -m "docs(<phase-id>): close phase"

Reference files

• references/kickoff-template.md — full kickoff template and example
• references/plan-quality.md — what makes a good task list