Initial commit

2025-11-29 17:59:29 +08:00
commit 681c2e46c0
31 changed files with 6218 additions and 0 deletions
--- a/commands/plan-save.md
+++ b/commands/plan-save.md
@@ -0,0 +1,285 @@
+You are executing the /session:save-plan command to create a conceptual plan from the current conversation.
+
+**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`, `/session:plan-list`, `/session:save-plan`
+- ❌ Wrong: `/plan-execute`, `/plan-status`, `/plan-show`, `/plan-list`, `/save-plan`
+Use ONLY the exact command formats specified in this template.
+
+## Arguments
+
+Parsed from user input:
+- `plan_name`: {name} (required)
+
+ARGUMENTS: {name}
+
+## Workflow
+
+### Step 1: Check for Active Session (Optional)
+
+Plans are now global and don't require a session. However, if there's an active session, we can extract requirements from the conversation.
+
+Check for active session:
+
+```bash
+[ -f .claude/sessions/.active-session ] && cat .claude/sessions/.active-session || echo "none"
+```
+
+- If result is "none": Skip Steps 2-3, create an empty plan with placeholder requirements (go to Step 4)
+- If there's an active session: Continue to Step 2 to extract from conversation
+
+### Step 2: Read Conversation Log (If Session Active)
+
+**Only execute this step if there's an active session.**
+
+Load the conversation log for the active session. The conversation log file is at:
+`.claude/sessions/{session_name}/conversation-log.jsonl`
+
+**Chunked Reading Strategy:**
+1. Check if file exists
+2. Count lines: `wc -l .claude/sessions/{session_name}/conversation-log.jsonl`
+3. If <= 2000 lines: Read entire file
+4. If > 2000 lines: Read in chunks of 2000 using Read tool's offset/limit parameters
+5. Concatenate all chunks into full conversation log
+
+If the file doesn't exist or is empty:
+- Show warning: "⚠️ No conversation log found. Creating empty plan template."
+- Continue to Step 4 with empty requirements
+
+### Step 3: Detect Work Type (Optional - If Session Active)
+
+Detect the work type from the conversation for metadata purposes:
+
+```bash
+node ${CLAUDE_PLUGIN_ROOT}/cli/session-cli.js detect-work-type {session_name}
+```
+
+This returns a JSON object with:
+```json
+{
+  "type": "feature|bug|spike|refactor|unknown",
+  "confidence": 87,
+  "scores": {...},
+  "signals": {...}
+}
+```
+
+Show the detection result:
+```
+🔍 Analyzing conversation...
+✓ Detected work type: {TYPE} ({confidence}% confidence)
+```
+
+This is for metadata only - conceptual plans don't use templates.
+
+### Step 4: Extract Requirements from Conversation
+
+Use a subagent to analyze the conversation and extract requirements (not tasks!).
+
+Invoke the Task tool with:
+- subagent_type: "general-purpose"
+- model: "haiku"
+- prompt: Read the file at `${CLAUDE_PLUGIN_ROOT}/prompts/analyze-conversation.md`, replace placeholders with actual values, then execute those instructions
+
+The subagent will return extracted requirements:
+```json
+{
+  "goal": "High-level objective",
+  "requirements": [
+    {
+      "id": "req-1",
+      "description": "What the user wants (high-level)",
+      "notes": "Additional context",
+      "open_questions": ["Question 1", "Question 2"],
+      "priority": "high|medium|low",
+      "conversation_context": "Relevant conversation excerpts"
+    }
+  ],
+  "discussion_notes": "Free-form notes from planning discussion",
+  "conversation_summary": "Summary of conversation"
+}
+```
+
+**IMPORTANT:** Extract REQUIREMENTS (what user wants), NOT tasks (how to implement).
+- ✓ Good requirement: "Restrict products based on user permissions"
+- ✗ Bad (too detailed): "Add restriction_level column to public.new_product table"
+
+Requirements are exploratory and high-level during planning.
+
+### Step 4: Build Requirements Plan
+
+Create the requirements.json structure:
+
+```json
+{
+  "plan_name": "{plan_name}",
+  "plan_type": "conceptual",
+  "goal": "{extracted_goal_or_placeholder}",
+  "requirements": [...extracted_requirements_or_empty],
+  "discussion_notes": "{discussion_notes_or_empty}",
+  "conversation_summary": "{conversation_summary_or_empty}",
+  "created_at": "{ISO_8601_timestamp}",
+  "metadata": {
+    "work_type": "{detected_work_type_or_unknown}",
+    "estimated_complexity": "simple|moderate|complex",
+    "source_session": "{session_name_if_available_else_null}"
+  }
+}
+```
+
+**Note:** The `session_name` field is no longer required. Plans are global and can be created with or without session context.
+
+### Step 6: Show Requirements Preview
+
+Display a preview of the requirements to the user:
+
+```
+📋 Requirements Preview: {plan_name}
+
+Goal: {goal}
+Work Type: {type} ({confidence}% confidence)
+
+Requirements Captured:
+  1. {req-1-description}
+     Notes: {req-1-notes}
+     Open Questions: {req-1-questions}
+
+  2. {req-2-description}
+     Notes: {req-2-notes}
+
+  [Show first 3-4 requirements, summarize rest if more]
+
+💡 This is a conceptual plan. Use /session:plan-finalize to transform requirements into executable tasks.
+
+Options:
+  1. ✓ Save this plan (recommended)
+  2. Cancel
+```
+
+### Step 7: Get User Choice
+
+Use the AskUserQuestion tool to get the user's choice.
+
+Handle the response:
+- **Option 1 (Save)**: Continue to Step 8
+- **Option 2 (Cancel)**: Show "Plan creation cancelled" and STOP
+
+### Step 8: Validate Requirements
+
+Validate the requirements against requirements-schema.json:
+
+```bash
+node ${CLAUDE_PLUGIN_ROOT}/cli/session-cli.js validate-requirements '{requirements_json}'
+```
+
+If validation fails, show the errors and STOP:
+```
+❌ Validation errors found:
+  1. {error_1}
+  2. {error_2}
+
+Cannot save invalid plan. Please review.
+```
+
+If validation succeeds, continue.
+
+### Step 9: Save Requirements File
+
+Create the requirements.json file using the global plans directory:
+
+```bash
+node ${CLAUDE_PLUGIN_ROOT}/cli/session-cli.js save-requirements {plan_name} '{requirements_json}'
+```
+
+This creates:
+- `.claude/plans/{plan_name}/requirements.json`
+
+Also create a conversation context markdown file for reference (if conversation was analyzed):
+- Path: `.claude/plans/{plan_name}/conversation-context.md`
+- Content: Include conversation summary, key decisions, requirements discussion, etc.
+- If no session context, skip this file or create with placeholder noting manual plan creation
+
+### Step 10: Display Success
+
+Show success message with next steps:
+
+```
+✓ Global plan saved: {plan_name}
+
+📋 Plan Details:
+   • Type: Conceptual (requirements captured)
+   • Work type: {type} (detected with {confidence}% confidence)
+   • Requirements: {requirement_count}
+   • Location: .claude/plans/{plan_name}/requirements.json
+   • Scope: Global (accessible from any session)
+
+📝 Next Steps:
+
+   1. Review requirements:
+      /session:plan-status {plan_name}
+
+   2. List all plans:
+      /session:plan-list
+
+   3. Transform into executable plan:
+      /session:plan-finalize {plan_name}
+
+      This will use AI to break down requirements into concrete tasks
+      organized by implementation phases (Database, API, UI, etc.)
+
+   4. After finalization, execute:
+      /session:plan-execute {plan_name}
+
+💡 Plans are now global and accessible from any session. No need to be in a specific session to work with plans.
+```
+
+---
+
+## Error Handling
+
+At each step, handle errors gracefully:
+
+- **File not found**: Show clear message with suggestion on how to proceed
+- **Validation failed**: Show specific validation errors
+- **Detection low confidence**: Accept it (work type is just metadata)
+- **Parse errors**: Show error details and abort
+- **CLI command failures**: Check exit codes and show appropriate error messages
+
+Always provide actionable next steps when errors occur.
+
+---
+
+## Key Principles
+
+**Planning Phase = Requirements Capture**
+
+- Users discuss WHAT they want (requirements), not HOW to implement (tasks)
+- Keep it lightweight and exploratory
+- Allow for open questions and uncertainty
+- No forced structure - just capture what was discussed
+
+**Examples of Good Requirements:**
+- "Restrict products based on user permissions"
+- "Track who created each product"
+- "Add audit logging for product changes"
+- "Improve product search performance"
+
+**Examples of Bad (Too Detailed for Planning):**
+- "Add restriction_level column to public.new_product table" ← This is a task!
+- "Create POST /api/products validation" ← This is a task!
+- "Add checkbox in product form component" ← This is a task!
+
+The transformation from requirements → tasks happens in /session:plan-finalize.
+
+---
+
+## Notes
+
+- The ${CLAUDE_PLUGIN_ROOT} environment variable should point to the session plugin source directory
+- Plans are now global - stored in `.claude/plans/` regardless of active session
+- The {session_name} variable is optional - used only if there's an active session for conversation context
+- All CLI commands should use absolute paths
+- Error messages should be user-friendly and actionable
+- The workflow is designed to be interruptible - user can cancel at any point
+- Conceptual plans use requirements.json format (not orchestration.json)
+- Plans can be created with or without session context (conversation analysis is optional)