aiblueprint-cli 1.4.23 → 1.4.25

package/claude-code-config/skills/workflow-apex/steps/step-02-plan.md

@@ -0,0 +1,264 @@
+---
+name: step-02-plan
+description: Strategic planning - create detailed file-by-file implementation strategy
+prev_step: steps/step-01-analyze.md
+next_step: steps/step-03-execute.md
+---
+
+# Step 2: Plan (Strategic Design)
+
+## MANDATORY EXECUTION RULES (READ FIRST):
+
+- 🛑 NEVER start implementing - that's step 3
+- 🛑 NEVER write or modify code in this step
+- ✅ ALWAYS structure plan by FILE, not by feature
+- ✅ ALWAYS include specific line numbers from analysis
+- ✅ ALWAYS map acceptance criteria to file changes
+- 📋 YOU ARE A PLANNER, not an implementer
+- 💬 FOCUS on "What changes need to be made where?"
+- 🚫 FORBIDDEN to use Edit, Write, or Bash tools
+
+## EXECUTION PROTOCOLS:
+
+- 🎯 ULTRA THINK before creating the plan
+- 💾 Save plan to output file (if save_mode)
+- 📖 Reference patterns from step-01 analysis
+- 🚫 FORBIDDEN to proceed until user approves plan (unless auto_mode)
+
+## CONTEXT BOUNDARIES:
+
+- Context from step-01 (files, patterns, utilities) is available
+- Implementation has NOT started
+- User has NOT approved any changes yet
+- Plan must be complete before execution
+
+## YOUR TASK:
+
+Transform analysis findings into a comprehensive, executable, file-by-file implementation plan.
+
+---
+
+<available_state>
+From previous steps:
+
+| Variable | Description |
+|----------|-------------|
+| `{task_description}` | What to implement |
+| `{task_id}` | Kebab-case identifier |
+| `{acceptance_criteria}` | Success criteria from step-01 |
+| `{auto_mode}` | Skip confirmations |
+| `{save_mode}` | Save outputs to files |
+| `{output_dir}` | Path to output (if save_mode) |
+| Files found | From step-01 codebase exploration |
+| Patterns | From step-01 pattern analysis |
+| Utilities | From step-01 utility discovery |
+</available_state>
+
+---
+
+## EXECUTION SEQUENCE:
+
+### 1. Initialize Save Output (if save_mode)
+
+**If `{save_mode}` = true:**
+
+```bash
+bash {skill_dir}/scripts/update-progress.sh "{task_id}" "02" "plan" "in_progress"
+```
+
+Append plan to `{output_dir}/02-plan.md` as you work.
+
+### 2. ULTRA THINK: Design Complete Strategy
+
+**CRITICAL: Think through ENTIRE implementation before writing any plan.**
+
+Mental simulation:
+- Walk through the implementation step by step
+- Identify all files that need changes
+- Determine logical order (dependencies first)
+- Consider edge cases and error handling
+- Plan test coverage
+
+### 3. Clarify Ambiguities
+
+**If `{auto_mode}` = true:**
+→ Use recommended option for any ambiguity, proceed automatically
+
+**If `{auto_mode}` = false AND multiple valid approaches exist:**
+
+```yaml
+questions:
+  - header: "Approach"
+    question: "Multiple approaches are possible. Which should we use?"
+    options:
+      - label: "Approach A (Recommended)"
+        description: "Description and tradeoffs of A"
+      - label: "Approach B"
+        description: "Description and tradeoffs of B"
+      - label: "Approach C"
+        description: "Description and tradeoffs of C"
+    multiSelect: false
+```
+
+### 4. Create Detailed Plan
+
+**Structure by FILE, not by feature:**
+
+```markdown
+## Implementation Plan: {task_description}
+
+### Overview
+[1-2 sentences: High-level strategy and approach]
+
+### Prerequisites
+- [ ] Prerequisite 1 (if any)
+- [ ] Prerequisite 2 (if any)
+
+---
+
+### File Changes
+
+#### `src/path/file1.ts`
+- Add `functionName` that handles X
+- Extract logic from Y (follow pattern in `example.ts:45`)
+- Handle error case: [specific scenario]
+- Consider: [edge case or important context]
+
+#### `src/path/file2.ts`
+- Update imports to include new module
+- Call `functionName` in existing flow at line ~42
+- Update types: Add `NewType` interface
+
+#### `src/path/file3.ts` (NEW FILE)
+- Create utility for Z
+- Export: `utilityFunction`, `HelperType`
+- Pattern: Follow `similar-util.ts` structure
+
+---
+
+### Testing Strategy
+
+**New tests:**
+- `src/path/file1.test.ts` - Test functionName with:
+  - Happy path
+  - Error case
+  - Edge case
+
+**Update existing:**
+- `src/path/existing.test.ts` - Add test for new flow
+
+---
+
+### Acceptance Criteria Mapping
+- [ ] AC1: Satisfied by changes in `file1.ts`
+- [ ] AC2: Satisfied by changes in `file2.ts`
+
+---
+
+### Risks & Considerations
+- Risk 1: [potential issue and mitigation]
+```
+
+**If `{save_mode}` = true:** Append full plan to 02-plan.md
+
+### 5. Verify Plan Completeness
+
+Checklist:
+- [ ] All files identified - nothing missing
+- [ ] Logical order - dependencies handled first
+- [ ] Clear actions - every step specific and actionable
+- [ ] Test coverage - all paths have test strategy
+- [ ] In scope - no scope creep
+- [ ] AC mapped - every criterion has implementation
+
+### 6. Present Plan for Approval
+
+```
+**Implementation Plan Ready**
+
+**Overview:** [1 sentence summary]
+
+**Files to modify:** {count} files
+**New files:** {count} files
+**Tests:** {count} test files
+
+**Estimated changes:**
+- `file1.ts` - Major changes (add function, handle errors)
+- `file2.ts` - Minor changes (imports, single call)
+- `file1.test.ts` - New test file
+```
+
+**If `{auto_mode}` = true:**
+→ Skip confirmation, proceed directly to execution
+
+**If `{auto_mode}` = false:**
+
+```yaml
+questions:
+  - header: "Plan"
+    question: "Review the implementation plan. Ready to proceed?"
+    options:
+      - label: "Approve and execute (Recommended)"
+        description: "Plan looks good, start implementation"
+      - label: "Adjust plan"
+        description: "I want to modify specific parts"
+      - label: "Ask questions"
+        description: "I have questions about the plan"
+      - label: "Start over"
+        description: "Revise the entire plan"
+    multiSelect: false
+```
+
+### 7. Complete Save Output (if save_mode)
+
+**If `{save_mode}` = true:**
+
+Append to `{output_dir}/02-plan.md`:
+```markdown
+---
+## Step Complete
+**Status:** ✓ Complete
+**Files planned:** {count}
+**Tests planned:** {count}
+**Next:** step-03-execute.md
+**Timestamp:** {ISO timestamp}
+```
+
+---
+
+## SUCCESS METRICS:
+
+✅ Complete file-by-file plan created
+✅ Logical dependency order established
+✅ All acceptance criteria mapped to changes
+✅ Test strategy defined
+✅ User approved plan (or auto-approved)
+✅ NO code written or modified
+✅ Output saved (if save_mode)
+
+## FAILURE MODES:
+
+❌ Organizing by feature instead of file
+❌ Vague actions like "add feature" or "fix issue"
+❌ Missing test strategy
+❌ Not mapping to acceptance criteria
+❌ Starting to write code (that's step 3!)
+❌ **CRITICAL**: Not using AskUserQuestion for approval
+
+## PLANNING PROTOCOLS:
+
+- Structure by FILE - each file is a section
+- Include line number references from analysis
+- Every action must be specific and actionable
+- Map every AC to specific file changes
+- Plan tests alongside implementation
+
+---
+
+## NEXT STEP:
+
+After user approves via AskUserQuestion (or auto-proceed), load `./step-03-execute.md`
+
+<critical>
+Remember: Planning is ONLY about designing the approach - save all implementation for step-03!
+</critical>

package/claude-code-config/skills/workflow-apex/steps/step-03-execute.md

@@ -0,0 +1,239 @@
+---
+name: step-03-execute
+description: Todo-driven implementation - execute the plan file by file
+prev_step: steps/step-02-plan.md
+next_step: steps/step-04-validate.md
+---
+
+# Step 3: Execute (Implementation)
+
+## MANDATORY EXECUTION RULES (READ FIRST):
+
+- 🛑 NEVER deviate from the approved plan
+- 🛑 NEVER add features not in the plan (scope creep)
+- 🛑 NEVER modify files without reading them first
+- ✅ ALWAYS follow the plan file-by-file
+- ✅ ALWAYS mark todos complete immediately after each task
+- ✅ ALWAYS read files BEFORE editing them
+- 📋 YOU ARE AN IMPLEMENTER following a plan, not a designer
+- 💬 FOCUS on executing the plan exactly as approved
+- 🚫 FORBIDDEN to add "improvements" not in the plan
+
+## EXECUTION PROTOCOLS:
+
+- 🎯 Create todos from plan before starting
+- 💾 Mark todos complete immediately after each task
+- 📖 Read each file BEFORE modifying it
+- 🚫 FORBIDDEN to have multiple todos in_progress simultaneously
+
+## CONTEXT BOUNDARIES:
+
+- Plan from step-02 is approved and must be followed
+- Files to modify are known from the plan
+- Patterns to follow are documented from step-01
+- Don't add features - stick to the plan
+
+## YOUR TASK:
+
+Execute the approved implementation plan file-by-file, tracking progress with todos.
+
+---
+
+<available_state>
+From previous steps:
+
+| Variable | Description |
+|----------|-------------|
+| `{task_description}` | What to implement |
+| `{task_id}` | Kebab-case identifier |
+| `{auto_mode}` | Skip confirmations |
+| `{save_mode}` | Save outputs to files |
+| `{output_dir}` | Path to output (if save_mode) |
+| Implementation plan | File-by-file changes from step-02 |
+| Patterns | How to implement from step-01 |
+</available_state>
+
+---
+
+## EXECUTION SEQUENCE:
+
+### 1. Initialize Save Output (if save_mode)
+
+**If `{save_mode}` = true:**
+
+```bash
+bash {skill_dir}/scripts/update-progress.sh "{task_id}" "03" "execute" "in_progress"
+```
+
+Append logs to `{output_dir}/03-execute.md` as you work.
+
+### 2. Create Todos from Plan
+
+Convert each file change from the plan into todos:
+
+```
+Plan entry:
+#### `src/auth/handler.ts`
+- Add `validateToken` function
+- Handle error case: expired token
+
+Becomes:
+- [ ] src/auth/handler.ts: Add validateToken function
+- [ ] src/auth/handler.ts: Handle expired token error
+```
+
+Use TodoWrite to create the full list.
+
+### 3. Execute File by File
+
+For each todo:
+
+**3.1 Mark In Progress**
+- Only ONE todo in_progress at a time
+
+**3.2 Read Before Edit**
+```
+ALWAYS read the file before modifying:
+- Understand current structure
+- Find exact insertion points
+- Verify patterns match expectations
+```
+
+**3.3 Implement Changes**
+```
+Make changes specified in the plan:
+- Follow patterns from step-01 analysis
+- Use exact names from plan
+- Handle error cases as specified
+- NO comments unless truly necessary
+```
+
+**3.4 Mark Complete Immediately**
+- Mark todo complete RIGHT AFTER finishing
+- Don't batch completions
+
+**3.5 Log Progress (if save_mode)**
+```markdown
+### ✓ src/auth/handler.ts
+- Added `validateToken` function (lines 45-78)
+- Added error handling for expired tokens
+**Timestamp:** {ISO}
+```
+
+### 4. Handle Blockers
+
+**If `{auto_mode}` = true:**
+→ Make reasonable decision and continue
+
+**If `{auto_mode}` = false:**
+
+```yaml
+questions:
+  - header: "Blocker"
+    question: "Encountered an issue. How should we proceed?"
+    options:
+      - label: "Use alternative approach (Recommended)"
+        description: "Description of alternative"
+      - label: "Skip this part"
+        description: "Continue without this change"
+      - label: "Stop for discussion"
+        description: "I want to discuss before continuing"
+    multiSelect: false
+```
+
+### 5. Verify Implementation
+
+After completing all todos:
+
+```bash
+pnpm run typecheck && pnpm run lint --fix
+```
+
+Fix any errors immediately.
+
+### 6. Implementation Summary
+
+```
+**Implementation Complete**
+
+**Files Modified:**
+- `src/auth/handler.ts` - Added validateToken, error handling
+- `src/api/auth/route.ts` - Integrated token validation
+
+**New Files:**
+- `src/types/auth.ts` - Auth type definitions
+
+**Todos:** {X}/{Y} complete
+```
+
+**If `{auto_mode}` = true:**
+→ Proceed to validation
+
+**If `{auto_mode}` = false:**
+
+```yaml
+questions:
+  - header: "Execute"
+    question: "Implementation complete. Ready to validate?"
+    options:
+      - label: "Proceed to validation (Recommended)"
+        description: "Run typecheck, lint, and tests"
+      - label: "Review changes"
+        description: "I want to review what was changed"
+      - label: "Make adjustments"
+        description: "I want to modify something"
+    multiSelect: false
+```
+
+### 7. Complete Save Output (if save_mode)
+
+**If `{save_mode}` = true:**
+
+Append to `{output_dir}/03-execute.md`:
+```markdown
+---
+## Step Complete
+**Status:** ✓ Complete
+**Files modified:** {count}
+**Todos completed:** {count}
+**Next:** step-04-validate.md
+**Timestamp:** {ISO timestamp}
+```
+
+---
+
+## SUCCESS METRICS:
+
+✅ All plan items implemented
+✅ All todos marked complete
+✅ No scope creep - only plan items
+✅ Files read before modification
+✅ Typecheck and lint pass
+✅ Progress logged (if save_mode)
+
+## FAILURE MODES:
+
+❌ Adding features not in the plan
+❌ Modifying files without reading first
+❌ Not updating todos as you work
+❌ Multiple todos in_progress simultaneously
+❌ Ignoring type or lint errors
+❌ **CRITICAL**: Not using AskUserQuestion for blockers
+
+## EXECUTION PROTOCOLS:
+
+- Follow the plan EXACTLY
+- Read before write
+- One file at a time
+- Update todos in real-time
+- Fix errors immediately
+
+---
+
+## NEXT STEP:
+
+After implementation complete, load `./step-04-validate.md`
+
+<critical>
+Remember: Execution is about following the plan - don't redesign or add features!
+</critical>