aiblueprint-cli 1.4.88 → 1.4.89

package/agents-config/skills/apex/steps/step-03-execute.md

@@ -0,0 +1,240 @@
+---
+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
+- **If context was cleared ("Execute and clear context"):** The plan file contains all APEX state variables in the "APEX Workflow Context" section. Read the plan file first and restore all variables before proceeding.
+
+## 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/agents-config/skills/apex/steps/step-04-validate.md

@@ -0,0 +1,272 @@
+---
+name: step-04-validate
+description: Self-check - run tests, verify AC, audit implementation quality
+prev_step: steps/step-03-execute.md
+next_step: steps/step-05-examine.md
+---
+
+# 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 (or step-03-execute-teams) is complete
+- Tests may or may not pass yet
+- Type errors may exist
+- Focus is on verification, not new implementation
+- **If `{teams_mode}` = true:** The agent team is still alive. Do NOT shutdown or dismiss teammates. Team shutdown happens in step-09-finish only.
+
+## 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 |
+| `{test_mode}` | Include test steps |
+| `{examine_mode}` | Auto-proceed to review |
+| `{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. Determine Next Step
+
+**Decision tree:**
+
+```
+IF {test_mode} = true:
+    → Load step-07-tests.md (test analysis and creation)
+
+ELSE IF {examine_mode} = true:
+    → Load step-05-examine.md (adversarial review)
+
+ELSE IF {verify_mode} = true:
+    → Load step-10-verify.md (feature verification)
+
+ELSE IF {auto_mode} = false:
+    → Ask user:
+```
+
+```yaml
+questions:
+  - header: "Next"
+    question: "Validation complete. What would you like to do?"
+    options:
+      - label: "Run adversarial review"
+        description: "Deep review for security, logic, and quality"
+      - label: "Verify feature"
+        description: "Launch app and test feature works"
+      - label: "Complete workflow"
+        description: "Skip review and finalize"
+      - label: "Add tests"
+        description: "Create additional tests first"
+    multiSelect: false
+```
+
+```
+ELSE:
+    → Complete workflow (show final summary)
+```
+
+### 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:** ✓
+**Next:** {next step based on flags}
+**Timestamp:** {ISO timestamp}
+```
+
+---
+
+## SUCCESS METRICS:
+
+✅ Typecheck passes
+✅ Lint passes
+✅ All tests pass
+✅ All AC verified
+✅ Code formatted
+✅ User informed of status
+
+## 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
+❌ **CRITICAL**: Not using AskUserQuestion for next step
+
+## VALIDATION PROTOCOLS:
+
+- Run EVERY validation command
+- Fix failures IMMEDIATELY
+- Don't proceed until all green
+- Verify EACH acceptance criterion
+- Document all results
+
+---
+
+## NEXT STEP:
+
+Based on flags (check in order):
+- **If test_mode:** Load `./step-07-tests.md`
+- **If examine_mode OR user requests:** Load `./step-05-examine.md`
+- **If verify_mode:** Load `./step-10-verify.md` to verify feature
+- **If pr_mode:** Load `./step-09-finish.md` to create pull request
+- **Otherwise:** Workflow complete - show summary
+
+<critical>
+Remember: NEVER proceed with failing checks - fix everything first!
+If teams_mode is active: NEVER shutdown teammates - they stay alive until step-09-finish!
+</critical>