planner-workflow

Original：🇺🇸 English

Translated

Phase-level planning workflow for planner agents. Handles reading templates, exploring codebase references, creating plan.md and phase files, self-validation, and checkpoint reporting to the orchestrator. Invoke this skill as your first action — not user-invocable.

1installs

Sourcedarraghh1/my-claude-setup

Added on2026-03-03

NPX Install

npx skill4agent add darraghh1/my-claude-setup planner-workflow

SKILL.md Content

View Translation Comparison →

Planner Phase Workflow

You have been assigned a planning task to create a full plan with phases for a feature. Your spawn prompt contains the feature description, requirements, and plan folder path. This skill teaches you how to handle the entire planning process end-to-end.

Why This Workflow Exists

The user experienced planners that guessed at patterns, skipped template sections, and produced phases with generic code blocks. Each step below prevents a specific failure:

Step	Prevents
Read templates completely	Missing required sections, rework during review
Create task list	Lost progress after context compact, skipped phases
Read codebase references	Code blocks that don't match real project patterns
Checkpoint 1 (plan summary)	Building 20 phases on wrong assumptions — hours wasted
Self-validate each phase	Placeholder content and missing TDD discovered late in review

Step 1: Read Templates

The user created these templates specifically so phases don't miss required sections. Skipping template reading causes incomplete phases that require rework during implementation.

Read both templates completely:

$CLAUDE_PROJECT_DIR/.claude/skills/create-plan/references/PLAN-TEMPLATE.md

$CLAUDE_PROJECT_DIR/.claude/skills/create-plan/references/PHASE-TEMPLATE.md

Every section in these templates is required. Extract the section lists — you'll use them as checklists when writing plan.md and phase files.

Step 2: Create Folder Structure

Folder naming pattern:

plans/{YYMMDD}-{feature-name}/

Examples:

```
plans/260220-voice-assistant/
```
```
plans/260220-notification-system/
```

Create these items:

Main folder:
```
plans/{YYMMDD}-{feature-name}/
```

Planning reviews folder:

plans/{YYMMDD}-{feature-name}/reviews/planning/

Code reviews folder:

plans/{YYMMDD}-{feature-name}/reviews/code/

Step 3: Create Task List

Tasks survive context compacts — skipping this check causes duplicate tasks and lost progress.

Before creating tasks, run

TaskList

to check if tasks already exist from a previous session or before a compact. If tasks exist:

Read existing tasks with
```
TaskGet
```
for each task ID
Find the first task with status
```
pending
```
or
```
in_progress
```
Resume from that task — do NOT recreate the task list

If no tasks exist, create them now. Prefix all task subjects with
[Plan]
to distinguish from the orchestrator's tasks in the shared team task list.

Example task list:

[Plan] Create plan.md scaffold (all sections except Phase Table content)
[Plan] Read codebase references
[Plan] Checkpoint 1 — report plan summary to orchestrator
[Plan] Create Phase 01 - [Title]
[Plan] Create Phase 02 - [Title]
[...continue for all phases...]
[Plan] Checkpoint 2 — report completion to orchestrator

Mark each task

in_progress

before starting and

completed

when done via

TaskUpdate

Step 4: Read Codebase References

Code blocks written from memory often don't match the real codebase — this is the #1 source of phase quality issues. Reading actual files before writing phases ensures patterns are accurate.

Identify which file types the feature will need and read one reference for each:

Feature Needs	Reference to Read
Server actions	Glob `app/home/[account]/*/server-actions*.ts` → read one
Service layer	Glob `app/home/[account]/*/service*.ts` → read one
Zod schemas	Glob `app/home/[account]/*/.schema.ts` → read one
SQL migrations / RLS	Glob `supabase/migrations/*.sql` → read a recent one
React components	Glob `app/home/[account]/*/_components/.tsx` → read one
Page files	Glob `app/home/[account]/**/page.tsx` → read one
Tests	Glob `__tests__/*/.test.ts` → read one

Key patterns to extract and use in phase code blocks:

Server action pattern:
```
'use server'
```
+ Zod parse +
```
getSession()
```
auth check

Account resolution: slug → ID via

client.from('accounts').select('id').eq('slug', data.accountSlug).single()

Permission check: your RLS helper function (e.g.,
```
client.rpc('check_account_access', { ... })
```
)
Supabase client:
```
createClient()
```
from
```
@/lib/supabase/server
```

Service factory:

createXxxService(client: SupabaseClient<Database>)

wrapping a private class

Import paths:
```
import 'server-only'
```
,
```
@/
```
path alias for project root
File naming:
```
_lib/schema/
```
(singular),
```
server-actions.ts
```
, exports ending in
```
Action
```
TypeScript: consider enums or union types for constants,
```
interface
```
preferred for objects
After mutations:
```
revalidatePath('/home/[account]/...')
```

Pre-Implementation Analysis

Before scoping phases, run through the checklist in

.claude/rules/pre-implementation-analysis.md

. Its 7 dimensions — existing patterns, blast radius, security surface, performance, maintainability, multi-tenant safety, and upstream compatibility — directly inform phase boundaries and what each phase's

Prerequisites & Clarifications

