Plan Generator Skill

<identity> Plan Generator Skill - Creates structured, validated plans from requirements by coordinating with specialist agents and generating comprehensive planning artifacts. </identity> <capabilities> - Creating plans for new features - Planning refactoring efforts - Planning system migrations - Planning architecture changes - Breaking down complex requirements - Validating existing plans </capabilities> <instructions> <execution_process>

Step 0: Previous Task Intelligence (Cross-Task Context)

Before creating a new plan, gather context from recent work to avoid duplication and build on prior decisions:

1. Recent commits: Run git log --oneline -5 to see what was recently shipped
2. Recent tasks: Call TaskList() to check for completed tasks with relevant metadata
3. Recent decisions: Read .claude/context/memory/decisions.md for architectural choices that constrain this plan
4. Recent issues: Read .claude/context/memory/issues.md for known blockers or workarounds

Use this context to:

• Avoid re-implementing features that were recently shipped
• Respect architectural decisions already made (don't contradict them without escalation)
• Build on completed work rather than starting from scratch
• Reference specific commit hashes or task IDs when relevant

Step 1: Analyze Requirements

Parse user requirements:

• Extract explicit requirements
• Identify implicit requirements
• Determine planning scope
• Assess complexity

Step 2: Coordinate Specialists

Request planning input from relevant agents:

• Analyst: Business requirements and market context
• PM: Product requirements and user stories
• Architect: Technical architecture and design
• Database Architect: Data requirements
• UX Expert: Interface requirements

Step 3: Generate Plan Structure

Create plan following this EXECUTABLE structure:

# Plan: [Title]

## Executive Summary

[2-3 sentence overview]

## Objectives

- [Objective 1]
- [Objective 2]

## Phases

### Phase N: [Phase Title]

**Dependencies**: [Phase numbers or 'None']
**Parallel OK**: [Yes/No - can tasks run concurrently?]

#### Tasks

- [ ] **N.1** [Task description] (~X min)
  - **Command**: `actual shell command here`
  - **Verify**: `command to verify success`
  - **Rollback**: `command to undo if needed`

- [ ] **N.2** [Task description] (~X min) [⚡ parallel OK]
  - **Command**: `...`
  - **Verify**: `...`

#### Phase N Error Handling

If any task fails:

1. Run rollback commands for completed tasks (reverse order)
2. Document error: `echo "Phase N failed: [error]" >> .claude/context/memory/issues.md`
3. Do NOT proceed to Phase N+1

#### Phase N Verification Gate

```bash
# All must pass before proceeding
[verification commands]
```

Risks

Risk	Impact	Mitigation	Rollback
[Risk]	[H/M/L]	[Strategy]	[Command]

Timeline Summary

Phase	Tasks	Est. Time	Parallel?
1	5	30 min	Partial
2	3	20 min	No

### The Executable Task Format (MANDATORY)

Every task MUST include:
1. **Checkbox** - `- [ ]` for progress tracking
2. **ID** - `N.M` format for reference
3. **Time estimate** - `(~X min)`
4. **Command** - Actual executable command
5. **Verify** - Command to confirm success
6. **Rollback** - Command to undo (if applicable)
7. **Parallel marker** - `[⚡ parallel OK]` if can run concurrently

**Enhanced task format with structured completion fields** (verify/done/files are OPTIONAL — omit for backward compatibility):

```markdown
- [ ] **N.1** [Task description] (~X min)
  - **Command**: `actual shell command here`
  - **Verify**: `pnpm test -- --grep "pattern"` (command proving task is done)
  - **Done**: [measurable criteria for "done" — e.g. "All tests pass, lint clean, file exists"]
  - **Files**: [`path/to/file1`, `path/to/file2`] (files this task creates or modifies)
  - **Rollback**: `command to undo if needed`
```

> **Schema**: Full task structure is documented in `.claude/schemas/plan-format.schema.json`.
> The `verify`, `done`, and `files` fields are optional — existing plans without them remain valid.

### Guidelines
- Define clear objectives
- Break down into phases (<=7 phases total)
- Each phase has <=7 tasks
- Every task has executable commands
- Include verification gates between phases
- For **HIGH** or **EPIC** complexity tasks, invoke `discuss-phase` skill BEFORE generating the plan to surface ambiguities and resolve scope, architecture, and acceptance criteria questions with the user

### Step 4: Assess Risks

Identify risks and mitigation:

- Technical risks
- Resource risks
- Timeline risks
- Dependency risks
- Mitigation strategies

### Step 5: Validate Plan

Validate plan completeness:

- All requirements addressed
- Dependencies mapped
- Success criteria defined
- Risks identified
- Plan is feasible

### Step 6: Generate Artifacts

Create plan artifacts using the template-renderer skill:

**Using Template-Renderer**:
After creating plan data structure, invoke template-renderer to generate formatted output:

```javascript
// Map plan data to template tokens
const planTokens = {
  PLAN_TITLE: plan.title,
  DATE: new Date().toISOString().split('T')[0],
  FRAMEWORK_VERSION: 'Agent-Studio v3.1.0',
  STATUS: plan.status || 'Phase 0 - Research',
  EXECUTIVE_SUMMARY: plan.executiveSummary,
  TOTAL_TASKS: `${plan.totalTasks} atomic tasks`,
  FEATURES_COUNT: plan.features.length,
  ESTIMATED_TIME: plan.estimatedTime,
  STRATEGY: plan.strategy,
  KEY_DELIVERABLES_LIST: plan.keyDeliverables.map(d => `- ${d}`).join('\n'),
  // Phase-specific tokens
  PHASE_0_PURPOSE: plan.phases[0].purpose,
  PHASE_0_DURATION: plan.phases[0].duration,
  PHASE_1_NAME: plan.phases[1].name,
  PHASE_1_PURPOSE: plan.phases[1].purpose,
  PHASE_1_DURATION: plan.phases[1].duration,
  DEPENDENCIES: plan.phases[1].dependencies,
  PARALLEL_OK: plan.phases[1].parallelOk ? 'Yes' : 'No',
  VERIFICATION_COMMANDS: plan.phases[1].verificationCommands,
  // Add more phase tokens as needed
};

// Invoke template-renderer skill
Skill({
  skill: 'template-renderer',
  args: {
    templateName: 'plan-template',
    outputPath: `.claude/context/plans/${planId}.md`,
    tokens: planTokens
  }
});
```

**Output Locations**:
- Plan markdown (from template): `.claude/context/plans/<plan-id>.md`
- Plan JSON (structured data): `.claude/context/plans/<plan-id>.json`
- Plan summary (for quick reference)
</execution_process>

<plan_types>
**Feature Development Plan**:

- Objectives: Feature goals
- Steps: Analysis -> Design -> Implementation -> Testing
- Agents: Analyst -> PM -> Architect -> Developer -> QA

**Refactoring Plan**:

- Objectives: Code quality goals
- Steps: Analysis -> Planning -> Implementation -> Validation
- Agents: Code Reviewer -> Refactoring Specialist -> Developer -> QA

**Migration Plan**:

- Objectives: Migration goals
- Steps: Analysis -> Planning -> Execution -> Validation
- Agents: Architect -> Legacy Modernizer -> Developer -> QA

**Architecture Plan**:

- Objectives: Architecture goals
- Steps: Analysis -> Design -> Validation -> Documentation
- Agents: Architect -> Database Architect -> Security Architect -> Technical Writer
</plan_types>

<integration>
**Integration with Planner Agent**:
Planner agent uses this skill to:
- Generate plans from requirements
- Coordinate specialist input
- Validate plan completeness
- Track plan execution
</integration>

<best_practices>

1. **Coordinate Early**: Get specialist input before finalizing plan
2. **Keep Steps Focused**: <=7 steps per plan section
3. **Map Dependencies**: Clearly identify prerequisites
4. **Assess Risks**: Identify and mitigate risks proactively
5. **Validate Thoroughly**: Ensure plan is complete and feasible
</best_practices>
</instructions>

<examples>
<formatting_example>
**Example Plan Output**

**Command**: "Generate plan for user authentication feature"

**Generated Plan**:

```markdown
# Plan: User Authentication Feature

## Executive Summary
Add JWT-based authentication with login/logout endpoints. Includes password hashing, session management, and security testing.

## Objectives
- Implement JWT-based authentication
- Support login, logout, and session management
- Provide secure password handling

## Phases

### Phase 1: Setup & Design
**Dependencies**: None
**Parallel OK**: Partial

#### Tasks
- [ ] **1.1** Create feature branch (~2 min)
  - **Command**: `git checkout -b feature/auth`
  - **Verify**: `git branch --show-current | grep feature/auth`

- [ ] **1.2** Create auth module directory (~1 min) [⚡ parallel OK]
  - **Command**: `mkdir -p src/auth`
  - **Verify**: `ls -d src/auth`

- [ ] **1.3** Design auth architecture (~15 min)
  - **Command**: `Task({ task_id: 'task-1', agent: "architect", prompt: "Design JWT auth..." })`
  - **Verify**: `ls .claude/context/artifacts/auth-design.md`

#### Phase 1 Verification Gate
```bash
git branch --show-current | grep feature/auth && ls src/auth && ls .claude/context/artifacts/auth-design.md

Phase 2: Implementation

Dependencies: Phase 1 Parallel OK: No (sequential TDD)

Tasks

• 2.1 Write auth endpoint tests (~10 min)

  • Command: Task({ task_id: 'task-2', agent: "developer", prompt: "TDD: Write failing tests for /login endpoint" })
  • Verify: npm test -- --grep "login" 2>&1 | grep -E "failing|FAIL"
  • Rollback: git checkout -- src/auth/__tests__/

• 2.2 Implement login endpoint (~15 min)

  • Command: Task({ task_id: 'task-3', agent: "developer", prompt: "Implement login to pass tests" })
  • Verify: npm test -- --grep "login" 2>&1 | grep -E "passing|PASS"

• 2.3 Implement logout endpoint (~10 min)

  • Command: Task({ task_id: 'task-4', agent: "developer", prompt: "TDD: logout endpoint" })
  • Verify: npm test -- --grep "logout" 2>&1 | grep -E "passing|PASS"

Phase 2 Error Handling

If any task fails:

1. Run: git stash && git checkout -- src/auth/
2. Document: echo "Phase 2 failed: $(date)" >> .claude/context/memory/issues.md
3. Do NOT proceed to Phase 3

Phase 2 Verification Gate

npm test -- --grep "auth" && echo "All auth tests passing"

Phase 3: Security Review

Dependencies: Phase 2 Parallel OK: Yes

Tasks

• 3.1 Security audit (~20 min) [⚡ parallel OK]

  • Command: Task({ task_id: 'task-5', agent: "security-architect", prompt: "Audit auth implementation" })
  • Verify: ls .claude/context/reports/security/security-audit.md

• 3.2 Run security tests (~5 min) [⚡ parallel OK]

  • Command: npm run test:security
  • Verify: echo $? (exit code 0)

Risks

Risk	Impact	Mitigation	Rollback
JWT secret exposure	High	Use env vars	Rotate secret immediately
SQL injection	High	Parameterized queries	git revert HEAD

Timeline Summary

Phase	Tasks	Est. Time	Parallel?
1	3	18 min	Partial
2	3	35 min	No
3	2	25 min	Yes
Total	8	~78 min

**After plan generation**, invoke template-renderer:

```javascript
// Map plan data to tokens
const tokens = {
  PLAN_TITLE: 'User Authentication Feature',
  DATE: '2026-01-28',
  FRAMEWORK_VERSION: 'Agent-Studio v3.1.0',
  STATUS: 'Phase 0 - Research',
  EXECUTIVE_SUMMARY: 'Add JWT-based authentication with login/logout endpoints...',
  TOTAL_TASKS: '8 atomic tasks',
  FEATURES_COUNT: '1',
  ESTIMATED_TIME: '~78 minutes',
  STRATEGY: 'Foundation-first → Core features → Security review',
  KEY_DELIVERABLES_LIST: '- Authentication module\n- Login/logout endpoints\n- Security audit',
  PHASE_1_NAME: 'Setup & Design',
  PHASE_1_PURPOSE: 'Create feature branch and design architecture',
  PHASE_1_DURATION: '18 minutes',
  DEPENDENCIES: 'None',
  PARALLEL_OK: 'Partial',
  VERIFICATION_COMMANDS: 'git branch --show-current | grep feature/auth && ls src/auth',
};

// Render plan using template
Skill({
  skill: 'template-renderer',
  args: {
    templateName: 'plan-template',
    outputPath: '.claude/context/plans/user-auth-plan.md',
    tokens: tokens
  }
});

</formatting_example> </examples>

Canonical Section Order (IRON LAW)

Every plan emitted by plan-generator MUST contain exactly these 6 top-level sections in this exact order:

1. ## Problem — why this work matters; the pain point or gap being addressed
2. ## Decision — what is being done; the chosen approach (not the steps, just the choice)
3. ## Scope — what is IN scope; explicitly list what is OUT of scope
4. ## Risks — what could go wrong; include mitigations and rollback commands
5. ## Steps — ordered implementation checklist using - [ ] task format
6. ## Done Criteria — acceptance criteria; objective conditions that prove the work is complete

Rules:

• All 6 sections MUST be present — plans missing any section are invalid
• Sections MUST appear in the order listed above — reordering is invalid
• Each section must have substantive content (not a placeholder like "TBD")
• Sub-sections and additional detail are allowed within each section
• The pre-completion-validation hook enforces this order at task completion (severity: warning)

Why fixed order? AI-generated plans frequently reorder sections or omit scope/risks, causing incomplete execution. Fixed ordering enables automated validation and catches AI-slopped plans before they reach execution.

Iron Laws

1. ALWAYS include an executable command in every task — a task without a command is a wish, not an action; plans with wishes stall at execution because agents have nothing to run.
2. NEVER create a phase with more than 7 tasks — phases exceeding 7 tasks cause cognitive overload, lose parallel opportunities, and make rollback scoping impossible.
3. ALWAYS include a verification gate between every phase — proceeding without verification means failures in Phase N are discovered in Phase N+3, making rollback exponentially more complex.
4. NEVER generate a plan without explicit rollback commands for destructive operations — a plan without rollback paths is unrecoverable; rollback must be specified before the operation is attempted.
5. ALWAYS coordinate specialist input (Analyst, PM, Architect) before finalizing a plan — plans generated without domain expert review routinely miss implicit requirements, producing incomplete execution paths.
6. ALWAYS include a mandatory "Final: Self-review + token report" task as the LAST task in every plan — without this task, pipelines complete without cost visibility or quality self-assessment, and post-pipeline hooks never trigger.
7. ALWAYS emit the 6 canonical sections (Problem → Decision → Scope → Risks → Steps → Done Criteria) in exactly that order — plans with missing or reordered sections are rejected by pre-completion-validation.

MANDATORY FINAL TASK (IRON LAW — NEVER SKIP)

Every plan MUST include this as the LAST task, blocked by all other tasks:

Task: "Final: Self-review + token report"

• Description: "Run ccusage to display today's token/cost (npx ccusage@latest --model --today). Then self-review: Can I improve any deliverable from this pipeline? If yes, create a reflection via reflection-spawn-request.json. NEVER dismiss failures as pre-existing. Mark metadata.isFinalTask = true and metadata.pipelineComplete = true in TaskUpdate(completed)."
• This task is NEVER optional. It is part of every plan regardless of complexity.
• The task must set metadata.isFinalTask = true so post-pipeline hooks trigger.

Example TaskCreate for planners to emit:

TaskCreate({
  subject: "Final: Self-review + token report",
  description: "1. Run: npx ccusage@latest --model --today — display token costs\n2. Self-review all deliverables: Can I improve this?\n3. If improvements found, queue reflection-spawn-request\n4. NEVER dismiss failures as pre-existing\n5. TaskUpdate(completed, { metadata: { isFinalTask: true, pipelineComplete: true } })",
  activeForm: "Running self-review and token report"
})

Rules

The Iron Law of Planning

EVERY TASK MUST HAVE AN EXECUTABLE COMMAND

A task without a command is not a task - it's a wish.

Mandatory Elements

• Every task must have: checkbox, ID, time estimate, command, verify
• Every phase must have: verification gate, error handling
• Every risk must have: rollback command

Anti-Patterns (DO NOT)

Anti-Pattern	Problem	Fix
"Install X" without command	Not executable	Add: cp -r source dest
"Verify Y works"	Vague	Add: npm test | grep PASS
"Update Z"	What file? What change?	Add exact Edit or sed command
No time estimates	Can't track progress	Add (~X min) to every task
No rollback	Can't recover from failure	Add rollback command

Quality Checklist

Before finalizing any plan, verify:

• Can I copy-paste every command and run it?
• Does every verify command have a clear pass/fail output?
• Does each task have a verify command that proves completion objectively?
• Does each task have a done criteria that is measurable and unambiguous?
• Is there a rollback for every destructive operation?
• Are time estimates realistic and granular?
• Are parallel tasks marked with ⚡?

Template Integration

This skill uses the template-renderer skill to generate formatted plans:

Integration Flow:

1. plan-generator creates structured plan data (JSON)
2. Maps plan data to template tokens (see Step 6)
3. Invokes template-renderer with plan-template
4. Outputs rendered plan to .claude/context/plans/

Required Tokens (for plan-template):

• Core: PLAN_TITLE, DATE, FRAMEWORK_VERSION, STATUS
• Summary: EXECUTIVE_SUMMARY, TOTAL_TASKS, ESTIMATED_TIME, STRATEGY
• Phases: PHASE_N_NAME, PHASE_N_PURPOSE, DEPENDENCIES, PARALLEL_OK
• Verification: VERIFICATION_COMMANDS

See .claude/templates/plan-template.md for complete token list.

Related Skills

• template-renderer - Renders plan-template with token replacement
• writing-plans - Bite-sized task plans with complete code for implementation
• discuss-phase - Requirement disambiguation for HIGH/EPIC tasks before planning

Memory Protocol (MANDATORY)

Before starting:

cat .claude/context/memory/learnings.md

After completing:

• New pattern -> .claude/context/memory/learnings.md
• Issue found -> .claude/context/memory/issues.md
• Decision made -> .claude/context/memory/decisions.md

ASSUME INTERRUPTION: Your context may reset. If it's not in memory, it didn't happen.