aiblueprint-cli 1.4.87 → 1.4.89

package/agents-config/skills/apex/steps/step-00-init.md

@@ -0,0 +1,278 @@
+---
+name: step-00-init
+description: Initialize APEX workflow - parse flags, detect continuation, setup state
+next_step: steps/step-01-analyze.md
+---
+
+# Step 0: Initialization
+
+## MANDATORY EXECUTION RULES (READ FIRST):
+
+- 🛑 NEVER skip flag parsing
+- 🛑 ONLY check for existing workflow if resume_task is set
+- ✅ ALWAYS parse ALL flags before any other action
+- ✅ ONLY check for resume if {resume_task} is set
+- 📋 YOU ARE AN INITIALIZER, not an executor
+- 💬 FOCUS on setup only - don't look ahead to implementation
+- 🚫 FORBIDDEN to load step-01 until init is complete
+
+## EXECUTION PROTOCOLS:
+
+- 🎯 Parse flags first, then check resume, then setup
+- 💾 Create output structure if save_mode enabled
+- 📖 Initialize all state variables before proceeding
+- 🚫 FORBIDDEN to start analysis (that's step-01's job)
+- ✅ ALWAYS show COMPACT summary (one table) and proceed immediately
+- 🚫 FORBIDDEN to show verbose parsing logs or explanations
+
+## CONTEXT BOUNDARIES:
+
+- This is the FIRST step - no previous context exists
+- User input contains flags and task description
+- Output folder may or may not exist
+- Don't assume anything about the codebase yet
+
+## YOUR TASK:
+
+Initialize the APEX workflow by parsing flags, detecting continuation state, and setting up the execution environment.
+
+---
+
+<defaults>
+## Default Configuration
+
+**Edit these values to change default behavior. Flags always override defaults.**
+
+```yaml
+# ===========================================
+# APEX DEFAULT SETTINGS
+# ===========================================
+
+auto_mode: false # -a: Skip confirmations, use recommended options
+examine_mode: false # -x: Auto-proceed to adversarial review
+save_mode: false # -s: Save outputs to .claude/output/apex/
+test_mode: false # -t: Include test creation and runner steps
+verify_mode: false # -v: Launch app and verify feature works via real user surface
+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
+# Full quality:     examine_mode: true, save_mode: true, test_mode: true
+# Autonomous:       auto_mode: true, examine_mode: true, save_mode: true, test_mode: true
+```
+
+**Flag Reference:** See `SKILL.md` for complete flag documentation and examples.
+
+</defaults>
+
+---
+
+## EXECUTION SEQUENCE:
+
+### 1. Parse Flags and Input
+
+**Step 1: Load defaults from config above**
+
+```
+{auto_mode}    = <default>
+{examine_mode} = <default>
+{save_mode}    = <default>
+{test_mode}    = <default>
+{verify_mode}  = <default>
+{economy_mode} = <default>
+{branch_mode}  = <default>
+{pr_mode}      = <default>
+{interactive_mode} = <default>
+{tasks_mode}   = <default>
+{teams_mode}   = <default>
+```
+
+**Step 2: Parse user input and override defaults:**
+
+```
+Enable flags (lowercase - turn ON):
+  -a or --auto     → {auto_mode} = true
+  -x or --examine  → {examine_mode} = true
+  -s or --save     → {save_mode} = true
+  -t or --test     → {test_mode} = true
+  -v or --verify   → {verify_mode} = true
+  -e or --economy  → {economy_mode} = true
+
+Disable flags (UPPERCASE - turn OFF):
+  -A or --no-auto         → {auto_mode} = false
+  -X or --no-examine      → {examine_mode} = false
+  -S or --no-save         → {save_mode} = false
+  -T or --no-test         → {test_mode} = false
+  -V or --no-verify       → {verify_mode} = false
+  -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
+  -pr or --pull-request → {pr_mode} = true, {branch_mode} = true
+
+Interactive:
+  -i or --interactive   → {interactive_mode} = true
+
+Other:
+  -r or --resume   → {resume_task} = <next argument>
+  Remainder        → {task_description}
+```
+
+**Step 3: Generate feature_name and task_id:**
+
+```
+{feature_name} = kebab-case-description (without number prefix)
+
+Example: "add user authentication" → "add-user-authentication"
+
+{task_id} will be generated by the setup script:
+  - Script auto-detects next available number in .claude/output/apex/
+  - Result: "01-add-user-authentication" (or 02, 03, etc.)
+```
+
+### 2. Check Resume Mode
+
+<critical>
+ONLY execute this section if {resume_task} is set!
+If {resume_task} is NOT set, skip directly to step 3.
+</critical>
+
+**If `{resume_task}` is set:**
+
+1. **Search for matching task:**
+
+   ```bash
+   ls .claude/output/apex/ | grep "^{resume_task}"
+   ```
+
+2. **If exact match found:**
+   - Read `00-context.md` to restore state variables
+   - Scan step files to find last completed step (check for completion marker)
+   - Load next incomplete step
+   - **STOP** - do not continue with fresh init
+
+3. **If partial match (e.g., `-r 01`):**
+   - If single match: use it
+   - If multiple matches: list them and ask user to specify
+
+4. **If no match found:**
+   - List available tasks
+   - Ask user to provide correct ID
+
+**If {resume_task} is NOT set:** → Skip directly to step 3
+
+### 3. Run Optional Sub-Steps
+
+**Load sub-steps in order (if flags enabled):**
+
+```
+IF {interactive_mode} = true:
+  → Load steps/step-00b-interactive.md
+  → User configures flags interactively
+  → Return here with updated flags
+
+IF {branch_mode} = true:
+  → Load steps/step-00b-branch.md
+  → Verify/create branch
+  → Return here with {branch_name} set
+
+IF {economy_mode} = true:
+  → Load steps/step-00b-economy.md
+  → Apply economy overrides
+
+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
+```
+
+### 4. Initialize and Proceed
+
+**Always (regardless of auto_mode):**
+
+Show COMPACT initialization summary (one table, then proceed immediately):
+
+```
+✓ APEX: {task_description}
+
+| Variable | Value |
+|----------|-------|
+| `{task_id}` | 01-kebab-name |
+| `{auto_mode}` | true/false |
+| `{examine_mode}` | true/false |
+| `{save_mode}` | true/false |
+| `{test_mode}` | true/false |
+| `{verify_mode}` | true/false |
+| `{economy_mode}` | true/false |
+| `{branch_mode}` | true/false |
+| `{pr_mode}` | true/false |
+| `{tasks_mode}` | true/false |
+| `{teams_mode}` | true/false |
+
+→ Analyzing...
+```
+
+<critical>
+KEEP OUTPUT MINIMAL:
+- One line header with task
+- One table with ALL variables (use brackets to show they're available)
+- One line "→ Analyzing..." then IMMEDIATELY load step-01
+- NO verbose explanations, NO parsing logs, NO separators
+</critical>
+
+**Then proceed directly to step-01-analyze.md**
+
+---
+
+## SUCCESS METRICS:
+
+✅ All flags correctly parsed (enable AND disable)
+✅ Output is COMPACT (one table, no verbose logs)
+✅ Variables shown with `{brackets}` notation
+✅ Proceeded to step-01 immediately after table
+✅ Output folder created with 00-context.md (if save_mode)
+
+## FAILURE MODES:
+
+❌ Verbose output with separators and explanations
+❌ Showing parsing steps/logs to user
+❌ Not using `{variable}` bracket notation
+❌ Not proceeding immediately after summary
+❌ **CRITICAL**: Blocking workflow with unnecessary confirmations
+
+## INITIALIZATION PROTOCOLS:
+
+- Parse ALL flags before any other action
+- Check resume BEFORE creating new output folder
+- Verify branch BEFORE creating output structure (if branch_mode)
+- Create output structure BEFORE confirming start
+- Load economy overrides BEFORE proceeding to step-01
+
+---
+
+## NEXT STEP:
+
+After showing initialization summary, always proceed directly to `./step-01-analyze.md`
+
+<critical>
+Remember:
+- Step-00 is an INITIALIZER, not a GATEKEEPER
+- Output MUST be compact: one table, no verbose logs
+- Use `{variable}` notation to show available state
+- Proceed immediately - never block!
+</critical>

package/agents-config/skills/apex/steps/step-00b-branch.md

@@ -0,0 +1,126 @@
+---
+name: step-00b-branch
+description: Verify and setup git branch for APEX workflow
+returns_to: step-00-init.md
+---
+
+# Step 0b: Branch Setup
+
+## MANDATORY EXECUTION RULES (READ FIRST):
+
+- 🛑 NEVER commit directly to main/master when branch_mode enabled
+- 🛑 NEVER skip branch verification
+- ✅ ALWAYS check current branch first
+- ✅ ALWAYS store {branch_name} before returning
+- 📋 YOU ARE A BRANCH MANAGER, not an implementer
+- 💬 FOCUS on branch setup only
+- 🚫 FORBIDDEN to start any implementation work
+
+## CONTEXT BOUNDARIES:
+
+- Variables available: `{task_id}`, `{auto_mode}`, `{pr_mode}`
+- This sub-step sets: `{branch_name}`
+- Return to step-00-init.md after completion
+
+## YOUR TASK:
+
+Verify the current git branch and create a feature branch if on main/master.
+
+---
+
+## EXECUTION SEQUENCE:
+
+### 1. Check Current Branch
+
+```bash
+git branch --show-current
+```
+
+Store result as `{current_branch}`
+
+### 2. Evaluate Branch Status
+
+**If `{current_branch}` is `main` or `master`:**
+→ Go to step 3 (Create Branch)
+
+**If `{current_branch}` is NOT main/master:**
+→ Store `{branch_name}` = `{current_branch}`
+→ Display: "✓ Already on branch: {branch_name}"
+→ Return to step-00-init.md
+
+### 3. Create Feature Branch
+
+**If `{auto_mode}` = true:**
+→ Auto-create branch: `feat/{task_id}`
+
+**If `{auto_mode}` = false:**
+Use AskUserQuestion:
+```yaml
+questions:
+  - header: "Branch"
+    question: "You're on {current_branch}. Create a new branch for this task?"
+    options:
+      - label: "Create feat/{task_id} (Recommended)"
+        description: "Create new feature branch and switch to it"
+      - label: "Custom branch name"
+        description: "I'll specify a custom branch name"
+      - label: "Stay on {current_branch}"
+        description: "Continue without creating a branch (not recommended for PRs)"
+    multiSelect: false
+```
+
+### 4. Execute Branch Creation
+
+**If user chose "Create feat/{task_id}" or auto_mode:**
+```bash
+git checkout -b feat/{task_id}
+```
+→ `{branch_name}` = `feat/{task_id}`
+
+**If user chose "Custom branch name":**
+→ Ask for branch name
+```bash
+git checkout -b {custom_name}
+```
+→ `{branch_name}` = `{custom_name}`
+
+**If user chose "Stay on {current_branch}":**
+→ `{branch_name}` = `{current_branch}`
+→ Display warning if `{pr_mode}` = true:
+  "⚠️ Warning: Creating PR from {current_branch} directly"
+
+### 5. Confirm and Return
+
+Display:
+```
+✓ Branch: {branch_name}
+{if new branch created: "Created and switched to new branch"}
+```
+
+→ Return to step-00-init.md with `{branch_name}` set
+
+---
+
+## SUCCESS METRICS:
+
+✅ Current branch verified
+✅ Feature branch created if on main/master (unless user declined)
+✅ `{branch_name}` variable set
+✅ User warned if staying on main with PR mode
+
+## FAILURE MODES:
+
+❌ Starting implementation before returning
+❌ Not setting `{branch_name}` variable
+❌ Creating branch without user consent (when not auto_mode)
+❌ **CRITICAL**: Using plain text prompts instead of AskUserQuestion
+
+---
+
+## RETURN:
+
+After branch setup complete, return to `./step-00-init.md` to continue initialization.
+
+<critical>
+Remember: This sub-step ONLY handles branch setup. Return immediately after setting {branch_name}.
+</critical>

package/agents-config/skills/apex/steps/step-00b-economy.md

@@ -0,0 +1,247 @@
+---
+name: step-00b-economy
+description: Economy mode overrides - no subagents, direct tool usage to save tokens
+load_condition: economy_mode = true
+---
+
+# Economy Mode Overrides
+
+**This file is ONLY loaded when `-e` or `--economy` flag is active.**
+
+These instructions OVERRIDE the default behavior in all steps to save tokens by avoiding subagent launches.
+
+---
+
+<why_economy_mode>
+**Purpose:** Reduce token usage for users with limited Claude Code plans.
+
+**Trade-offs:**
+- ✅ Uses ~70% fewer tokens
+- ✅ Faster execution (no agent overhead)
+- ⚠️ Less thorough exploration
+- ⚠️ No parallel research
+- ⚠️ May miss some context
+
+**When to use:**
+- Limited monthly token budget
+- Simple, well-defined tasks
+- Familiar codebase
+- Quick fixes or small features
+</why_economy_mode>
+
+---
+
+<override_rules>
+
+## CRITICAL: Apply These Overrides to ALL Steps
+
+**When `{economy_mode}` = true, these rules OVERRIDE the default instructions:**
+
+---
+
+### Override 1: No Subagent Launches
+
+**DEFAULT behavior (when economy_mode = false):**
+```
+Launch parallel agents:
+- Agent 1: explore-codebase
+- Agent 2: explore-docs
+- Agent 3: websearch
+```
+
+**ECONOMY behavior (when economy_mode = true):**
+```
+Use direct tools instead:
+- Glob to find files
+- Grep to search content
+- Read to examine files
+- find-docs only if current technical docs are necessary
+- exa-search only if broader online research is necessary
+```
+
+**NEVER launch sub-agents in economy mode.**
+
+---
+
+### Override 2: Direct Tool Usage Pattern
+
+Instead of launching exploration agents, use this pattern:
+
+```
+1. Glob to find relevant files:
+   - Glob: "**/*auth*" or "**/*{keyword}*"
+   - Glob: "src/**/*.ts" for specific areas
+
+2. Grep to find specific code:
+   - Grep: "function login" or "class Auth"
+   - Grep: pattern in specific directory
+
+3. Read to examine found files:
+   - Read the most relevant 3-5 files
+   - Focus on files matching the task
+
+4. Online research ONLY if:
+   - Library documentation needed
+   - Unknown API or pattern
+   - Limit to 1-2 searches max
+   - Use /Users/melvynx/.agents/skills/find-docs/SKILL.md for technical docs
+   - Use /Users/melvynx/.agents/skills/exa-search/SKILL.md for broader web research
+```
+
+---
+
+### Override 3: Reduced Exploration Scope
+
+**DEFAULT:** Explore comprehensively, find all related code
+**ECONOMY:** Focus on most likely locations only
+
+```
+Economy exploration strategy:
+1. Start with obvious paths (src/auth/, src/api/, etc.)
+2. Search for exact keywords from task
+3. Read only files directly related to task
+4. Skip "nice to have" context
+5. Stop exploring when you have enough to proceed
+```
+
+---
+
+### Override 4: Skip Optional Steps
+
+**In economy mode, skip or minimize:**
+- Extensive documentation research (use existing knowledge)
+- Web searches for common patterns (use best practices you know)
+- Multiple rounds of exploration (one round is enough)
+- Deep pattern analysis (quick scan is sufficient)
+
+**Always do:**
+- Find the files to modify
+- Understand existing patterns (quick read)
+- Identify dependencies
+- Create the plan
+
+---
+
+### Override 5: Leaner Validation
+
+**DEFAULT:** Launch code-reviewer agent for adversarial review
+**ECONOMY:** Self-review without subagent
+
+```
+Economy validation:
+1. Run typecheck and lint (required)
+2. Run affected tests (required)
+3. Quick self-review checklist:
+   - [ ] No obvious bugs
+   - [ ] Follows existing patterns
+   - [ ] Error handling present
+   - [ ] No security issues
+4. Skip adversarial review agent
+```
+
+---
+
+### Override 6: Test Mode Adjustments
+
+**If both `{economy_mode}` and `{test_mode}` are true:**
+
+```
+Economy test strategy:
+1. Analyze tests with Glob + Grep (not explore-codebase agent)
+2. Read 1-2 similar test files for patterns
+3. Create essential tests only:
+   - 1 happy path test
+   - 1 error case test
+   - Skip edge cases unless critical
+4. Run tests directly (no agent)
+```
+
+</override_rules>
+
+---
+
+<step_specific_overrides>
+
+## Step-by-Step Economy Overrides
+
+### Step 01: Analyze (Economy)
+```
+INSTEAD OF: 3 parallel exploration agents
+DO:
+1. Glob "**/*{keyword}*" for task-related files
+2. Grep for specific patterns in src/
+3. Read top 3-5 most relevant files
+4. Skip online research unless stuck. If needed, use find-docs for technical docs and exa-search for broader web research.
+```
+
+### Step 02: Plan (Economy)
+```
+Same as default - planning doesn't use agents
+```
+
+### Step 03: Execute (Economy)
+```
+Same as default - execution doesn't use agents
+```
+
+### Step 04: Validate (Economy)
+```
+INSTEAD OF: Comprehensive validation
+DO:
+1. Run typecheck + lint
+2. Run only affected tests
+3. Quick manual review
+4. Skip coverage analysis
+```
+
+### Step 05: Examine (Economy)
+```
+INSTEAD OF: code-reviewer agent
+DO:
+1. Self-review with checklist:
+   - Security: no injection, no secrets
+   - Logic: handles errors, edge cases
+   - Quality: follows patterns, readable
+2. Note any concerns
+3. Move to resolve if issues found
+```
+
+### Step 07: Tests (Economy)
+```
+INSTEAD OF: Deep test analysis with agents
+DO:
+1. Glob for existing test files
+2. Read 1 similar test file
+3. Create minimal test coverage
+4. Focus on critical paths only
+```
+
+### Step 08: Run Tests (Economy)
+```
+Same as default - test running doesn't use agents
+```
+
+</step_specific_overrides>
+
+---
+
+<economy_indicator>
+**When economy mode is active, start each step with:**
+
+```
+⚡ ECONOMY MODE - Using direct tools, no subagents
+```
+
+This reminds both Claude and the user that economy mode is active.
+</economy_indicator>
+
+---
+
+<success_metrics>
+Economy mode is successful when:
+- No sub-agent launches
+- Direct Glob/Grep/Read usage instead
+- Fewer than 3 WebSearch calls total
+- Implementation still correct and working
+- Tests pass (if test_mode enabled)
+</success_metrics>