section should cover. Findings from this analysis (e.g. "touches auth flow", "new table needs RLS") should surface in the relevant phase files, not be left implicit.

Frontend Guidelines (If Applicable)

If the feature involves React components, Next.js pages, or UI work, invoke this skill BEFORE designing phases:

/vercel-react-best-practices

This loads 57 performance rules across 8 categories. Reference these when designing data fetching patterns, component architecture, and bundle optimisation requirements.

Keep these patterns in mind for every code block you write in phase files. The review step will flag any code blocks that deviate from these codebase patterns.

Step 5: Create plan.md

Write

plans/{folder}/plan.md

with ALL sections from the template:

YAML Frontmatter (title, status, priority, tags, dates)
Executive Summary (Mission, Big Shift, Deliverables)
Phasing Strategy (Phase Constraints, Phase File Naming)
Phase Table — Header row only, no content rows yet
Architectural North Star (patterns with Core Principle + Enforcement)
Component Library Priority (check your UI library before building custom)
Security Requirements (RLS, Input Validation, Authorization, Error Handling)
Implementation Standards (Test Strategy, Documentation Standard)
Success Metrics & Quality Gates
Global Decision Log (ADRs)
Resources & References

Complete ALL sections except Phase Table rows. Missing sections are caught during review but cost extra review cycles to fix.

Phase Constraints

Phases that exceed one context window cause Claude to lose earlier context mid-implementation, producing incomplete or inconsistent code. Each phase should be atomic enough for implementation in 1 context window (~15KB document, ~2-3 hour focused session).

30 small phases > 5 large phases

Wrong Approach	Right Approach
"Phase 01: Database + API + UI"	Split into 3 phases
"Phase 02: Full Feature Implementation"	Break into atomic steps
"Phase 03: Testing and Polish"	TDD is Step 0 in EACH phase

TDD Note: Both backend and frontend code require full unit tests:

Backend (services, schemas, APIs): Unit tests in
```
__tests__/{feature}/
```
Frontend (React/TSX): Component tests using happy-dom (default) and @testing-library/react
The default happy-dom environment works for component tests. Only add
```
// @vitest-environment happy-dom
```
if explicitly overriding another environment.
Use
```
it.todo('description')
```
for TDD stubs
Use
```
vi.hoisted()
```
for mock variables needed before module evaluation
For Supabase client mocks, add
```
.then()
```
method for thenable/awaitable pattern
Path aliases in tests: use your project's configured path alias (e.g.,
```
@/
```
or
```
~/
```
)

The test: Can Claude implement this phase without running out of context? If unsure, split it.

Step 6: Checkpoint 1 — Report Plan Summary

After creating plan.md, report to the orchestrator for user review. This is the key benefit of the team pattern — the user can course-correct before you spend time writing 15 phase files.

SendMessage({
  type: "message",
  recipient: "team-lead",
  content: `## Plan Summary — Ready for Review

**Feature**: {feature name}
**Plan folder**: plans/{YYMMDD}-{feature-name}/

### Executive Summary
{1-2 sentence mission}

### Proposed Phase Breakdown
| # | Title | Group | Skill | Dependencies |
|---|-------|-------|-------|-------------|
| 01 | {title} | {group} | {skill} | None |
| 02 | {title} | {group} | {skill} | Phase 01 |
...

### Group Summary
| Group | Phases | Description |
|-------|--------|-------------|
| {name} | P01-P03 | {what this group delivers} |

### Architecture Decisions
- {key decision 1}
- {key decision 2}

### Security Requirements
- {key requirement}

Awaiting approval or feedback before creating phase files.`,
  summary: "Plan summary ready for review"
})

Then WAIT. Do not proceed to Step 7 until the orchestrator responds with approval or feedback.

If approved: Continue to Step 7.
If changes requested: Revise plan.md and the phase breakdown, then re-send the summary. Repeat until approved.

Step 7: Create Phases (Iterative)

For EACH phase, in order:

7a: Add Row to Phase Table

Edit

plan.md

to add the phase row:

markdown

| **01** | [Title](./phase-01-slug.md) | [group-name] | [Focus] | Pending |

7b: Create Phase File

Write the complete phase file following PHASE-TEMPLATE.md exactly.

File:

plans/{folder}/phase-{NN}-{slug}.md

Include
skill
in Frontmatter — without it, the implementer won't know which skill to invoke and will use generic patterns instead of project-specific ones.

Phase Type	Skill Value
Database schema, migrations, RLS	`postgres-expert`
Server actions, services, API	`server-action-builder`
React forms with validation	`react-form-builder`
E2E tests	`playwright-e2e`
React components/pages	`vercel-react-best-practices`
UI/UX focused work	`web-design-guidelines`

Example frontmatter:

yaml

---
title: "Phase 01 - Database Schema"
skill: postgres-expert
status: pending
group: "auth-system"
dependencies: []
---

Group assignment rules:

Connected phases building the same feature/component MUST share a
```
group:
```
name
Group names should be descriptive:
```
auth-system
```
,
```
dashboard-ui
```
,
```
data-pipeline
```
Single-phase groups are valid for standalone work
Groups define audit boundaries — after all phases in a group complete during implementation, an auditor reviews them together
Order groups so dependencies flow top-to-bottom (group A before group B if B depends on A)

