aiblueprint-cli 1.4.40 → 1.4.42

package/claude-code-config/skills/apex/SKILL.md

@@ -0,0 +1,116 @@
+---
+name: apex
+description: Systematic implementation using APEX methodology (Analyze-Plan-Execute-eXamine) with parallel agents, self-validation, and optional adversarial review. Use when implementing features, fixing bugs, or making code changes that benefit from structured workflow.
+argument-hint: "[-a] [-x] [-s] [-t] [-b] [-pr] [-i] [-m] [-r <task-id>] <task description>"
+---
+
+<objective>
+Execute systematic implementation workflows using the APEX methodology with progressive step loading.
+</objective>
+
+<quick_start>
+
+```bash
+/apex add authentication middleware           # Basic
+/apex -a -s implement user registration       # Autonomous + save
+/apex -a -x -s fix login bug                  # With adversarial review
+/apex -a -m implement full auth system        # Agent Teams (parallel)
+/apex -a -x -s -t add auth middleware         # Full workflow with tests
+/apex -a -pr add auth middleware              # With PR creation
+/apex -r 01-auth-middleware                   # Resume previous task
+/apex -e add auth middleware                  # Economy mode (save tokens)
+/apex -i add auth middleware                  # Interactive flag config
+```
+
+</quick_start>
+
+<flags>
+**Enable (lowercase ON) / Disable (UPPERCASE OFF):**
+
+| ON | OFF | Long | Description |
+|----|-----|------|-------------|
+| `-a` | `-A` | `--auto` | Skip confirmations, auto-approve |
+| `-x` | `-X` | `--examine` | Adversarial code review |
+| `-s` | `-S` | `--save` | Save outputs to `.claude/output/apex/` |
+| `-t` | `-T` | `--test` | Include test creation + runner |
+| `-e` | `-E` | `--economy` | No subagents, save tokens |
+| `-b` | `-B` | `--branch` | Verify not on main, create branch |
+| `-pr` | `-PR` | `--pull-request` | Create PR at end (enables -b) |
+| `-i` | | `--interactive` | Configure flags via menu |
+| `-k` | `-K` | `--tasks` | Task breakdown with dependencies |
+| `-m` | `-M` | `--teams` | Agent Teams parallel execution (enables -k) |
+| `-r` | | `--resume` | Resume from previous task ID |
+
+**Parsing:** Defaults from `steps/step-00-init.md`, flags override, remainder = `{task_description}`, ID = `NN-kebab-case`.
+</flags>
+
+<workflow>
+1. **Init** → Parse flags, setup state
+2. **Analyze** → Context gathering (1-10 parallel agents)
+3. **Plan** → File-by-file strategy + TaskList creation
+4. **Tasks** → Task breakdown (if -k or -m)
+5. **Execute** → Implementation (standard or Agent Teams if -m)
+6. **Validate** → Typecheck, lint, tests
+7. **Tests** → Create + run tests (if -t)
+8. **Examine** → Adversarial review (if -x)
+9. **Resolve** → Fix findings (if examine found issues)
+10. **Finish** → Create PR (if -pr)
+</workflow>
+
+<step_files>
+
+| Step | File | Purpose |
+|------|------|---------|
+| 00 | `steps/step-00-init.md` | Parse flags, initialize state |
+| 00b | `steps/step-00b-save.md` | Setup save output structure (if -s) |
+| 00b | `steps/step-00b-branch.md` | Git branch setup (if -b) |
+| 00b | `steps/step-00b-economy.md` | Economy mode overrides (if -e) |
+| 00b | `steps/step-00b-interactive.md` | Interactive flag config (if -i) |
+| 01 | `steps/step-01-analyze.md` | Smart context gathering |
+| 02 | `steps/step-02-plan.md` | File-by-file plan + TaskList |
+| 02b | `steps/step-02b-tasks.md` | Task breakdown (if -k/-m) |
+| 03 | `steps/step-03-execute.md` | Todo-driven implementation |
+| 03t | `steps/step-03-execute-teams.md` | Agent Team execution (if -m) |
+| 04 | `steps/step-04-validate.md` | Self-check and validation |
+| 05 | `steps/step-05-examine.md` | Adversarial code review |
+| 06 | `steps/step-06-resolve.md` | Finding resolution |
+| 07 | `steps/step-07-tests.md` | Test analysis and creation |
+| 08 | `steps/step-08-run-tests.md` | Test runner loop |
+| 09 | `steps/step-09-finish.md` | Create pull request |
+
+</step_files>
+
+<state_variables>
+
+| Variable | Type | Set by |
+|----------|------|--------|
+| `{task_description}` | string | step-00 |
+| `{feature_name}` | string | step-00 |
+| `{task_id}` | string | step-00 / step-00b-save |
+| `{acceptance_criteria}` | list | step-01 |
+| `{auto_mode}` | boolean | step-00 |
+| `{examine_mode}` | boolean | step-00 |
+| `{save_mode}` | boolean | step-00 |
+| `{test_mode}` | boolean | step-00 |
+| `{economy_mode}` | boolean | step-00 |
+| `{branch_mode}` | boolean | step-00 |
+| `{pr_mode}` | boolean | step-00 |
+| `{tasks_mode}` | boolean | step-00 |
+| `{teams_mode}` | boolean | step-00 |
+| `{output_dir}` | string | step-00b-save |
+| `{branch_name}` | string | step-00b-branch |
+
+</state_variables>
+
+<execution_rules>
+- **Load one step at a time** (progressive loading)
+- **ULTRA THINK** before major decisions
+- **Persist state variables** across all steps
+- **Follow next_step directive** at end of each step
+- **Save outputs** if `{save_mode}` = true (each step appends to its file)
+- **Use parallel agents** for independent exploration (step-01)
+</execution_rules>
+
+<entry_point>
+**FIRST ACTION:** Load `steps/step-00-init.md`
+</entry_point>

