aiblueprint-cli 1.4.24 → 1.4.25

package/claude-code-config/skills/workflow-apex-free/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>

package/claude-code-config/skills/workflow-apex-free/steps/step-04-validate.md

@@ -0,0 +1,251 @@
+---
+name: step-04-validate
+description: Self-check - run tests, verify AC, audit implementation quality, complete workflow
+prev_step: steps/step-03-execute.md
+next_step: null
+---
+
+# Step 4: Validate (Self-Check)
+
+## MANDATORY EXECUTION RULES (READ FIRST):
+
+- 🛑 NEVER claim checks pass when they don't
+- 🛑 NEVER skip any validation step
+- ✅ ALWAYS run typecheck, lint, and tests
+- ✅ ALWAYS verify each acceptance criterion
+- ✅ ALWAYS fix failures before proceeding
+- 📋 YOU ARE A VALIDATOR, not an implementer
+- 💬 FOCUS on "Does it work correctly?"
+- 🚫 FORBIDDEN to proceed with failing checks
+
+## EXECUTION PROTOCOLS:
+
+- 🎯 Run all validation commands
+- 💾 Log results to output (if save_mode)
+- 📖 Check each AC against implementation
+- 🚫 FORBIDDEN to mark complete with failures
+
+## CONTEXT BOUNDARIES:
+
+- Implementation from step-03 is complete
+- Tests may or may not pass yet
+- Type errors may exist
+- Focus is on verification, not new implementation
+
+## YOUR TASK:
+
+Validate the implementation by running checks, verifying acceptance criteria, and ensuring quality.
+
+---
+
+<available_state>
+From previous steps:
+
+| Variable | Description |
+|----------|-------------|
+| `{task_description}` | What was implemented |
+| `{task_id}` | Kebab-case identifier |
+| `{acceptance_criteria}` | Success criteria |
+| `{auto_mode}` | Skip confirmations |
+| `{save_mode}` | Save outputs to files |
+| `{economy_mode}` | No subagents mode |
+| `{output_dir}` | Path to output (if save_mode) |
+| Implementation | Completed in step-03 |
+</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}" "04" "validate" "in_progress"
+```
+
+Append results to `{output_dir}/04-validate.md` as you work.
+
+### 2. Discover Available Commands
+
+Check `package.json` for exact command names:
+```bash
+cat package.json | grep -A 20 '"scripts"'
+```
+
+Look for: `typecheck`, `lint`, `test`, `build`, `format`
+
+### 3. Run Validation Suite
+
+**3.1 Typecheck**
+```bash
+pnpm run typecheck  # or npm run typecheck
+```
+
+**MUST PASS.** If fails:
+1. Read error messages
+2. Fix type issues
+3. Re-run until passing
+
+**3.2 Lint**
+```bash
+pnpm run lint
+```
+
+**MUST PASS.** If fails:
+1. Try auto-fix: `pnpm run lint --fix`
+2. Manually fix remaining
+3. Re-run until passing
+
+**3.3 Tests**
+```bash
+pnpm run test -- --filter={affected-area}
+```
+
+**MUST PASS.** If fails:
+1. Identify failing test
+2. Determine if code bug or test bug
+3. Fix the root cause
+4. Re-run until passing
+
+**If `{save_mode}` = true:** Log each result
+
+### 4. Self-Audit Checklist
+
+Verify each item:
+
+**Tasks Complete:**
+- [ ] All todos from step-03 marked complete
+- [ ] No tasks skipped without reason
+- [ ] Any blocked tasks have explanation
+
+**Tests Passing:**
+- [ ] All existing tests pass
+- [ ] New tests written for new functionality
+- [ ] No skipped tests without reason
+
+**Acceptance Criteria:**
+- [ ] Each AC demonstrably met
+- [ ] Can explain how implementation satisfies AC
+- [ ] Edge cases considered
+
+**Patterns Followed:**
+- [ ] Code follows existing patterns
+- [ ] Error handling consistent
+- [ ] Naming conventions match
+
+### 5. Format Code
+
+If format command available:
+```bash
+pnpm run format
+```
+
+### 6. Final Verification
+
+Re-run all checks:
+```bash
+pnpm run typecheck && pnpm run lint
+```
+
+Both MUST pass.
+
+### 7. Present Validation Results
+
+```
+**Validation Complete**
+
+**Typecheck:** ✓ Passed
+**Lint:** ✓ Passed
+**Tests:** ✓ {X}/{X} passing
+**Format:** ✓ Applied
+
+**Acceptance Criteria:**
+- [✓] AC1: Verified by [how]
+- [✓] AC2: Verified by [how]
+
+**Files Modified:** {list}
+
+**Summary:** All checks passing, ready for next step.
+```
+
+### 8. Complete Workflow
+
+**Show final summary:**
+
+```
+✅ APEX Workflow Complete
+
+**Task:** {task_description}
+**Task ID:** {task_id}
+
+**Validation Results:**
+- Typecheck: ✓ Passed
+- Lint: ✓ Passed
+- Tests: ✓ Passed
+
+**Acceptance Criteria:**
+- [✓] AC1: Verified
+- [✓] AC2: Verified
+
+**Files Modified:** {list}
+
+🎉 Implementation complete and validated!
+```
+
+### 9. Complete Save Output (if save_mode)
+
+**If `{save_mode}` = true:**
+
+Append to `{output_dir}/04-validate.md`:
+```markdown
+---
+## Step Complete
+**Status:** ✓ Complete
+**Typecheck:** ✓
+**Lint:** ✓
+**Tests:** ✓
+**Workflow:** Complete
+**Timestamp:** {ISO timestamp}
+```
+
+Run: `bash {skill_dir}/scripts/update-progress.sh "{task_id}" "04" "validate" "complete"`
+
+---
+
+## SUCCESS METRICS:
+
+✅ Typecheck passes
+✅ Lint passes
+✅ All tests pass
+✅ All AC verified
+✅ Code formatted
+✅ User informed of status
+✅ Workflow completed
+
+## FAILURE MODES:
+
+❌ Claiming checks pass when they don't
+❌ Not running all validation commands
+❌ Skipping tests for modified code
+❌ Missing AC verification
+❌ Proceeding with failures
+
+## VALIDATION PROTOCOLS:
+
+- Run EVERY validation command
+- Fix failures IMMEDIATELY
+- Don't proceed until all green
+- Verify EACH acceptance criterion
+- Document all results
+
+---
+
+## WORKFLOW COMPLETE
+
+This is the final step. After validation passes, the APEX workflow is complete.
+
+<critical>
+Remember: NEVER claim completion with failing checks - fix everything first!
+</critical>

package/claude-code-config/skills/workflow-apex-free/templates/00-context.md

@@ -0,0 +1,43 @@
+# APEX Task: {{task_id}}
+
+**Created:** {{timestamp}}
+**Task:** {{task_description}}
+
+---
+
+## Configuration
+
+| Flag | Value |
+|------|-------|
+| Auto mode (`-a`) | {{auto_mode}} |
+| Save mode (`-s`) | {{save_mode}} |
+| Economy mode (`-e`) | {{economy_mode}} |
+| Branch mode (`-b`) | {{branch_mode}} |
+| Interactive mode (`-i`) | {{interactive_mode}} |
+| Branch name | {{branch_name}} |
+
+---
+
+## User Request
+
+```
+{{original_input}}
+```
+
+---
+
+## Acceptance Criteria
+
+_To be defined in step-01-analyze.md_
+
+---
+
+## Progress
+
+| Step | Status | Timestamp |
+|------|--------|-----------|
+| 00-init | ⏸ Pending | |
+| 01-analyze | ⏸ Pending | |
+| 02-plan | ⏸ Pending | |
+| 03-execute | ⏸ Pending | |
+| 04-validate | ⏸ Pending | |

package/claude-code-config/skills/workflow-apex-free/templates/01-analyze.md

@@ -0,0 +1,10 @@
+# Step 01: Analyze
+
+**Task:** {{task_description}}
+**Started:** {{timestamp}}
+
+---
+
+## Context Discovery
+
+_Findings will be appended here as exploration progresses..._

package/claude-code-config/skills/workflow-apex-free/templates/02-plan.md

@@ -0,0 +1,10 @@
+# Step 02: Plan
+
+**Task:** {{task_description}}
+**Started:** {{timestamp}}
+
+---
+
+## Planning Progress
+
+_Implementation plan will be written here..._

package/claude-code-config/skills/workflow-apex-free/templates/03-execute.md

@@ -0,0 +1,10 @@
+# Step 03: Execute
+
+**Task:** {{task_description}}
+**Started:** {{timestamp}}
+
+---
+
+## Implementation Log
+
+_Changes will be logged here as implementation progresses..._

package/claude-code-config/skills/workflow-apex-free/templates/04-validate.md

@@ -0,0 +1,10 @@
+# Step 04: Validate
+
+**Task:** {{task_description}}
+**Started:** {{timestamp}}
+
+---
+
+## Validation Progress
+
+_Validation results will be appended here..._