10 KiB
10 KiB
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-showUse 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:
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:
node ${CLAUDE_PLUGIN_ROOT}/cli/session-cli.js load-requirements {plan_name}
This returns the requirements data:
{
"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:
{
"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:
node ${CLAUDE_PLUGIN_ROOT}/cli/session-cli.js transform-plan {plan_name} '{breakdown_json}'
This will:
- Create orchestration.json with metadata and phase registry
- Create phases/*.json files with tasks
- Create execution-state.json for progress tracking
- Keep requirements.json for traceability
- 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:
{
"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)