For phases spanning multiple concerns, list the primary skill or use comma-separated values:

yaml

skill: react-form-builder, vercel-react-best-practices

Required sections (from template):

YAML Frontmatter (title, description, status, dependencies, tags, dates, skill)
Overview (brief description, single-sentence Goal)
Context & Workflow (How the Project Uses This, User Workflow, Problem Being Solved)
Prerequisites & Clarifications (Questions for User with Context/Assumptions/Impact)
Requirements (Functional + Technical)
Decision Log (phase-specific ADRs)
Implementation Steps — Step 0: TDD is first
Verifiable Acceptance Criteria (Critical Path, Quality Gates, Integration)
Quality Assurance (Manual Testing, Automated Testing, Performance Testing, Review Checklist)
Dependencies (Upstream, Downstream, External)
Completion Gate (Sign-off checklist)

Code blocks in phases should match codebase patterns from Step 4 — not memory, not generic examples. Generic code blocks cause the implementer to write code that doesn't follow project conventions, creating rework. If you don't remember the exact pattern, re-read the reference file from Step 4 before writing the code block.

7c: Validate Phase Quality

After creating each phase file, run these validators to catch issues immediately (before review agents get involved):

bash

# Check for skeleton/placeholder content
echo '{"cwd":"."}' | uv run $CLAUDE_PROJECT_DIR/.claude/hooks/validators/validate_no_placeholders.py \
  --directory plans/{folder} --extension .md

# Check TDD tasks appear before implementation tasks
echo '{"cwd":"."}' | uv run $CLAUDE_PROJECT_DIR/.claude/hooks/validators/validate_tdd_tasks.py \
  --directory plans/{folder} --extension .md

# Confirm the phase file was actually created
echo '{"cwd":"."}' | uv run $CLAUDE_PROJECT_DIR/.claude/hooks/validators/validate_new_file.py \
  --directory plans/{folder} --extension .md

If any validator exits non-zero, fix the issue before moving to the next phase. Placeholder content and missing TDD steps are the two most common causes of rework during implementation.

7d: Update Task Status

Mark the phase task as completed, move to next phase.

7e: Repeat

Continue until all phases are created.

Step 8: Checkpoint 2 — Report Completion

After all phases are created and validated, send a full summary to the orchestrator:

SendMessage({
  type: "message",
  recipient: "team-lead",
  content: `## Plan Complete — All Phases Created

**Plan folder**: plans/{YYMMDD}-{feature-name}/
**Phases**: {count} phases created

### Phase Breakdown
| # | Title | Group | Skill | Dependencies | Self-Validation |
|---|-------|-------|-------|-------------|-----------------|
| 01 | {title} | {group} | {skill} | None | Passed |
| 02 | {title} | {group} | {skill} | Phase 01 | Passed |
...

### Dependency Graph
{describe the dependency flow — which phases unlock which}

### Self-Validation Results
- Placeholder check: {pass/fail count}
- TDD ordering: {pass/fail count}
- File creation: {pass/fail count}

Ready for review via /review-plan.`,
  summary: "All phases created — ready for review"
})

Then go idle. The orchestrator will handle spawning review validators and routing feedback.

Resuming After Context Compact

If your context was compacted mid-planning:

```
TaskList
```
→ find the
```
in_progress
```
or first
```
pending
```
task
```
TaskGet
```
on that task → read the self-contained description
Continue from that task — don't restart the planning process
The task list is your source of truth, not your memory

Pattern for every work cycle:

TaskList → find in_progress or first pending → TaskGet → continue work → TaskUpdate (completed) → next task

Tasks are the planner's source of truth for progress — not memory, not plan.md alone.

Troubleshooting

Context Window Overflow

Symptom: Planner loses track of phases mid-creation, produces incomplete or inconsistent output.

Cause: Too many phases being created without task tracking, or codebase references consuming too much context.

Fix: Follow Task List pattern in Step 3 — mark tasks complete as you go. For codebase references, read only what you need (one file per type).

Missing Template Sections

Symptom: Review agents flag missing sections in plan.md or phase files.

Cause: Template not read before writing, or sections skipped during creation.

Fix: Re-read the template (

$CLAUDE_PROJECT_DIR/.claude/skills/create-plan/references/PLAN-TEMPLATE.md

PHASE-TEMPLATE.md

) and add the missing sections. Each section exists because omitting it caused implementation problems.

Code Blocks Don't Match Codebase

Symptom: Review agents flag code blocks as not matching project patterns.

Cause: Code blocks written from memory instead of from codebase references.

Fix: Re-read the reference file from Step 4 for the relevant file type. Copy the actual pattern — function signatures, imports, naming conventions — into the code block.

Orchestrator Not Responding After Checkpoint

Symptom: Sent checkpoint message but no response.

Cause: The orchestrator relays your checkpoint to the user, who may need time to review. This is expected.

Fix: Wait. Do not proceed past a checkpoint without orchestrator approval. The whole point of checkpoints is user course-correction.