Initial commit

2025-11-30 08:53:07 +08:00
commit b5ab310674
19 changed files with 5687 additions and 0 deletions
--- a/commands/implement.md
+++ b/commands/implement.md
@@ -0,0 +1,260 @@
+---
+description: "Executes the implementation plan from a specification"
+argument-hint: "spec ID to implement (e.g., S001, R002, or full name like S001-user-auth)"
+allowed-tools: ["Task", "TodoWrite", "Bash", "Write", "Edit", "Read", "LS", "Glob", "Grep", "MultiEdit"]
+---
+
+You are an intelligent implementation orchestrator that executes the plan for: **$ARGUMENTS**
+
+## 📚 Core Rules
+
+- **You are an orchestrator** - Delegate tasks to specialist agents based on PLAN.md
+- **Work through steps sequentially** - Complete each step before moving to next
+- **Real-time tracking** - Use TodoWrite for every task status change
+- **Display ALL agent responses** - Show every agent response verbatim
+- **Validate at checkpoints** - Run validation commands when specified
+
+### 🔄 Process Rules
+
+- This command has stop points where you MUST wait for user confirmation.
+- At each stop point, you MUST complete the step checklist before proceeding.
+
+### 🤝 Agent Delegation
+
+Break down implementation tasks by activities. Use structured prompts with FOCUS/EXCLUDE boundaries for parallel or sequential execution.
+
+### 📝 TodoWrite Tool Rules
+
+**PLAN Phase Loading Protocol:**
+- NEVER load all tasks from PLAN.md at once - this causes cognitive overload
+- Load one phase at a time into TodoWrite
+- Clear or archive completed phase tasks before loading next
+- Maintain phase progress separately from individual task progress
+
+**Why PLAN Phase-by-Phase:**
+- Prevents LLM context overload with too many tasks
+- Maintains focus on current work
+- Creates natural pause points for user feedback
+- Enables user to stop or redirect between phases
+
+## 🎯 Process
+
+### 📋 Step 1: Initialize and Analyze Plan
+
+**🎯 Goal**: Validate specification exists, analyze the implementation plan, and prepare for execution.
+
+Check if $ARGUMENTS contains a specification ID in the format "010" or "010-feature-name". Run `~/.claude/plugins/marketplaces/the-startup/plugins/start/scripts/spec.py [ID] --read` to check for existing specification.
+
+Parse the TOML output which contains:
+- Specification metadata: `id`, `name`, `dir`
+- `[spec]` section: Lists spec documents (prd, sdd, plan)
+- `[gates]` section: Lists quality gates (definition_of_ready, definition_of_done, task_definition_of_done) if they exist
+
+If the specification doesn't exist (error in output):
+- Display "❌ Specification not found: [ID]"
+- Suggest: "Run /start:specify with your feature description to create the specification first."
+- Exit gracefully
+
+If the specification exists, display "📁 Found existing spec: [directory]" and list available documents from the `[spec]` section. Verify `plan` exists in the `[spec]` section. If not, display error: "❌ No PLAN.md found. Run /start:specify first to create the implementation plan." and exit.
+
+**Quality Gates**: If the `[gates]` section exists with `task_definition_of_done`, note it for task validation. If gates don't exist, proceed without validation.
+
+If PLAN.md exists, display `📊 Analyzing Implementation Plan` and read the plan to identify all phases (look for **Phase X:** patterns). Count total phases and tasks per phase. If any tasks are already marked `[x]` or `[~]`, report their status. Load ONLY Phase 1 tasks into TodoWrite.
+
+Display comprehensive implementation overview:
+```
+📁 Specification: [directory]
+📊 Implementation Overview:
+
+Specification Type: [Standard/Refactoring/Custom]
+Found X phases with Y total tasks:
+- Phase 1: [Name] (N tasks, X completed)
+- Phase 2: [Name] (N tasks, X completed)
+...
+
+Ready to start Phase 1 implementation? (yes/no)
+```
+
+**🤔 Ask yourself before proceeding:**
+1. Have I used the spec script to verify the specification exists?
+2. Does the specification directory contain a PLAN.md file?
+3. Have I successfully loaded and parsed the PLAN.md file?
+4. Did I identify ALL phases and count the tasks in each one?
+5. Are Phase 1 tasks (and ONLY Phase 1) now loaded into TodoWrite?
+6. Have I presented a complete overview to the user?
+7. Am I about to wait for explicit user confirmation?
+
+Present the implementation overview and ask: "Ready to start Phase 1 implementation?" and wait for user confirmation before proceeding.
+
+### 📋 Step 2: Phase-by-Phase Implementation
+
+For each phase in PLAN.md:
+
+#### 🚀 Phase Start
+- Clear previous phase tasks from TodoWrite (if any)
+- Load current phase tasks into TodoWrite
+- Display: "📍 Starting Phase [X]: [Phase Name]"
+- Show task count and overview for this phase
+
+**📋 Pre-Implementation Review:**
+- Check for "Pre-implementation review" task in phase
+- If present, ensure SDD sections are understood
+- Extract "Required reading" from phase comments
+- Display: "⚠️ Specification Review Required: SDD Sections [X.Y, A.B, C.D]"
+- Confirm understanding of architecture decisions and constraints
+
+#### ⚙️ Phase Execution
+
+**🔍 Task Analysis:**
+- Extract task metadata: `[activity: areas]`, `[complexity: level]`
+- Identify tasks marked with `[parallel: true]` on the same indentation level for concurrent execution
+- Group sequential vs parallel tasks
+
+**⚡ For Parallel Tasks (within same phase):**
+- Mark all parallel tasks as `in_progress` in TodoWrite
+- Launch multiple agents in single response (multiple Task tool invocations)
+- Pass appropriate context to each:
+  ```
+  FOCUS: [Specific task from PLAN.md]
+  EXCLUDE: [Other tasks, future phases]
+  CONTEXT: [Relevant BRD/PRD/SDD excerpts + prior phase outputs]
+  SDD_REQUIREMENTS: [Exact SDD sections and line numbers for this task]
+  SPECIFICATION_CONSTRAINTS: [Must match interfaces, patterns, decisions]
+  SUCCESS: [Task completion criteria + specification compliance]
+  ```
+- Track completion independently
+
+**📝 For Sequential Tasks:**
+- Execute one at a time
+- Mark as `in_progress` in TodoWrite
+- Extract SDD references from task: `[ref: SDD/Section X.Y]`
+- Delegate to specialist agent with specification context:
+  ```
+  FOCUS: [Task description]
+  SDD_SECTION: [Relevant SDD section content]
+  MUST_IMPLEMENT: [Specific interfaces, patterns from SDD]
+  SPECIFICATION_CHECK: Ensure implementation matches SDD exactly
+  ```
+- After completion, mark `completed` in TodoWrite
+
+**🔍 Review Handling:**
+- After implementation, select specialist reviewer agent
+- Pass implementation context AND specification requirements:
+  ```
+  REVIEW_FOCUS: [Implementation to review]
+  SDD_COMPLIANCE: Check against SDD Section [X.Y]
+  VERIFY:
+    - Interface contracts match specification
+    - Business logic follows defined flows
+    - Architecture decisions are respected
+    - No unauthorized deviations
+  ```
+- Handle feedback:
+  - APPROVED/LGTM/✅ → proceed
+  - Specification violation → must fix before proceeding
+  - Revision needed → implement changes (max 3 cycles)
+  - After 3 cycles → escalate to user
+
+**✓ Validation Handling:**
+- Run validation commands
+- Only proceed if validation passes
+- If fails → attempt fix → re-validate
+
+#### Phase Completion Protocol
+
+**🤔 Ask yourself before marking phase complete:**
+1. Are ALL TodoWrite tasks for this phase showing 'completed' status?
+2. Have I updated every single checkbox in PLAN.md for this phase?
+3. Did I run all validation commands and did they pass?
+4. **Have I verified specification compliance for every task?**
+5. **Did I complete the Post-Implementation Specification Compliance checks?**
+6. **Are there any deviations from the SDD that need documentation?**
+7. Have I generated a comprehensive phase summary?
+8. Am I prepared to present the summary and wait for user confirmation?
+
+**📋 Specification Compliance Summary:**
+Before presenting phase completion, verify:
+- All SDD requirements from this phase are implemented
+- No unauthorized deviations occurred
+- Interface contracts are satisfied
+- Architecture decisions were followed
+
+Present phase summary and ask: "Phase [X] is complete. Should I proceed to Phase [X+1]?" and wait for user confirmation before proceeding.
+
+Phase Summary Format:
+```
+✅ Phase [X] Complete: [Phase Name]
+- Tasks completed: X/X
+- Reviews passed: X
+- Validations: ✓ Passed
+- Key outputs: [Brief list]
+
+Should I proceed to Phase [X+1]?
+```
+
+### 📋 Step 3: Overall Completion
+
+**✅ When All Phases Complete:**
+```
+🎉 Implementation Complete!
+
+Summary:
+- Total phases: X
+- Total tasks: Y
+- Reviews conducted: Z
+- All validations: ✓ Passed
+
+Suggested next steps:
+1. Run full test suite
+2. Deploy to staging
+3. Create PR for review
+```
+
+**❌ If Blocked at Any Point:**
+```
+⚠️ Implementation Blocked
+
+Phase: [X]
+Task: [Description]
+Reason: [Specific blocker]
+
+Options:
+1. Retry with modifications
+2. Skip task and continue
+3. Abort implementation
+4. Get manual assistance
+
+Awaiting your decision...
+```
+
+## 📊 Task Management Details
+
+**🔗 Context Accumulation:**
+- Phase 1 context = BRD/PRD/SDD excerpts
+- Phase 2 context = Phase 1 outputs + relevant specs
+- Phase N context = Accumulated outputs + relevant specs
+- Pass only relevant context to avoid overload
+
+**📊 Progress Tracking Display:**
+```
+📊 Overall Progress:
+Phase 1: ✅ Complete (5/5 tasks)
+Phase 2: 🔄 In Progress (3/7 tasks)
+Phase 3: ⏳ Pending
+Phase 4: ⏳ Pending
+```
+
+**📝 PLAN.md Update Strategy**
+- Update PLAN.md checkboxes at phase completion
+- All checkboxes in a phase get updated together
+
+## 📌 Important Notes
+
+- **Phase boundaries are stops** - Always wait for user confirmation
+- **Respect parallel execution hints** - Launch concurrent tasks or agents when marked
+- **Accumulate context wisely** - Pass relevant prior outputs to later phases
+- **Track in TodoWrite** - Real-time task tracking during execution
+
+**💡 Remember:**
+- You orchestrate the workflow by executing PLAN.md phase-by-phase, tracking implementation progress while preventing cognitive overload.
+- Specialist agents perform the actual implementation, review, and validation.