aiblueprint-cli 1.4.22 → 1.4.24

package/claude-code-config/skills/workflow-apex/steps/step-08-run-tests.md

@@ -0,0 +1,308 @@
+---
+name: step-08-run-tests
+description: Run tests in a loop - fix issues until all pass
+prev_step: steps/step-07-tests.md
+next_step: steps/step-05-examine.md
+---
+
+# Step 8: Run Tests (Fix Loop)
+
+## MANDATORY EXECUTION RULES (READ FIRST):
+
+- 🛑 NEVER give up after first failure
+- 🛑 NEVER start services without permission (unless auto_mode)
+- 🛑 NEVER infinite loop on same failure (max 3 attempts)
+- ✅ ALWAYS loop until all tests pass
+- ✅ ALWAYS ask user when stuck (unless auto_mode)
+- ✅ ALWAYS clean up background processes
+- 📋 YOU ARE A TEST RUNNER, fixing until green
+- 💬 FOCUS on "Run → Fail → Fix → Repeat until green"
+- 🚫 FORBIDDEN to ignore configuration errors
+
+## EXECUTION PROTOCOLS:
+
+- 🎯 Check requirements before running
+- 💾 Log each test run (if save_mode)
+- 📖 Analyze failures before fixing
+- 🚫 FORBIDDEN to proceed with failing tests (without explicit skip)
+
+## CONTEXT BOUNDARIES:
+
+- Tests were created in step-07
+- Tests may require services (DB, server)
+- Failures may be code bugs or test bugs
+- Loop until all green or user decides to skip
+
+## YOUR TASK:
+
+Run tests, fix any failures, and loop until ALL tests pass.
+
+---
+
+<available_state>
+From previous steps:
+
+| Variable | Description |
+|----------|-------------|
+| `{task_description}` | What was implemented |
+| `{task_id}` | Kebab-case identifier |
+| `{auto_mode}` | Auto-start servers, auto-retry |
+| `{examine_mode}` | Auto-proceed to review after |
+| `{save_mode}` | Save outputs to files |
+| `{output_dir}` | Path to output (if save_mode) |
+| Tests created | From step-07 |
+| Test command | Discovered in step-07 |
+</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}" "08" "run-tests" "in_progress"
+```
+
+Append logs to `{output_dir}/08-run-tests.md` as you work.
+
+### 2. Check Requirements
+
+**Identify required services:**
+```bash
+cat package.json | grep -A 10 '"scripts"'
+```
+
+Common: Database, dev server, Redis
+
+**Check if running:**
+```bash
+curl -s http://localhost:3000 > /dev/null 2>&1 && echo "Server running"
+```
+
+### 3. Handle Missing Services
+
+**If `{auto_mode}` = true:**
+→ Start services automatically:
+```bash
+pnpm run dev &
+sleep 5
+```
+
+**If `{auto_mode}` = false:**
+
+```yaml
+questions:
+  - header: "Services"
+    question: "Tests require services that aren't running. How proceed?"
+    options:
+      - label: "I'll start manually"
+        description: "Give me a moment to start them"
+      - label: "Start automatically"
+        description: "Try to start services automatically"
+      - label: "Skip tests needing services"
+        description: "Only run tests that don't need services"
+      - label: "Skip test step"
+        description: "Continue without running tests"
+    multiSelect: false
+```
+
+### 4. Run Test Loop
+
+**CRITICAL: Loop until all pass**
+
+```
+max_attempts = 10
+attempt = 0
+
+WHILE attempt < max_attempts:
+    attempt += 1
+
+    1. Run tests
+    2. If all pass → EXIT (success)
+    3. If failure:
+       a. Analyze failure
+       b. Determine: code bug or test bug?
+       c. Fix the issue
+       d. CONTINUE LOOP
+    4. If same failure 3x → ASK USER
+```
+
+**Run tests:**
+```bash
+pnpm run test 2>&1
+```
+
+**Log each run:**
+```
+**Run #{attempt}:**
+- Total: 5, Passed: 3, Failed: 2
+- Fixing: {description}
+```
+
+### 5. Handle Failures
+
+For each failing test:
+
+```
+**Analyzing:**
+Test: "creates user with valid data"
+File: src/auth/register.test.ts:25
+Error: Expected 201, got 500
+Stack: TypeError: Cannot read 'email' of undefined
+
+**Diagnosis:** Code bug - null handling
+**Fix:** Add null check in handler
+```
+
+**Fix location:**
+| Error Type | Fix |
+|------------|-----|
+| Assertion failed | Usually code bug |
+| TypeError in code | Code bug |
+| TypeError in test | Test bug |
+| Timeout | async/await issue |
+| Import error | Missing dep |
+
+### 6. Handle Stuck (3x same failure)
+
+**If `{auto_mode}` = true:**
+→ Try different approach once, then continue
+
+**If `{auto_mode}` = false:**
+
+```yaml
+questions:
+  - header: "Stuck"
+    question: "Test keeps failing. How proceed?"
+    options:
+      - label: "I'll debug manually"
+        description: "Let me investigate"
+      - label: "Skip this test"
+        description: "Mark as skip, continue others"
+      - label: "Delete test"
+        description: "Remove this test entirely"
+      - label: "Keep trying"
+        description: "Try more approaches"
+    multiSelect: false
+```
+
+### 7. Handle Config Errors
+
+| Error | Solution |
+|-------|----------|
+| Cannot find module | Check imports, pnpm install |
+| Connection refused | DB/server not running |
+| Timeout | Increase timeout, check async |
+
+**If `{auto_mode}` = false:**
+
+```yaml
+questions:
+  - header: "Config"
+    question: "Configuration issue detected. How proceed?"
+    options:
+      - label: "I'll fix manually"
+        description: "Let me handle config"
+      - label: "Try automatic fix"
+        description: "Attempt suggested fix"
+      - label: "Skip tests"
+        description: "Continue without tests"
+    multiSelect: false
+```
+
+### 8. Success - All Passing
+
+```
+**✓ All Tests Passing**
+
+**Results:**
+- Total: {count}
+- Passed: {count}
+- Failed: 0
+
+**Attempts:** {count}
+
+**Tests:**
+- src/auth/register.test.ts - 3 tests
+- src/utils/validation.test.ts - 2 tests
+```
+
+### 9. Complete Save Output (if save_mode)
+
+**If `{save_mode}` = true:**
+
+Append to `{output_dir}/08-run-tests.md`:
+```markdown
+---
+## Step Complete
+**Status:** ✓ Complete
+**Tests passed:** {count}
+**Attempts:** {count}
+**Next:** {next step}
+**Timestamp:** {ISO timestamp}
+```
+
+### 10. Determine Next Step
+
+**If `{examine_mode}` = true:**
+→ Load step-05-examine.md
+
+**If `{auto_mode}` = false:**
+
+```yaml
+questions:
+  - header: "Next"
+    question: "All tests passing. What next?"
+    options:
+      - label: "Run adversarial review"
+        description: "Deep review for security/logic"
+      - label: "Complete workflow"
+        description: "Finalize and show summary"
+    multiSelect: false
+```
+
+**Else:**
+→ Complete workflow
+
+---
+
+## SUCCESS METRICS:
+
+✅ All tests passing
+✅ No stuck failures without user decision
+✅ Config issues resolved
+✅ Services cleaned up
+✅ Clear summary
+
+## FAILURE MODES:
+
+❌ Giving up after first failure
+❌ Infinite loop on same failure
+❌ Starting services without permission
+❌ Not cleaning up background processes
+❌ Ignoring config errors
+❌ **CRITICAL**: Not using AskUserQuestion when stuck
+
+## RUN PROTOCOLS:
+
+- Loop until green
+- Analyze before fixing
+- Ask user when stuck (3x)
+- Clean up services
+- Clear summary at end
+
+---
+
+## NEXT STEP:
+
+Based on flags (check in order):
+- **If examine_mode:** Load `./step-05-examine.md`
+- **If pr_mode:** Load `./step-09-finish.md` to create pull request
+- **Otherwise:** Workflow complete - show summary
+
+<critical>
+Remember: Loop until ALL tests pass - don't give up after first failure!
+</critical>

package/claude-code-config/skills/workflow-apex/steps/step-09-finish.md

@@ -0,0 +1,193 @@
+---
+name: step-09-finish
+description: Finish APEX workflow and create pull request
+previous_step: step-08-run-tests.md (or step-04-validate.md if no tests)
+---
+
+# Step 9: Finish & Create PR
+
+## MANDATORY EXECUTION RULES (READ FIRST):
+
+- 🛑 NEVER push without user confirmation (unless auto_mode)
+- 🛑 NEVER create PR if there are uncommitted changes
+- ✅ ALWAYS verify all changes are committed
+- ✅ ALWAYS push to remote before creating PR
+- 📋 YOU ARE A FINISHER, completing the workflow
+- 💬 FOCUS on PR creation and workflow summary
+- 🚫 FORBIDDEN to make code changes in this step
+
+## EXECUTION PROTOCOLS:
+
+- 🎯 Verify git status before any push/PR operations
+- 💾 Save PR details to output file if save_mode enabled
+- 📖 Provide clear workflow summary
+- 🚫 FORBIDDEN to proceed with uncommitted changes
+
+## CONTEXT BOUNDARIES:
+
+- Variables available: `{task_id}`, `{task_description}`, `{branch_name}`, `{pr_mode}`, `{auto_mode}`, `{save_mode}`, `{output_dir}`
+- Previous steps completed: analyze, plan, execute, validate (+ optional: tests, examine)
+- All implementation should be done at this point
+
+## YOUR TASK:
+
+Finalize the APEX workflow by committing remaining changes, pushing to remote, and creating a pull request.
+
+---
+
+## EXECUTION SEQUENCE:
+
+### 1. Verify Git Status
+
+```bash
+git status
+```
+
+**If uncommitted changes exist:**
+→ Commit them with message: `feat({task_id}): {task_description}`
+
+**If working tree is clean:**
+→ Continue to step 2
+
+### 2. Check Commits to Push
+
+```bash
+git log origin/{branch_name}..HEAD --oneline 2>/dev/null || git log --oneline -5
+```
+
+Display commits that will be included in PR.
+
+### 3. Confirm Push (if not auto_mode)
+
+**If `{auto_mode}` = true:**
+→ Auto-push to remote
+
+**If `{auto_mode}` = false:**
+Use AskUserQuestion:
+```yaml
+questions:
+  - header: "Push"
+    question: "Ready to push {branch_name} and create PR?"
+    options:
+      - label: "Push and create PR (Recommended)"
+        description: "Push commits to remote and open pull request"
+      - label: "Push only"
+        description: "Push to remote without creating PR"
+      - label: "Review commits first"
+        description: "Show me the full diff before pushing"
+      - label: "Cancel"
+        description: "Don't push or create PR"
+    multiSelect: false
+```
+
+### 4. Push to Remote
+
+```bash
+git push -u origin {branch_name}
+```
+
+**If push fails:**
+→ Display error and ask user how to proceed
+→ Common fixes: pull --rebase, force push (with warning)
+
+### 5. Create Pull Request (if pr_mode)
+
+**If `{pr_mode}` = true:**
+
+Generate PR content:
+- **Title:** `feat({task_id}): {task_description}`
+- **Body:** Summary of changes from the workflow
+
+```bash
+gh pr create --title "feat({task_id}): {task_description}" --body "$(cat <<'EOF'
+## Summary
+
+{Brief description of what was implemented}
+
+## Changes
+
+{List of key changes made}
+
+## Testing
+
+{How the changes were validated}
+
+---
+
+_Generated by APEX workflow_
+EOF
+)"
+```
+
+**Capture PR URL:**
+```bash
+gh pr view --json url -q '.url'
+```
+→ Store as `{pr_url}`
+
+### 6. Save Output (if save_mode)
+
+**If `{save_mode}` = true:**
+
+```bash
+bash {skill_dir}/scripts/update-progress.sh "{task_id}" "09" "finish" "in_progress"
+```
+
+Append to `{output_dir}/09-finish.md`: branch, PR URL, commits, timestamp.
+
+```bash
+bash {skill_dir}/scripts/update-progress.sh "{task_id}" "09" "finish" "complete"
+```
+
+### 7. Final Summary
+
+Display workflow completion summary:
+
+```
+═══════════════════════════════════════════════════════
+  APEX WORKFLOW COMPLETE
+═══════════════════════════════════════════════════════
+
+  Task: {task_description}
+  ID: {task_id}
+
+  ✓ Analysis complete
+  ✓ Plan created and approved
+  ✓ Implementation done
+  ✓ Validation passed
+  {if test_mode: "✓ Tests passing"}
+  {if examine_mode: "✓ Review findings resolved"}
+  ✓ Changes pushed to {branch_name}
+  {if pr_mode: "✓ PR created: {pr_url}"}
+
+═══════════════════════════════════════════════════════
+```
+
+---
+
+## SUCCESS METRICS:
+
+✅ All changes committed
+✅ Branch pushed to remote
+✅ PR created with proper title and description (if pr_mode)
+✅ PR URL captured and displayed
+✅ Output saved (if save_mode)
+✅ Clear completion summary provided
+
+## FAILURE MODES:
+
+❌ Creating PR with uncommitted changes
+❌ Pushing without user confirmation (when not auto_mode)
+❌ Force pushing without explicit user request
+❌ Not displaying PR URL after creation
+❌ **CRITICAL**: Using plain text prompts instead of AskUserQuestion
+
+---
+
+## WORKFLOW COMPLETE
+
+This is the final step of the APEX workflow. No next step to load.
+
+<critical>
+Remember: This step ONLY handles git operations and PR creation. All code changes should have been completed in earlier steps.
+</critical>

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

@@ -0,0 +1,51 @@
+# APEX Task: {{task_id}}
+
+**Created:** {{timestamp}}
+**Task:** {{task_description}}
+
+---
+
+## Configuration
+
+| Flag | Value |
+|------|-------|
+| Auto mode (`-a`) | {{auto_mode}} |
+| Examine mode (`-x`) | {{examine_mode}} |
+| Save mode (`-s`) | {{save_mode}} |
+| Test mode (`-t`) | {{test_mode}} |
+| Economy mode (`-e`) | {{economy_mode}} |
+| Branch mode (`-b`) | {{branch_mode}} |
+| PR mode (`-pr`) | {{pr_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 | |
+| 05-examine | {{examine_status}} | |
+| 06-resolve | {{examine_status}} | |
+| 07-tests | {{test_status}} | |
+| 08-run-tests | {{test_status}} | |
+| 09-finish | {{pr_status}} | |

package/claude-code-config/skills/workflow-apex/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/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/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/templates/04-validate.md

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

package/claude-code-config/skills/workflow-apex/templates/05-examine.md

@@ -0,0 +1,10 @@
+# Step 05: Examine
+
+**Task:** {{task_description}}
+**Started:** {{timestamp}}
+
+---
+
+## Adversarial Review
+
+_Review findings will be documented here..._

package/claude-code-config/skills/workflow-apex/templates/06-resolve.md

@@ -0,0 +1,10 @@
+# Step 06: Resolve
+
+**Task:** {{task_description}}
+**Started:** {{timestamp}}
+
+---
+
+## Resolution Log
+
+_Fixes will be logged here..._

package/claude-code-config/skills/workflow-apex/templates/07-tests.md

@@ -0,0 +1,10 @@
+# Step 07: Tests
+
+**Task:** {{task_description}}
+**Started:** {{timestamp}}
+
+---
+
+## Test Analysis and Creation
+
+_Test strategy and implementation will be documented here..._

package/claude-code-config/skills/workflow-apex/templates/08-run-tests.md

@@ -0,0 +1,10 @@
+# Step 08: Run Tests
+
+**Task:** {{task_description}}
+**Started:** {{timestamp}}
+
+---
+
+## Test Runner Log
+
+_Test execution results will be logged here..._

package/claude-code-config/skills/workflow-apex/templates/09-finish.md

@@ -0,0 +1,10 @@
+# Step 09: Finish
+
+**Task:** {{task_description}}
+**Started:** {{timestamp}}
+
+---
+
+## Pull Request Creation
+
+_PR creation process will be logged here..._