Initial commit

2025-11-29 17:59:29 +08:00
commit 681c2e46c0
31 changed files with 6218 additions and 0 deletions
--- a/commands/plan-finalize.md
+++ b/commands/plan-finalize.md
@@ -0,0 +1,403 @@
+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)