gh-awudevelop-claude-plugins-session/commands/plan-finalize.md

You are executing the /session:plan-finalize command to transform requirements into executable tasks.

**NOTE:** Plans are now global and independent of sessions.

**CRITICAL - Command Format:**
All session plugin commands use the `/session:` prefix. DO NOT suggest commands without this prefix.
- ✅ Correct: `/session:plan-execute`, `/session:plan-status`, `/session:plan-finalize`
- ❌ Wrong: `/plan-execute`, `/plan-status`, `/plan-show`
Use ONLY the exact command formats specified in this template.

## Arguments

Parsed from user input:
- `plan_name`: {name} (required)

ARGUMENTS: {name}

## Purpose

This is the TRANSFORMATION step that bridges conceptual planning and execution:

**Before (Conceptual - requirements.json):**
```
Requirements (WHAT):
- "Restrict products based on user permissions"
- "Track who created each product"
```

**After (Implementation - orchestration.json + phases/):**
```
Phase 1: Database Layer
  ✓ task-1-1: Add restriction_level column to public.new_product table
  ✓ task-1-2: Create migration script for ALTER TABLE
  ✓ task-1-3: Add created_by column with foreign key to users

Phase 2: API Layer
  ✓ task-2-1: Add validation in POST /api/products endpoint
  ✓ task-2-2: Add validation in PUT /api/products/:id endpoint
  ✓ task-2-3: Return 403 error for restricted products

Phase 3: UI Layer
  ✓ task-3-1: Add restriction checkbox in product form
  ✓ task-3-2: Show error message when restriction fails
```

**This step uses AI to break down requirements into concrete, actionable tasks.**

## Workflow

### Step 1: Load Plan and Validate Format

Plans are global and stored in `.claude/plans/`. Check what format the plan is in:

```bash
node ${CLAUDE_PLUGIN_ROOT}/cli/session-cli.js get-plan-format {plan_name}
```

This returns `format: "conceptual"` or `format: "implementation"`.

**If format is "implementation":**
```
✓ Plan '{plan_name}' is already finalized

This plan has already been transformed into executable tasks.

Use /session:plan-execute {plan_name} to start implementation.
```
Then STOP.

**If format is "conceptual":** Continue to next step.

### Step 2: Load Requirements

Load the requirements.json file from the global plans directory:

```bash
node ${CLAUDE_PLUGIN_ROOT}/cli/session-cli.js load-requirements {plan_name}
```

This returns the requirements data:
```json
{
  "goal": "...",
  "requirements": [
    { "id": "req-1", "description": "...", "priority": "high" },
    { "id": "req-2", "description": "...", "priority": "medium" }
  ],
  "metadata": { "work_type": "feature" }
}
```

### Step 4: Show Requirements Summary

Display what will be transformed:

```
📋 Plan: {plan_name}

Goal: {goal}
Format: Conceptual (requirements)

Requirements to Transform:
  1. req-1: {description} [{priority}]
  2. req-2: {description} [{priority}]
  ... ({total} requirements)

Work Type: {work_type}

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

💡 Finalization Process:

I will use AI to break down each requirement into concrete implementation tasks,
organized by phases (Database, API, UI, Testing, etc.)

This transformation will:
  • Convert high-level requirements into actionable tasks
  • Organize tasks by implementation layer
  • Add implementation details (SQL, API endpoints, UI components)
  • Track which requirement led to which tasks
  • Create execution-ready plan structure

Ready to proceed? (yes/no)
```

### Step 5: Get User Confirmation

Use the AskUserQuestion tool to confirm.

If user says no/cancel, show:
```
Plan finalization cancelled. The plan remains in conceptual format.
```
Then STOP.

If yes, continue.

### Step 6: AI-Powered Task Breakdown

Show progress indicator:
```
🤖 AI Analysis in Progress...

This will take 30-60 seconds.
```

Invoke the Task tool with:
- subagent_type: "general-purpose"
- model: "sonnet"  (use sonnet for better quality breakdown)
- prompt: Read the file at `${CLAUDE_PLUGIN_ROOT}/prompts/breakdown-requirement.md`, replace `[REQUIREMENTS JSON INSERTED HERE]` with the actual requirements JSON, then execute those instructions

The subagent will analyze requirements and return structured breakdown:
```json
{
  "implementation_goal": "...",
  "phases": [
    {
      "name": "Database Layer",
      "description": "...",
      "tasks": [
        {
          "description": "Add restriction_level column to products",
          "details": "ALTER TABLE products ADD COLUMN...",
          "from_requirement": "req-1"
        }
      ]
    }
  ],
  "traceability": {
    "req-1": ["task-1-1", "task-2-1", "task-3-1"],
    "req-2": ["task-1-2", "task-2-2"]
  },
  "assumptions": [...],
  "risks": [...]
}
```

### Step 7: Show Transformation Preview

