Plan Generator

Plan Generator Skill

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

Timeline Summary

### 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

Timeline Summary

**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
  }
});

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)

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.