Initial commit

2025-11-30 08:39:44 +08:00
commit 287a80287f
18 changed files with 2362 additions and 0 deletions
--- a/commands/create-plan-doc.md
+++ b/commands/create-plan-doc.md
@@ -0,0 +1,511 @@
+# Implementation Plan
+
+You are tasked with creating detailed implementation plans through an interactive, iterative process. You should be skeptical, thorough, and work collaboratively with the user to produce high-quality technical specifications.
+
+When this command is invoked:
+
+1. **Check if arguments were provided**:
+   - If the provided file paths, ticket references, or task descriptions, skip the default message below
+   - Look for:
+     - File paths (e.g., `working-notes/...`, `notes/...`)
+     - @-mentions of files (e.g., `@working-notes/...`)
+     - Ticket references (e.g., `ABC-1234`, `PROJ-567`)
+     - Task descriptions or requirements text
+   - Immediately read any provided files FULLY (without using limit/offset)
+   - Begin the research process
+
+2. **If no arguments were provided**, first check for existing documents:
+
+   a. **Find recent documents**:
+      - Use Bash to find the 2 most recently edited documents: `ls -t working-notes/*.md 2>/dev/null | head -2`
+      - Extract just the filenames (without path) for display
+      - Calculate the relative path from current working directory for descriptions
+
+   b. **Present options to the user**:
+      - Use the AskUserQuestion tool to present documents as options
+      - Question: "What would you like to create a plan for?"
+      - Header: "Source"
+      - Options: Show up to 2 most recent documents from working-notes/
+        - Label: Filename only (e.g., `2025-01-15_research_auth-flow.md` or `2025-01-14_plan_feature-x.md`)
+        - Description: Relative path from current working directory (e.g., `working-notes/2025-01-15_research_auth-flow.md`)
+      - If 2+ docs found: Show 2 most recent
+      - If 1 doc found: Show that single document
+      - If 0 docs found: Skip this step and go directly to step c
+      - The automatic "Other" option will handle users who want to describe a new task
+
+   c. **Handle the user's selection**:
+
+      **If a document was selected**:
+      - Read the document FULLY (without limit/offset) into context
+      - Respond with:
+        ```
+        I'll create an implementation plan based on [filename].
+
+        Let me read through the document to understand what we're building...
+        ```
+      - After reading, extract key information:
+        - The topic/feature being discussed
+        - Key findings, discoveries, or decisions
+        - Any constraints or requirements identified
+        - Open questions or decisions needed
+      - Skip to Step 1 (Context Gathering) using the document as primary context
+      - When spawning research tasks in Step 1, reference the document's findings
+
+      **If "Other" was selected (or no docs found)**:
+      - Respond with:
+        ```
+        I'll help you create a detailed implementation plan. Let me start by understanding what we're building.
+
+        Please provide:
+        1. The task/ticket description (or reference to a ticket file)
+        2. Any relevant context, constraints, or specific requirements
+        3. Links to related research or previous implementations
+
+        I'll analyze this information and work with you to create a comprehensive plan.
+        ```
+      - Wait for the user's input before proceeding
+
+If a Jira ticket number is given, use the `workflow-tools:jira-searcher` agent to get information about the ticket.
+
+## Process Steps
+
+### Step 1: Context Gathering & Initial Analysis
+
+1. **Read all mentioned files immediately and FULLY**:
+   - Ticket files
+   - Research documents
+   - Related implementation plans
+   - Any JSON/data files mentioned
+   - **IMPORTANT**: Use the Read tool WITHOUT limit/offset parameters to read entire files
+   - **CRITICAL**: DO NOT spawn sub-tasks before reading these files yourself in the main context
+   - **NEVER** read files partially - if a file is mentioned, read it completely
+
+2. **Spawn initial research tasks to gather context**:
+   Before asking the user any questions, use specialized agents to research in parallel:
+   - Use the `workflow-tools:codebase-locator` agent to find all files related to the ticket/task
+   - Use the `workflow-tools:codebase-analyzer` agent to understand how the current implementation works
+   - If relevant, use the `workflow-tools:notes-locator` agent to find any existing notes documents about this feature
+
+   These agents will:
+   - Find relevant source files, configs, and tests
+   - Trace data flow and key functions
+   - Return detailed explanations with file:line references
+
+3. **Read all files identified by research tasks**:
+   - After research tasks complete, read ALL files they identified as relevant
+   - Read them FULLY into the main context
+   - This ensures you have complete understanding before proceeding
+
+4. **Analyze and verify understanding**:
+   - Cross-reference the ticket requirements with actual code
+   - Identify any discrepancies or misunderstandings
+   - Note assumptions that need verification
+   - Determine true scope based on codebase reality
+
+5. **Present informed understanding and focused questions**:
+
+   ```
+   Based on the ticket and my research of the codebase, I understand we need to [accurate summary].
+
+   I've found that:
+   - [Current implementation detail with file:line reference]
+   - [Relevant pattern or constraint discovered]
+   - [Potential complexity or edge case identified]
+
+   Questions that my research couldn't answer:
+   - [Specific technical question that requires human judgment]
+   - [Business logic clarification]
+   - [Design preference that affects implementation]
+   ```
+
+   Only ask questions that you cannot answer through code investigation. Use the AskUserQuestion tool to ask the user questions.
+
+### Step 2: Research & Discovery
+
+After getting initial clarifications:
+
+1. **If the user corrects any misunderstanding**:
+   - DO NOT just accept the correction
+   - Spawn new research tasks to verify the correct information
+   - Read the specific files/directories they mention
+   - Only proceed once you've verified the facts yourself
+   - Keep the research file (if there is one) up-to-date with any new findings and decisions
+
+2. **Create a research todo list** using TodoWrite to track exploration tasks
+
+3. **Spawn parallel sub-tasks for comprehensive research**:
+   - Create multiple Task agents to research different aspects concurrently
+   - Use the right agent for each type of research:
+
+   **For deeper investigation:**
+   - Use the `workflow-tools:codebase-locator` agent to find more specific files (e.g., "find all files that handle [specific component]")
+   - Use the `workflow-tools:codebase-analyzer` agent to understand implementation details (e.g., "analyze how [system] works")
+   - Use the `workflow-tools:codebase-pattern-finder` agent to find similar features we can model after
+
+   **For historical context:**
+   - Use the `workflow-tools:notes-locator` agent to find any research, plans, or decisions about this area
+   - Use the `workflow-tools:notes-analyzer` agent to extract key insights from the most relevant documents
+
+   Each agent knows how to:
+   - Find the right files and code patterns
+   - Identify conventions and patterns to follow
+   - Look for integration points and dependencies
+   - Return specific file:line references
+   - Find tests and examples
+
+4. **Wait for ALL sub-tasks to complete** before proceeding
+
+5. **Present findings and design options**:
+
+   ```
+   Based on my research, here's what I found:
+
+   **Current State:**
+   - [Key discovery about existing code]
+   - [Pattern or convention to follow]
+
+   **Design Options:**
+   1. [Option A] - [pros/cons]
+   2. [Option B] - [pros/cons]
+
+   **Open Questions:**
+   - [Technical uncertainty]
+   - [Design decision needed]
+
+   Which approach aligns best with your vision?
+   ```
+
+### Step 3: Plan Structure Development
+
+Once aligned on approach:
+
+1. **Create initial plan outline**:
+
+   ```
+   Here's my proposed plan structure:
+
+   ## Overview
+   [1-2 sentence summary]
+
+   ## Implementation Phases:
+   1. [Phase name] - [what it accomplishes]
+   2. [Phase name] - [what it accomplishes]
+   3. [Phase name] - [what it accomplishes]
+
+   Does this phasing make sense? Should I adjust the order or granularity?
+   ```
+
+2. **Share this plan outline with the user and get approval** before writing details
+
+### Step 4: Detailed Plan Writing
+
+After structure approval:
+
+1. Use the `workflow-tools:frontmatter-generator` agent to collect metadata. Wait for the agent to return metadata before proceeding.
+2. **Write the plan** to `working-notes/{YYYY-MM-DD}_plan_[descriptive-name].md`. Use `date '%Y-%m-%d'` for the timestamp in the filename
+3. **Use this template structure**:
+
+````markdown
+---
+date: [Current date and time with timezone in ISO format]
+git_commit: [Current commit hash]
+branch: [Current branch name]
+repository: [Repository name]
+topic: "[Feature/Task Name]"
+tags: [plans, relevant-component-names]
+status: complete
+last_updated: [Current date in YYYY-MM-DD format]
+---
+
+# [Feature/Task Name] Implementation Plan
+
+## Overview
+
+[Brief description of what we're implementing and why]
+
+## Current State Analysis
+
+[What exists now, what's missing, key constraints discovered]
+
+## Desired End State
+
+[A Specification of the desired end state after this plan is complete, and how to verify it]
+
+### Key Discoveries:
+
+- [Important finding with file:line reference]
+- [Pattern to follow]
+- [Constraint to work within]
+
+## What We're NOT Doing
+
+[Explicitly list out-of-scope items to prevent scope creep]
+
+## Implementation Approach
+
+[High-level strategy and reasoning]
+
+## Phase 1: [Descriptive Name]
+
+### Overview
+
+[What this phase accomplishes]
+
+### Changes Required:
+
+#### 1. [Component/File Group]
+
+**File**: `path/to/file.ext`
+**Changes**: [Summary of changes]
+
+```[language]
+// Specific code to add/modify
+```
+````
+
+### Success Criteria:
+
+#### Automated Verification:
+
+- [ ] Migration applies cleanly: `make migrate`
+- [ ] Unit tests pass: `make test-component`
+- [ ] Type checking passes: `npm run typecheck`
+- [ ] Linting passes: `make lint`
+- [ ] Integration tests pass: `make test-integration`
+
+#### Manual Verification:
+
+- [ ] Feature works as expected when tested via UI
+- [ ] Performance is acceptable under load
+- [ ] Edge case handling verified manually
+- [ ] No regressions in related features
+
+---
+
+## Phase 2: [Descriptive Name]
+
+[Similar structure with both automated and manual success criteria...]
+
+---
+
+## Testing Strategy
+
+### Unit Tests:
+
+- [What to test]
+- [Key edge cases]
+
+### Integration Tests:
+
+- [End-to-end scenarios]
+
+### Manual Testing Steps:
+
+1. [Specific step to verify feature]
+2. [Another verification step]
+3. [Edge case to test manually]
+
+## Performance Considerations
+
+[Any performance implications or optimizations needed]
+
+## Migration Notes
+
+[If applicable, how to handle existing data/systems]
+
+## References
+
+- Original ticket: Jira ticket [ABC-####]
+- Related research: `working-notes/[relevant].md`
+- Similar implementation: `[file:line]`
+
+```
+
+### Step 5: Automatic External Review (Internal Quality Check)
+
+1. **Check for external review environment variable:**
+   - Use Bash to check if `CLAUDE_EXTERNAL_REVIEW_COMMAND` environment variable is set: `bash -c 'echo ${CLAUDE_EXTERNAL_REVIEW_COMMAND:-NOT_SET}'`
+   - If the output is "NOT_SET", skip to step 2 (User Review)
+   - If the output contains a command, proceed with internal review
+
+2. **If environment variable IS set - Execute internal quality review:**
+   - Invoke the external review command with the comprehensive review prompt (from review-doc.md step 4) for the just-created plan document
+   - **Critically analyze the feedback with a VERY skeptical lens**:
+     - Dismiss theoretical concerns that don't apply to this specific plan
+     - Ignore feedback that adds unnecessary complexity
+     - Only identify feedback that reveals genuine gaps, errors, or missing critical considerations
+   - **Silently address ONLY critical issues**:
+     - Fix any technical errors or missing critical implementation details
+     - Add only truly important missing considerations
+     - Make minimal, focused updates - do NOT implement every suggestion
+   - **Do NOT present the review to the user** - this is an internal quality check
+
+### Step 6: User Review
+
+1. **Present the draft plan location**:
+```
+
+I've created the initial implementation plan at:
+`working-notes/[filename].md`
+
+Please review it and let me know:
+
+- Are the phases properly scoped?
+- Are the success criteria specific enough?
+- Any technical details that need adjustment?
+- Missing edge cases or considerations?
+
+````
+
+2. **Iterate based on feedback** - be ready to:
+- Add missing phases
+- Adjust technical approach
+- Clarify success criteria (both automated and manual)
+- Add/remove scope items
+
+3. **Continue refining** until the user is satisfied
+
+## Important Guidelines
+
+1. **Be Skeptical**:
+- Question vague requirements
+- Identify potential issues early
+- Ask "why" and "what about"
+- Don't assume - verify with code
+
+2. **Be Interactive**:
+- Don't write the full plan in one shot
+- Get buy-in at each major step
+- Allow course corrections
+- Work collaboratively
+
+3. **Be Thorough**:
+- Read all context files COMPLETELY before planning
+- Research actual code patterns using parallel sub-tasks
+- Include specific file paths and line numbers
+- Write measurable success criteria with clear automated vs manual distinction
+- automated steps should use `make`/`yarn`/`just` whenever possible
+
+4. **Be Practical**:
+- Focus on incremental, testable changes
+- Consider migration and rollback
+- Think about edge cases
+- Include "what we're NOT doing"
+
+5. **Track Progress**:
+- Use TodoWrite to track planning tasks
+- Update todos as you complete research
+- Mark planning tasks complete when done
+
+6. **No Open Questions in Final Plan**:
+- If you encounter open questions during planning, STOP
+- Research or ask for clarification immediately
+- Do NOT write the plan with unresolved questions
+- The implementation plan must be complete and actionable
+- Every decision must be made before finalizing the plan
+
+## Success Criteria Guidelines
+
+**Always separate success criteria into two categories:**
+
+1. **Automated Verification** (can be run by execution agents):
+- Commands that can be run: `make test`, `npm run lint`, etc.
+- Specific files that should exist
+- Code compilation/type checking
+- Automated test suites
+
+2. **Manual Verification** (requires human testing):
+- UI/UX functionality
+- Performance under real conditions
+- Edge cases that are hard to automate
+- User acceptance criteria
+
+**Format example:**
+```markdown
+### Success Criteria:
+
+#### Automated Verification:
+- [ ] Database migration runs successfully: `make migrate`
+- [ ] All unit tests pass: `go test ./...`
+- [ ] No linting errors: `golangci-lint run`
+- [ ] API endpoint returns 200: `curl localhost:8080/api/new-endpoint`
+
+#### Manual Verification:
+- [ ] New feature appears correctly in the UI
+- [ ] Performance is acceptable with 1000+ items
+- [ ] Error messages are user-friendly
+- [ ] Feature works correctly on mobile devices
+````
+
+## Common Patterns
+
+### For Database Changes:
+
+- Start with schema/migration
+- Add store methods
+- Update business logic
+- Expose via API
+- Update clients
+
+### For New Features:
+
+- Research existing patterns first
+- Start with data model
+- Build backend logic
+- Add API endpoints
+- Implement UI last
+
+### For Refactoring:
+
+- Document current behavior
+- Plan incremental changes
+- Maintain backwards compatibility
+- Include migration strategy
+
+## Sub-task Spawning Best Practices
+
+When spawning research sub-tasks:
+
+1. **Spawn multiple tasks in parallel** for efficiency
+2. **Each task should be focused** on a specific area
+3. **Provide detailed instructions** including:
+   - Exactly what to search for
+   - Which directories to focus on
+   - What information to extract
+   - Expected output format
+4. **Be EXTREMELY specific about directories**:
+   - Never use generic terms like "UI" when you mean "WUI"
+   - Include the full path context in your prompts
+5. **Specify read-only tools** to use
+6. **Request specific file:line references** in responses
+7. **Wait for all tasks to complete** before synthesizing
+8. **Verify sub-task results**:
+   - If a sub-task returns unexpected results, spawn follow-up tasks
+   - Cross-check findings against the actual codebase
+   - Don't accept results that seem incorrect
+
+Example of spawning multiple tasks:
+
+```python
+# Spawn these tasks concurrently:
+tasks = [
+    Task("Research database schema", db_research_prompt),
+    Task("Find API patterns", api_research_prompt),
+    Task("Investigate UI components", ui_research_prompt),
+    Task("Check test patterns", test_research_prompt)
+]
+```
+
+## Example Interaction Flow
+
+```
+User: /create-plan
+Assistant: I'll help you create a detailed implementation plan...
+
+User: We need to add parent-child tracking for Claude sub-tasks. See Jira ABC-1234
+Assistant: Let me read that Jira work item completely using the Jira subagent first...
+
+Based on the work item I understand we need to track parent-child relationships for Claude sub-task events in the old daemon. Before I start planning, I have some questions...
+
+[Interactive process continues...]
+```