Display the AI-generated breakdown for user review:

```
✓ AI Analysis Complete

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
📋 Transformation Preview
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Implementation Goal:
{implementation_goal}

Phase 1: {phase_1_name}
  • task-1-1: {description}
  • task-1-2: {description}
  • task-1-3: {description}
  [{task_count} tasks]

Phase 2: {phase_2_name}
  • task-2-1: {description}
  • task-2-2: {description}
  [{task_count} tasks]

Phase 3: {phase_3_name}
  • task-3-1: {description}
  [{task_count} tasks]

[Show all phases]

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Summary:
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

• Requirements: {requirement_count}
• Phases: {phase_count}
• Tasks: {task_count}
• Traceability: Complete (all tasks mapped to requirements)

Assumptions:
  - {assumption_1}
  - {assumption_2}

Risks:
  - {risk_1}
  - {risk_2}

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Does this breakdown look good? (yes/edit/cancel)
```

### Step 8: Handle User Response

**If "yes":** Continue to Step 9

**If "edit":**
```
What would you like to modify?

You can:
  a) Adjust task descriptions
  b) Add/remove tasks
  c) Change phase organization
  d) Add more details to specific tasks
  e) Re-run AI analysis with different focus

Your choice:
```

Based on user input, make modifications and show preview again (repeat Step 7).

**If "cancel":**
```
Finalization cancelled. Plan remains in conceptual format.
```
STOP.

### Step 9: Transform and Save

Show progress:
```
💾 Transforming plan...

Creating implementation structure...
```

Call the transformation function:
```bash
node ${CLAUDE_PLUGIN_ROOT}/cli/session-cli.js transform-plan {plan_name} '{breakdown_json}'
```

This will:
1. Create orchestration.json with metadata and phase registry
2. Create phases/*.json files with tasks
3. Create execution-state.json for progress tracking
4. Keep requirements.json for traceability
5. Mark plan as "implementation" type

### Step 10: Success Message

```
✓ Plan Finalized: {plan_name}

Requirements successfully transformed into executable implementation plan!

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Transformation Summary:
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Input:
  • Format: Conceptual (requirements)
  • Requirements: {requirement_count}

Output:
  • Format: Implementation (orchestration + phases)
  • Phases: {phase_count}
  • Tasks: {task_count}
  • Structure: Optimized for parallel execution

Files Created:
  • orchestration.json (coordinator)
  • phases/phase-1-{name}.json
  • phases/phase-2-{name}.json
  • phases/phase-3-{name}.json
  • execution-state.json (progress tracking)

Preserved:
  • requirements.json (for traceability)

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Next Steps:
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

1. Review the finalized plan:
   /session:plan-status {plan_name}

2. Start execution:
   /session:plan-execute {plan_name}

3. Track progress as you implement each task

🎯 Ready for implementation!
```

---

## Transformation Details

### File Structure

**Before (Conceptual):**
```
plans/{plan_name}/
├── requirements.json          (only file)
└── conversation-context.md    (reference)
```

**After (Implementation):**
```
plans/{plan_name}/
├── requirements.json          (preserved for traceability)
├── orchestration.json         (coordinator + metadata)
├── phases/
│   ├── phase-1-database.json
│   ├── phase-2-api.json
│   └── phase-3-ui.json
├── execution-state.json       (runtime progress)
└── conversation-context.md    (reference)
```

### Traceability

Every task in the implementation plan has a `from_requirement` field:
```json
{
  "task_id": "task-1-1",
  "description": "Add restriction_level column",
  "from_requirement": "req-1"
}
```

This allows you to trace back from implementation tasks to original requirements.

### Why AI-Powered?

Breaking down requirements into tasks requires:
- Understanding of technical architecture (DB → API → UI)
- Knowledge of implementation patterns
- Ability to infer specific tasks from general requirements
- Context about dependencies and ordering

AI excels at this transformation, turning:
- "Restrict products" → 10+ specific tasks across layers
- "Track creators" → Database schema, API logic, UI display

### Quality Assurance

The AI breakdown is trained to:
- Create concrete, actionable tasks (not vague)
- Provide implementation details (SQL, file paths, logic)
- Organize by architectural layers
- Specify dependencies correctly
- Estimate token usage realistically

---

## Error Handling

- **Plan not found**: Show available plans
- **Already finalized**: Show success, suggest execution
- **Invalid session**: Guide to start/continue
- **AI breakdown fails**: Offer retry or manual task creation
- **User cancels**: Keep conceptual format, can retry later

---

## Notes

- Finalization is REQUIRED to execute a plan
- AI breakdown takes 30-60 seconds (uses Sonnet for quality)
- User can review and modify before saving
- Original requirements.json is preserved for traceability
- Transformation is reversible (can re-finalize if needed)
- This is where requirements (WHAT) become tasks (HOW)