package/claude-code-config/skills/{workflow-apex → apex}/scripts/setup-templates.sh

@@ -18,8 +18,9 @@ ECONOMY_MODE="${7:-false}"
 BRANCH_MODE="${8:-false}"
 PR_MODE="${9:-false}"
 INTERACTIVE_MODE="${10:-false}"
-BRANCH_NAME="${11:-}"
-ORIGINAL_INPUT="${12:-}"
+TASKS_MODE="${11:-false}"
+BRANCH_NAME="${12:-}"
+ORIGINAL_INPUT="${13:-}"
 
 # Validate required arguments
 if [[ -z "$FEATURE_NAME" ]]; then
@@ -83,6 +84,9 @@ render_template() {
     local pr_status="⏭ Skip"
     [[ "$PR_MODE" == "true" ]] && pr_status="⏸ Pending"
 
+    local tasks_status="⏭ Skip"
+    [[ "$TASKS_MODE" == "true" ]] && tasks_status="⏸ Pending"
+
     # Read template and replace variables
     sed -e "s|{{task_id}}|${TASK_ID}|g" \
         -e "s|{{task_description}}|${TASK_DESCRIPTION}|g" \
@@ -95,10 +99,12 @@ render_template() {
         -e "s|{{branch_mode}}|${BRANCH_MODE}|g" \
         -e "s|{{pr_mode}}|${PR_MODE}|g" \
         -e "s|{{interactive_mode}}|${INTERACTIVE_MODE}|g" \
+        -e "s|{{tasks_mode}}|${TASKS_MODE}|g" \
         -e "s|{{branch_name}}|${BRANCH_NAME}|g" \
         -e "s|{{original_input}}|${ORIGINAL_INPUT}|g" \
         -e "s|{{examine_status}}|${examine_status}|g" \
         -e "s|{{test_status}}|${test_status}|g" \
+        -e "s|{{tasks_status}}|${tasks_status}|g" \
         -e "s|{{pr_status}}|${pr_status}|g" \
         "$template_file" > "$output_file"
 }
@@ -123,6 +129,10 @@ if [[ "$TEST_MODE" == "true" ]]; then
     render_template "${TEMPLATE_DIR}/08-run-tests.md" "${OUTPUT_DIR}/08-run-tests.md"
 fi
 
+if [[ "$TASKS_MODE" == "true" ]]; then
+    mkdir -p "${OUTPUT_DIR}/tasks"
+fi
+
 if [[ "$PR_MODE" == "true" ]]; then
     render_template "${TEMPLATE_DIR}/09-finish.md" "${OUTPUT_DIR}/09-finish.md"
 fi

package/claude-code-config/skills/{workflow-apex → apex}/steps/step-00-init.md

@@ -56,6 +56,8 @@ economy_mode: false # -e: No subagents, save tokens (for limited plans)
 branch_mode: false # -b: Verify not on main, create branch if needed
 pr_mode: false # -pr: Create pull request at end (enables -b)
 interactive_mode: false # -i: Configure flags interactively
+tasks_mode: false # -k: Generate task breakdown after plan
+teams_mode: false # -m: Use Claude Code Agent Teams for parallel execution
 
 # Presets:
 # Budget-friendly:  economy_mode: true
@@ -84,6 +86,8 @@ interactive_mode: false # -i: Configure flags interactively
 {branch_mode}  = <default>
 {pr_mode}      = <default>
 {interactive_mode} = <default>
+{tasks_mode}   = <default>
+{teams_mode}   = <default>
 ```
 
 **Step 2: Parse user input and override defaults:**
@@ -104,6 +108,14 @@ Disable flags (UPPERCASE - turn OFF):
   -E or --no-economy      → {economy_mode} = false
   -B or --no-branch       → {branch_mode} = false
   -PR or --no-pull-request → {pr_mode} = false
+  -K or --no-tasks        → {tasks_mode} = false
+  -M or --no-teams        → {teams_mode} = false
+
+Tasks mode:
+  -k or --tasks           → {tasks_mode} = true
+
+Teams mode:
+  -m or --teams           → {teams_mode} = true, {tasks_mode} = true
 
 Branch/PR flags:
   -b or --branch        → {branch_mode} = true
@@ -178,43 +190,14 @@ IF {branch_mode} = true:
 IF {economy_mode} = true:
   → Load steps/step-00b-economy.md
   → Apply economy overrides
-```
 
-### 4. Create Output Structure (if save_mode)
-
-**If `{save_mode}` = true:**
-
-Run the template setup script to initialize all output files:
-
-```bash
-bash {skill_dir}/scripts/setup-templates.sh \
-  "{feature_name}" \
-  "{task_description}" \
-  "{auto_mode}" \
-  "{examine_mode}" \
-  "{save_mode}" \
-  "{test_mode}" \
-  "{economy_mode}" \
-  "{branch_mode}" \
-  "{pr_mode}" \
-  "{interactive_mode}" \
-  "{branch_name}" \
-  "{original_input}"
+IF {save_mode} = true:
+  → Load steps/step-00b-save.md
+  → Create output structure, generate {task_id} and {output_dir}
+  → Return here with {task_id} and {output_dir} set
 ```
 
-**Note:** Pass `{feature_name}` (without number prefix), NOT `{task_id}`.
-The script auto-detects the next available number from existing folders.
-
-This script:
-
-- Auto-generates `{task_id}` = `NN-{feature_name}` (next available number)
-- Creates `.claude/output/apex/{task_id}/` directory
-- Initializes `00-context.md` with configuration and progress table
-- Pre-creates all step files from templates (01-analyze.md, 02-plan.md, etc.)
-- Only creates files for enabled steps (examine, tests, PR)
-- Outputs the generated `{task_id}` for use in subsequent steps
-
-### 5. Initialize and Proceed
+### 4. Initialize and Proceed
 
 **Always (regardless of auto_mode):**
 
@@ -233,6 +216,8 @@ Show COMPACT initialization summary (one table, then proceed immediately):
 | `{economy_mode}` | true/false |
 | `{branch_mode}` | true/false |
 | `{pr_mode}` | true/false |
+| `{tasks_mode}` | true/false |
+| `{teams_mode}` | true/false |
 
 → Analyzing...
 ```

package/claude-code-config/skills/{workflow-apex → apex}/steps/step-00b-interactive.md

@@ -45,6 +45,7 @@ Show current flag values:
 | Economy (`-e`) | {economy_mode ? "✓ ON" : "✗ OFF"} | No subagents |
 | Branch (`-b`) | {branch_mode ? "✓ ON" : "✗ OFF"} | Verify/create branch |
 | PR (`-pr`) | {pr_mode ? "✓ ON" : "✗ OFF"} | Create pull request |
+| Teams (`-m`) | {teams_mode ? "✓ ON" : "✗ OFF"} | Agent Teams parallel execution |
 ```
 
 ### 2. Ask for Flag Changes
@@ -80,6 +81,8 @@ questions:
         description: "{branch_mode ? 'Disable' : 'Enable'} - verify/create git branch"
       - label: "PR mode"
         description: "{pr_mode ? 'Disable' : 'Enable'} - create pull request at end"
+      - label: "Teams mode"
+        description: "{teams_mode ? 'Disable' : 'Enable'} - Agent Teams parallel execution"
       - label: "Done - keep current"
         description: "No more changes, proceed with workflow"
     multiSelect: true
@@ -96,9 +99,17 @@ IF "Test mode" selected → {test_mode} = !{test_mode}
 IF "Economy mode" selected → {economy_mode} = !{economy_mode}
 IF "Branch mode" selected → {branch_mode} = !{branch_mode}
 IF "PR mode" selected → {pr_mode} = !{pr_mode}
+IF "Teams mode" selected → {teams_mode} = !{teams_mode}
 ```
 
-**Special rule:** If PR mode enabled, auto-enable branch mode:
+**Special rules:**
+
+If Teams mode enabled, auto-enable tasks mode (teams requires task breakdown):
+```
+IF {teams_mode} = true → {tasks_mode} = true
+```
+
+If PR mode enabled, auto-enable branch mode:
 ```
 IF {pr_mode} = true → {branch_mode} = true
 ```
@@ -118,6 +129,7 @@ Display updated configuration:
 | Economy | {economy_mode ? "✓ ON" : "✗ OFF"} |
 | Branch | {branch_mode ? "✓ ON" : "✗ OFF"} |
 | PR | {pr_mode ? "✓ ON" : "✗ OFF"} |
+| Teams | {teams_mode ? "✓ ON" : "✗ OFF"} |
 ```
 
 ### 6. Return

package/claude-code-config/skills/apex/steps/step-00b-save.md

@@ -0,0 +1,123 @@
+---
+name: step-00b-save
+description: Setup save output structure for APEX workflow
+returns_to: step-00-init.md
+---
+
+# Step 0b: Save Mode Setup
+
+## MANDATORY EXECUTION RULES (READ FIRST):
+
+- 🛑 NEVER start analysis or implementation
+- ✅ ALWAYS run the setup script to create output structure
+- ✅ ALWAYS capture the generated `{task_id}` from the script output
+- 📋 YOU ARE A SETUP MANAGER, not an implementer
+- 🚫 FORBIDDEN to start any analysis work
+
+## CONTEXT BOUNDARIES:
+
+- Variables available: `{feature_name}`, `{task_description}`, all flag variables, `{branch_name}`
+- This sub-step sets: `{task_id}`, `{output_dir}`
+- Return to step-00-init.md after completion
+
+## YOUR TASK:
+
+Create the output directory structure and initialize all output files for the APEX workflow.
+
+---
+
+## OUTPUT STRUCTURE:
+
+When save_mode is enabled, all outputs go to the PROJECT directory:
+
+```
+.claude/output/apex/{task-id}/
+├── 00-context.md        # Params, user request, timestamp
+├── 01-analyze.md        # Analysis findings
+├── 02-plan.md           # Implementation plan
+├── 03-execute.md        # Execution log
+├── 04-validate.md       # Validation results
+├── 02b-tasks/           # Task breakdown (if -k or -m)
+│   ├── README.md
+│   └── task-NN-*.md
+├── 05-examine.md        # Review findings (if -x)
+├── 06-resolve.md        # Resolution log (if -x)
+├── 07-tests.md          # Test analysis (if -t)
+├── 08-run-tests.md      # Test runner log (if -t)
+└── 09-finish.md         # PR creation (if -pr)
+```
+
+## EXECUTION SEQUENCE:
+
+### 1. Run Template Setup Script
+
+```bash
+bash {skill_dir}/scripts/setup-templates.sh \
+  "{feature_name}" \
+  "{task_description}" \
+  "{auto_mode}" \
+  "{examine_mode}" \
+  "{save_mode}" \
+  "{test_mode}" \
+  "{economy_mode}" \
+  "{branch_mode}" \
+  "{pr_mode}" \
+  "{interactive_mode}" \
+  "{tasks_mode}" \
+  "{branch_name}" \
+  "{original_input}"
+```
+
+**Note:** Pass `{feature_name}` (without number prefix), NOT `{task_id}`.
+
+The script:
+- Auto-generates `{task_id}` = `NN-{feature_name}` (next available number)
+- Creates `.claude/output/apex/{task_id}/` directory
+- Initializes `00-context.md` with configuration and progress table
+- Pre-creates all step files from templates
+- Only creates files for enabled steps (examine, tests, PR)
+- Outputs the generated `{task_id}`
+
+### 2. Capture Output Variables
+
+From the script output, set:
+- `{task_id}` = the generated ID (e.g., `01-add-auth-middleware`)
+- `{output_dir}` = `.claude/output/apex/{task_id}`
+
+### 3. Return
+
+→ Return to step-00-init.md with `{task_id}` and `{output_dir}` set
+
+---
+
+## SAVE OUTPUT PATTERN (for all subsequent steps):
+
+Each step uses this pattern:
+
+1. `bash {skill_dir}/scripts/update-progress.sh "{task_id}" "{step_num}" "{step_name}" "in_progress"`
+2. Append findings/outputs to the pre-created step file
+3. `bash {skill_dir}/scripts/update-progress.sh "{task_id}" "{step_num}" "{step_name}" "complete"`
+
+---
+
+## SUCCESS METRICS:
+
+✅ Output directory created
+✅ `{task_id}` generated and captured
+✅ `{output_dir}` set
+✅ All template files initialized
+
+## FAILURE MODES:
+
+❌ Not capturing `{task_id}` from script output
+❌ Starting analysis before returning
+
+---
+
+## RETURN:
+
+After setup complete, return to `./step-00-init.md` to continue initialization.
+
+<critical>
+Remember: This sub-step ONLY creates the output structure. Return immediately after setting {task_id} and {output_dir}.
+</critical>

package/claude-code-config/skills/{workflow-apex → apex}/steps/step-01-analyze.md

@@ -11,11 +11,14 @@ next_step: steps/step-02-plan.md
 - 🛑 NEVER plan or design solutions - that's step 2
 - 🛑 NEVER create todos or implementation tasks
 - 🛑 NEVER decide HOW to implement anything
+- 🛑 NEVER mark analyze as "complete" BEFORE writing findings to `{output_dir}/01-analyze.md` (if save_mode)
 - ✅ ALWAYS focus on discovering WHAT EXISTS
 - ✅ ALWAYS report findings with file paths and line numbers
+- ✅ IF save_mode: ALWAYS use Edit tool to append ALL findings to `{output_dir}/01-analyze.md` BEFORE proceeding
 - 📋 YOU ARE AN EXPLORER, not a planner
 - 💬 FOCUS on "What is here?" NOT "What should we build?"
 - 🚫 FORBIDDEN to suggest implementations or approaches
+- 🚫 FORBIDDEN to skip file saving when save_mode is true
 
 ## 🧠 SMART AGENT STRATEGY
 
@@ -30,9 +33,10 @@ Before exploring, THINK about what information you need and launch the RIGHT age
 ## EXECUTION PROTOCOLS:
 
 - 🎯 Launch parallel exploration agents (unless economy_mode)
-- 💾 Append findings to output file (if save_mode)
+- 💾 IF save_mode: Use Edit tool to append findings to `{output_dir}/01-analyze.md` AFTER agents complete and BEFORE showing summary
 - 📖 Document patterns with specific file:line references
 - 🚫 FORBIDDEN to proceed until context is complete
+- 🚫 FORBIDDEN to proceed to step-02 without saving findings first (if save_mode)
 
 ## CONTEXT BOUNDARIES:
 
@@ -214,9 +218,14 @@ Find common patterns and pitfalls.
 [Task: websearch - Stripe webhook security best practices]
 ```
 
-### 4. Synthesize Findings
+### 4. Synthesize Findings + Save to File
 
-Combine results into structured context:
+<critical>
+**IF `{save_mode}` = true: You MUST write findings to the file BEFORE presenting the summary or proceeding.**
+This is the most commonly skipped step. DO NOT skip it.
+</critical>
+
+Combine all agent results into structured context using this format:
 
 ```markdown
 ## Codebase Context
@@ -256,7 +265,9 @@ Combine results into structured context:
 - Use httpOnly cookies for tokens
 ```
 
-**If `{save_mode}` = true:** Append synthesis to 01-analyze.md
+**IF `{save_mode}` = true (MANDATORY - DO THIS NOW):**
+
+Use the **Edit tool** to append the full synthesis to `{output_dir}/01-analyze.md`. Replace the placeholder text `_Findings will be appended here as exploration progresses..._` with all the structured findings above.
 
 ### 5. Infer Acceptance Criteria
 
@@ -274,9 +285,26 @@ Based on "{task_description}" and existing patterns:
 _These will be refined in the planning step._
 ```
 
-**If `{save_mode}` = true:** Update 00-context.md with acceptance criteria
+**If `{save_mode}` = true:** Append acceptance criteria to `{output_dir}/01-analyze.md` using Edit tool.
 
-### 6. Present Context Summary
+### 6. Complete Save Output (if save_mode)
+
+<critical>
+**This step MUST happen BEFORE presenting the summary to the user.**
+The file must already contain all findings before you proceed.
+</critical>
+
+**If `{save_mode}` = true:**
+
+1. Verify `{output_dir}/01-analyze.md` contains the full analysis (Read it to confirm)
+2. Update progress:
+
+```bash
+bash {skill_dir}/scripts/update-progress.sh "{task_id}" "01" "analyze" "complete"
+bash {skill_dir}/scripts/update-progress.sh "{task_id}" "02" "plan" "in_progress"
+```
+
+### 7. Present Context Summary
 
 **Always (regardless of auto_mode):**
 
@@ -300,17 +328,6 @@ Present summary and proceed directly to planning:
 Do NOT ask for user confirmation here - always proceed directly to step-02-plan.
 </critical>
 
-### 7. Complete Save Output (if save_mode)
-
-**If `{save_mode}` = true:**
-
-Append summary to `{output_dir}/01-analyze.md` then:
-
-```bash
-bash {skill_dir}/scripts/update-progress.sh "{task_id}" "01" "analyze" "complete"
-bash {skill_dir}/scripts/update-progress.sh "{task_id}" "02" "plan" "in_progress"
-```
-
 ---
 
 ## SUCCESS METRICS:
@@ -329,6 +346,7 @@ bash {skill_dir}/scripts/update-progress.sh "{task_id}" "02" "plan" "in_progress
 
 ## FAILURE MODES:
 
+❌ **CRITICAL**: Skipping file save when save_mode is true (proceeding to plan without writing to 01-analyze.md)
 ❌ Starting to plan or design (that's step 2!)
 ❌ Suggesting implementations or approaches
 ❌ Missing obvious related files
@@ -358,4 +376,5 @@ Always proceed directly to `./step-02-plan.md` after presenting context summary.
 <critical>
 Remember: Analysis is ONLY about "What exists?" - save all planning for step-02!
 Do NOT ask for confirmation - proceed directly!
+IF save_mode = true: The 01-analyze.md file MUST contain all findings BEFORE you load step-02-plan.md.
 </critical>