aiblueprint-cli 1.4.88 → 1.4.90

package/agents-config/skills/apex/steps/step-09-finish.md

@@ -0,0 +1,223 @@
+---
+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}`, `{teams_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:
+
+### 0. Shutdown Agent Team (if teams_mode)
+
+<critical>
+This is the ONLY step where team shutdown should happen.
+All previous steps (validate, examine, resolve) keep the team alive.
+</critical>
+
+**If `{teams_mode}` = true:**
+
+1. Send shutdown_request to each teammate:
+```
+SendMessage:
+  type: "shutdown_request"
+  recipient: "impl-{name}"
+  content: "APEX workflow complete. Shutting down team."
+```
+
+2. Wait for all teammates to confirm shutdown.
+
+3. Delete the team:
+```
+TeamDelete
+```
+
+→ This cleans up team files and task directories.
+
+### 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:
+
+✅ Agent team shut down gracefully via SendMessage shutdown_request (if teams_mode)
+✅ TeamDelete called to clean up team resources (if teams_mode)
+✅ 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 handles git operations, PR creation, AND team shutdown (if teams_mode).
+All code changes should have been completed in earlier steps.
+Team shutdown MUST happen here - step 0 of execution sequence - before git operations.
+</critical>

package/agents-config/skills/apex/steps/step-10-verify.md

@@ -0,0 +1,296 @@
+---
+name: step-10-verify
+description: Launch app and verify feature works through real user surface
+prev_step: steps/step-04-validate.md
+next_step: steps/step-09-finish.md
+---
+
+# Step 10: Verify (Feature Validation)
+
+## MANDATORY EXECUTION RULES (READ FIRST):
+
+- 🛑 NEVER skip verification - that defeats the purpose
+- 🛑 NEVER claim feature works without actually testing it
+- 📐 ALWAYS read the project's recommended verification rules FIRST (`.agents/rules/`, `AGENTS.md`, `CLAUDE.md`) and follow them
+- ✅ ALWAYS launch a verifier agent to test through real surface
+- ✅ ALWAYS compare results against original user request
+- 📸 ALWAYS capture 1+ screenshots proving the feature works - verification is INCOMPLETE without visual proof
+- ✅ ALWAYS fix issues before proceeding (unless user skips)
+- 📋 YOU ARE A VERIFIER, not an implementer
+- 💬 FOCUS on "Does the feature actually work for a real user?"
+- 🚫 FORBIDDEN to proceed with FAIL verdict without user confirmation
+
+## EXECUTION PROTOCOLS:
+
+- 🎯 Launch verifier agent with full context
+- 💾 Log verification results (if save_mode)
+- 📖 Compare each AC against real behavior
+- 🚫 FORBIDDEN to fake verification
+
+## CONTEXT BOUNDARIES:
+
+- Implementation is complete, validated, and reviewed
+- All typecheck/lint/tests pass
+- Now testing the REAL user experience
+- **If `{teams_mode}` = true:** Agent team is still alive. Do NOT shutdown teammates - that happens in step-09-finish only.
+
+## YOUR TASK:
+
+Launch the application, test the feature through real user interaction, and verify it matches the original request.
+
+---
+
+<available_state>
+From previous steps:
+
+| Variable | Description |
+|----------|-------------|
+| `{task_description}` | Original user request |
+| `{task_id}` | Kebab-case identifier |
+| `{acceptance_criteria}` | Success criteria from analysis |
+| `{auto_mode}` | Skip confirmations |
+| `{save_mode}` | Save outputs to files |
+| `{economy_mode}` | No subagents |
+| `{output_dir}` | Path to output (if save_mode) |
+| Files modified | From 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}" "10" "verify" "in_progress"
+```
+
+Append results to `{output_dir}/10-verify.md` as you work.
+
+### 2. Gather Context for Verifier
+
+Collect all information the verifier agent needs:
+
+```
+1. Original task description: {task_description}
+2. Acceptance criteria: {acceptance_criteria}
+3. Modified files (from git):
+   git diff --name-only HEAD~1
+   git status --porcelain
+4. Implementation summary from step-03/04
+```
+
+### 2b. Load Recommended Verification Rules
+
+Look for project-specific verification conventions and **follow them**. They override the defaults below. Check in order:
+
+1. `.agents/rules/` — any rule file about verification, testing, QA, or e2e (e.g. `verify.md`, `testing.md`)
+2. `AGENTS.md` — verification / commands sections
+3. `CLAUDE.md` — verification preferences (e.g. "Prefer /dev-browser for verification")
+4. `README.md` + `package.json` scripts — how to launch / test
+
+```bash
+ls .agents/rules/ 2>/dev/null
+cat AGENTS.md CLAUDE.md 2>/dev/null
+```
+
+Capture the recommended launch command, auth/login steps, test URLs/credentials, and any required evidence into `{verification_rules}` and pass it to the verifier. If nothing is documented, fall back to detecting the dev/start command from `package.json`.
+
+### 3. Launch Verifier Agent
+
+**If `{economy_mode}` = true:**
+-> Self-verify: manually test the feature using available tools (dev-browser, curl, shell commands). FOLLOW the recommended verification rules from step 2b, capture 1+ screenshots as proof, and include the screenshots directly in the chat using Markdown image syntax with absolute local paths. Follow the verification process below directly instead of launching an agent.
+
+**If `{economy_mode}` = false:**
+-> Launch a verifier sub-agent:
+
+```
+Sub-agent:
+  profile/type: "verifier"
+  prompt: |
+    ## Feature Verification
+
+    **Original Request:** {task_description}
+
+    **Acceptance Criteria:**
+    {acceptance_criteria - list each one}
+
+    **Files Modified:**
+    {list of modified files}
+
+    **Implementation Summary:**
+    {brief summary of what was done}
+
+    **Recommended Verification Rules (FOLLOW THESE):**
+    {verification_rules - or "none documented; use defaults"}
+
+    Verify this feature works correctly by:
+    1. FOLLOW the recommended verification rules above (launch command, auth, URLs)
+    2. Launch the app (rules first, else package.json dev/start command)
+    3. Navigate to the relevant pages/endpoints
+    4. Test each acceptance criterion through real interaction
+    5. Use /dev-browser for web UI (capture screenshots), curl for APIs, shell for CLI tools
+    6. 📸 MANDATORY: Capture 1+ screenshots proving the finished feature works. For web UI use dev-browser saveScreenshot; for non-visual surfaces capture the terminal output / response as evidence
+    7. Output the screenshot(s) directly in the chat using Markdown image syntax with absolute local paths, e.g. `![Feature verification](/absolute/path/screenshot.png)`. Do NOT only list paths.
+    8. Report your findings with PASS/FAIL for each AC, listing the screenshot paths below the inline images
+    9. List anything missing compared to the original request
+```
+
+### 4. Process Verification Results
+
+Parse the verifier agent's report:
+
+**If no screenshot / evidence was captured or screenshots are only listed as paths without inline chat images:**
+-> Verification is INCOMPLETE. Re-run capture (or send the verifier back) before accepting any PASS verdict.
+
+**If all ACs PASS:**
+-> Display success summary and proceed
+
+**If any ACs FAIL:**
+-> Display failure details
+
+### 5. Present Verification Report
+
+```markdown
+## Verification Results
+
+**Feature:** {task_description}
+
+| AC | Status | Details |
+|----|--------|---------|
+| AC1 | ✓ PASS | Working as expected |
+| AC2 | ✗ FAIL | {what went wrong} |
+
+**Screenshots:** {inline Markdown image(s) REQUIRED, then list screenshot paths - at least 1}
+
+**Verdict:** {PASS or FAIL}
+```
+
+### 6. Handle Failures
+
+**If verdict = PASS:**
+-> Proceed to next step
+
+**If verdict = FAIL:**
+
+**If `{auto_mode}` = true:**
+-> Auto-fix: Apply fixes for each failing AC, then re-verify (max 2 retry rounds)
+
+**If `{auto_mode}` = false:**
+
+```yaml
+questions:
+  - header: "Verify"
+    question: "Verification found issues. How would you like to proceed?"
+    options:
+      - label: "Fix and re-verify (Recommended)"
+        description: "Apply fixes for failing ACs and verify again"
+      - label: "Fix without re-verify"
+        description: "Apply fixes but skip second verification"
+      - label: "Skip verification"
+        description: "Accept current state, proceed anyway"
+      - label: "Discuss issues"
+        description: "Let me review the findings first"
+    multiSelect: false
+```
+
+### 7. Fix Loop (if user chooses to fix)
+
+```
+max_verify_rounds = 3
+round = 0
+
+WHILE round < max_verify_rounds AND verdict = FAIL:
+    round += 1
+
+    1. Read each failing AC
+    2. Identify the root cause
+    3. Apply the fix
+    4. Run typecheck + lint to ensure no regressions
+    5. Re-launch verifier agent (or self-verify if economy_mode)
+    6. Update verdict
+```
+
+**If still failing after 3 rounds:**
+
+```yaml
+questions:
+  - header: "Stuck"
+    question: "Verification still failing after {round} fix rounds. How proceed?"
+    options:
+      - label: "Keep trying"
+        description: "Continue fixing"
+      - label: "Accept current state"
+        description: "Proceed with known issues"
+      - label: "I'll fix manually"
+        description: "Let me investigate"
+    multiSelect: false
+```
+
+### 8. Complete Save Output (if save_mode)
+
+**If `{save_mode}` = true:**
+
+Append to `{output_dir}/10-verify.md`:
+```markdown
+---
+## Step Complete
+**Status:** ✓ Complete
+**Verdict:** {PASS/FAIL}
+**Rounds:** {count}
+**Screenshots:** {inline Markdown image(s) first, then paths - at least 1}
+**Failing ACs:** {list or "none"}
+**Timestamp:** {ISO timestamp}
+```
+
+```bash
+bash {skill_dir}/scripts/update-progress.sh "{task_id}" "10" "verify" "complete"
+```
+
+---
+
+## SUCCESS METRICS:
+
+✅ Recommended verification rules followed
+✅ Feature tested through real user surface
+✅ Each AC verified with actual interaction
+✅ 1+ screenshots captured as visual proof
+✅ Failures identified with clear descriptions
+✅ Fixes applied and re-verified (if needed)
+✅ User informed of verification status
+
+## FAILURE MODES:
+
+❌ Claiming verification passed without actually testing
+❌ Ignoring the project's recommended verification rules
+❌ No screenshot / visual proof of the feature working
+❌ Not launching the app
+❌ Testing only happy path, ignoring ACs
+❌ Auto-proceeding with FAIL verdict (without user OK)
+❌ Not comparing against original user request
+❌ **CRITICAL**: Not using AskUserQuestion for failure decisions
+
+## VERIFICATION PROTOCOLS:
+
+- Follow the project's recommended verification rules first (`.agents/rules/`, `AGENTS.md`, `CLAUDE.md`)
+- Test through REAL user surface (browser, CLI, API)
+- Capture 1+ screenshots as proof - no PASS verdict without evidence
+- Compare against ORIGINAL request, not just code
+- Fix and re-verify, don't just fix and hope
+- Be honest about failures
+
+---
+
+## NEXT STEP:
+
+Based on flags:
+- **If pr_mode:** Load `./step-09-finish.md` to create pull request
+- **Otherwise:** Workflow complete - show summary
+
+<critical>
+Remember: The whole point of verify is to catch things that code review and tests miss.
+Test the feature like a real user would - don't just check the code!
+If teams_mode is active: NEVER shutdown teammates - they stay alive until step-09-finish!
+</critical>

package/agents-config/skills/apex/templates/00-context.md

@@ -0,0 +1,55 @@
+# 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}} |
+| Tasks mode (`-k`) | {{tasks_mode}} |
+| Verify mode (`-v`) | {{verify_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 | |
+| 02b-tasks | {{tasks_status}} | |
+| 03-execute | ⏸ Pending | |
+| 04-validate | ⏸ Pending | |
+| 05-examine | {{examine_status}} | |
+| 06-resolve | {{examine_status}} | |
+| 07-tests | {{test_status}} | |
+| 08-run-tests | {{test_status}} | |
+| 10-verify | {{verify_status}} | |
+| 09-finish | {{pr_status}} | |

package/agents-config/skills/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/agents-config/skills/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/agents-config/skills/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/agents-config/skills/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/agents-config/skills/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/agents-config/skills/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/agents-config/skills/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/agents-config/skills/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/agents-config/skills/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..._

package/agents-config/skills/apex/templates/10-verify.md

@@ -0,0 +1,9 @@
+# Step 10: Verify - {{task_id}}
+
+**Task:** {{task_description}}
+
+---
+
+## Verification Results
+
+_Results will be appended during execution_