| name | plan-discipline |
| description | Get a plan into its one canonical home — the tracker plan.md — never .claude/plans. Run this skill when you enter plan mode (EnterPlanMode), when you have a plan draft (incl. plan-mode / ExitPlanMode output), or when a task enters brainstorm→plan. It walks task creation and draft→tracker authoring, including the plan-mode two-phase flow. |
| license | MIT |
Plan Discipline
A plan is always a task, authored into <ai_hats_dir>/tracker/backlog/tasks/<ID>/plan.md. Nowhere else.
When to Use
- On
EnterPlanMode, recall this skill — so you treat the plan-mode draft as
scratch and persist it into the tracker the moment you exit (see the two-phase
flow below). Plan mode is for designing + approval; the plan of record still
becomes a task in the tracker.
- Also whenever a plan must be persisted — a draft in chat or a plan-mode
artifact — even if no task exists yet.
- This skill is the plan's home and transport (where the file lives, how the
draft gets there). For filling each section well, hand off to plan-gate
(it routes Requirements / Scope / Steps / Verification to their owners). Don't
duplicate that here.
- Not an enforcement gate: the engine per-section gate (HATS-635) blocks
rack transition <ID> execute on an empty plan. This skill is the authoring discipline
upstream of it; the gate is the backstop.
Procedure
rack CLI commands (reads, transitions, logs) can be run from either the main repo or any linked worktree — root resolution automatically finds the main repo's .agent/ tracker. (Teardown commands like ai-hats wt merge / discard or closing transition done should be run from the main repo so your shell cwd isn't removed underfoot — see skill worktree-isolation / HATS-788).
Preferred — plan directly in the tracker (no plan mode)
When you control the flow, skip Claude Code plan mode and author straight into the
tracker — zero round-trip, no .claude/plans file.
- Make the task (if none):
rack create "<title>" --description "<intent>" [--priority high|medium|low] [--id PROJ-NNN] — starts in brainstorm; clarify scope there if fuzzy.
- Scaffold:
rack transition <ID> plan → empty <ai_hats_dir>/tracker/backlog/tasks/<ID>/plan.md.
- Author into it (Write/Edit), filling the required sections (route each via
plan-gate). rack transition <ID> execute stays blocked until they're non-empty.
In Claude Code plan mode — two phases
Plan mode is read-only: it blocks the rack CLI and every write except
.claude/plans/<slug>.md, so the tracker flow is impossible until you exit.
That's expected — don't fight it, and don't apologise for the draft.
- Phase 1 — in plan mode: design; draft into
.claude/plans/<slug>.md;
present via ExitPlanMode. Do not attempt rack create / rack transition
/ tracker writes — they are blocked. The draft is scratch, not the plan of record.
- Phase 2 — immediately on approval / exit: your first action, before any
other execute work, is to persist into the tracker —
rack create (if needed)
→ rack transition <ID> plan → Read the .claude/plans draft → Write it into
<ai_hats_dir>/tracker/backlog/tasks/<ID>/plan.md → fill/confirm sections → rack transition <ID> execute. There
is no auto-sync (HATS-637); the .claude/plans file is now inert, leave or delete.
Completion
<ai_hats_dir>/tracker/backlog/tasks/<ID>/plan.md holds the real plan; no task-bearing file remains in
.claude/plans; rack transition <ID> execute passes the gate.- Handoff: plan in tracker →
plan-gate (section quality) → engine gate → execute.
Anti-Patterns
- Treating the plan-mode
.claude/plans/<slug>.md as the plan — in plan mode it is
Phase-1 scratch; the plan isn't real until transferred to the tracker on exit.
- Skipping the Phase-2 transfer (or deferring it behind other execute work) —
persisting into the tracker is the first post-approval action.
- Fighting plan mode by trying
rack CLI / tracker writes while still in it — they
are blocked; draft, exit, then persist.
- Drafting a plan without a task — if it's a plan, you made a task.
- Running worktree teardown commands (
ai-hats wt merge / wt discard or terminal transition done) from inside the worktree being deleted — this orphans your shell (HATS-788). Return to the main repo first.
