aiblueprint-cli 1.4.88 → 1.4.89

package/agents-config/skills/agents-manager/SKILL.md

@@ -1,5 +1,5 @@
 ---
-name: agents-managers
+name: agents-manager
 description: Expert guidance for creating, building, and using Claude Code agents and the Task tool. Use when working with agents, setting up agent configurations, understanding how agents work, or using the Task tool to launch specialized agents.
 ---
 
@@ -28,7 +28,7 @@ Agents enable delegation of complex tasks to specialized agents that operate aut
 ---
 name: code-reviewer
 description: Expert code reviewer. Use proactively after code changes to review for quality, security, and best practices.
-tools: Read, Grep, Glob, Bash
+tools: Read, Grep, Glob, Bash, Skill
 model: sonnet
 ---
 
@@ -87,6 +87,17 @@ Project-level agents override user-level when names conflict.
 </field>
 </configuration>
 
+<online_research_tools>
+When an agent may need online research, make the routing explicit in its prompt and grant the required tools.
+
+- Use default harness tools for local code, files, git, command output, and browser inspection first.
+- Use `/Users/melvynx/.agents/skills/find-docs/SKILL.md` before answering or coding against current libraries, frameworks, SDKs, CLIs, cloud services, APIs, or code examples.
+- Use `/Users/melvynx/.agents/skills/exa-search/SKILL.md` for broader online research, recent information, source discovery, similar pages, URL extraction, or cited web answers.
+- Prefer those skills over ad hoc web searches. Built-in `WebSearch` and `WebFetch` are fallback tools unless the task explicitly asks for them.
+- Add `Skill` to restricted tool lists when the agent should invoke these skills. Add `Bash` when the skill needs local CLIs such as `exa-cli` or `ctx7`.
+- Never include secrets, tokens, credentials, personal data, or proprietary code in external queries.
+</online_research_tools>
+
 <execution_model>
 <critical_constraint>
 **Agents are black boxes that cannot interact with users.**
@@ -179,7 +190,7 @@ Tailor instructions to the specific task domain. Don't create generic "helper" a
 </system_prompt_guidelines>
 
 <agent_xml_structure>
-Agent.md files are system prompts consumed only by Claude. Like skills, they should use pure XML structure for optimal parsing and token efficiency.
+Agent.md files are system prompts consumed only by Claude. Like skills and slash commands, they should use pure XML structure for optimal parsing and token efficiency.
 
 <recommended_tags>
 Common tags for agent structure:

package/agents-config/skills/agents-manager/references/writing-agent-prompts.md

@@ -1,7 +1,7 @@
 <key_insight>
 Agent prompts should be task-specific, not generic. They define a specialized role with clear focus areas, workflows, and constraints.
 
-**Critical**: Agent.md files use pure XML structure (no markdown headings). Like skills, this improves parsing and token efficiency.
+**Critical**: Agent.md files use pure XML structure (no markdown headings). Like skills and slash commands, this improves parsing and token efficiency.
 </key_insight>
 
 <xml_structure_rule>

package/agents-config/skills/apex/SKILL.md

@@ -1,61 +1,122 @@
 ---
 name: apex
-description: Structured implementation using the APEX method (Analyze → Plan → Execute → eXamine). Use when implementing a feature or fixing a bug that benefits from a clear, deliberate workflow instead of jumping straight to code.
-argument-hint: "[-x] <task-description>"
+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] [-v] [-b] [-pr] [-i] [-m] [-r <task-id>] <task description>"
 ---
 
-# APEX
-
-Implement `$ARGUMENTS` with a deliberate, four-phase workflow. Think before each phase.
-
-Add `-x` to the request for an extra adversarial review pass after validation.
-
-## A — Analyze
-
-Gather just enough context to act with confidence:
-
-- Use `Glob`/`Grep` to find the files and patterns you'll touch
-- Read the closest existing example and follow its conventions
-- Restate the task as 2-4 concrete acceptance criteria
-- Note open questions; ask only if a wrong assumption would be costly
-
-## P — Plan
-
-Write a short, file-by-file plan before editing:
-
-- List each file to create or change and what changes in it
-- Pick the simplest approach that satisfies the criteria
-- Order the steps so the code stays runnable along the way
-
-## E — Execute
-
-Implement the plan:
-
-- Match the surrounding code's naming, structure, and idioms
-- Stay strictly in scope — no "while I'm here" refactors
-- Comments only where intent is genuinely non-obvious
-- Run the formatter if the project has one
-
-## X — eXamine
-
-Validate, then optionally review:
-
-1. **Validate**: run `lint`, `typecheck`, and relevant tests. Fix only what you broke; re-run until clean.
-2. **Review** (only if `-x`): re-read the diff as a skeptic — check for bugs, security holes, missed edge cases, and overcomplication. Fix what you find.
-
-## Output
-
-```
-## APEX complete
-
-**Task:** {what was implemented}
-**Criteria:** {✓ per acceptance criterion}
-**Files changed:** {list}
-**Validation:** ✓ lint ✓ typecheck ✓ tests
+<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 -v implement user dashboard          # With feature verification
+/apex -a -m implement full auth system        # Agent Teams (parallel)
+/apex -a -x -s -t -v add auth middleware      # Full workflow with tests + verify
+/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
 ```
 
-## Rules
-
-- One step at a time — finish each phase before the next
-- Stay in scope; ship the smallest change that meets the criteria
-- If blocked after 2 attempts, report the blocker and stop
+</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 |
+| `-v` | `-V` | `--verify` | Launch app and verify feature works |
+| `-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) - Security + Logic + Clean Code + Thermo-Nuclear maintainability audit in parallel
+9. **Resolve** → Fix findings (if examine found issues)
+10. **Verify** → Launch app, test feature (if -v)
+11. **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 |
+| 10 | `steps/step-10-verify.md` | Launch & verify feature |
+
+</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 |
+| `{verify_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)
+- **Use online research intentionally**: default harness tools for local code first, `/Users/melvynx/.agents/skills/find-docs/SKILL.md` for current technical docs, and `/Users/melvynx/.agents/skills/exa-search/SKILL.md` for broader web research or cited sources
+</execution_rules>
+
+<entry_point>
+**FIRST ACTION:** Load `steps/step-00-init.md`
+</entry_point>

package/agents-config/skills/apex/scripts/setup-templates.sh

@@ -0,0 +1,154 @@
+#!/bin/bash
+# APEX Template Setup Script
+# Creates output directory structure and initializes template files
+#
+# Usage: setup-templates.sh "feature-name" [other args...]
+# The script auto-generates the task ID with the next available number.
+
+set -e
+
+# Arguments - first arg is now just the feature name (kebab-case)
+FEATURE_NAME="$1"
+TASK_DESCRIPTION="$2"
+AUTO_MODE="${3:-false}"
+EXAMINE_MODE="${4:-false}"
+SAVE_MODE="${5:-false}"
+TEST_MODE="${6:-false}"
+ECONOMY_MODE="${7:-false}"
+BRANCH_MODE="${8:-false}"
+PR_MODE="${9:-false}"
+INTERACTIVE_MODE="${10:-false}"
+TASKS_MODE="${11:-false}"
+VERIFY_MODE="${12:-false}"
+BRANCH_NAME="${13:-}"
+ORIGINAL_INPUT="${14:-}"
+
+# Validate required arguments
+if [[ -z "$FEATURE_NAME" ]]; then
+    echo "Error: FEATURE_NAME is required"
+    exit 1
+fi
+
+if [[ -z "$TASK_DESCRIPTION" ]]; then
+    echo "Error: TASK_DESCRIPTION is required"
+    exit 1
+fi
+
+# Get current timestamp
+TIMESTAMP=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
+
+# Use current working directory as project root
+PROJECT_ROOT=$(pwd)
+APEX_OUTPUT_DIR="${PROJECT_ROOT}/.claude/output/apex"
+
+# Create apex output directory if it doesn't exist
+mkdir -p "$APEX_OUTPUT_DIR"
+
+# Find the next available number
+NEXT_NUM=1
+if [[ -d "$APEX_OUTPUT_DIR" ]]; then
+    # Find highest existing number prefix
+    HIGHEST=$(ls -1 "$APEX_OUTPUT_DIR" 2>/dev/null | grep -oE '^[0-9]+' | sort -n | tail -1)
+    if [[ -n "$HIGHEST" ]]; then
+        # Force base-10 interpretation (leading zeros would be treated as octal)
+        NEXT_NUM=$((10#$HIGHEST + 1))
+    fi
+fi
+
+# Format with leading zeros (2 digits)
+TASK_NUM=$(printf "%02d" "$NEXT_NUM")
+
+# Build full task ID
+TASK_ID="${TASK_NUM}-${FEATURE_NAME}"
+
+OUTPUT_DIR="${APEX_OUTPUT_DIR}/${TASK_ID}"
+
+# Get skill directory
+SKILL_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+TEMPLATE_DIR="${SKILL_DIR}/templates"
+
+# Create output directory
+mkdir -p "$OUTPUT_DIR"
+
+# Function to replace template variables
+render_template() {
+    local template_file="$1"
+    local output_file="$2"
+
+    # Determine status strings based on flags
+    local examine_status="⏭ Skip"
+    [[ "$EXAMINE_MODE" == "true" ]] && examine_status="⏸ Pending"
+
+    local test_status="⏭ Skip"
+    [[ "$TEST_MODE" == "true" ]] && test_status="⏸ Pending"
+
+    local pr_status="⏭ Skip"
+    [[ "$PR_MODE" == "true" ]] && pr_status="⏸ Pending"
+
+    local verify_status="⏭ Skip"
+    [[ "$VERIFY_MODE" == "true" ]] && verify_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" \
+        -e "s|{{timestamp}}|${TIMESTAMP}|g" \
+        -e "s|{{auto_mode}}|${AUTO_MODE}|g" \
+        -e "s|{{examine_mode}}|${EXAMINE_MODE}|g" \
+        -e "s|{{save_mode}}|${SAVE_MODE}|g" \
+        -e "s|{{test_mode}}|${TEST_MODE}|g" \
+        -e "s|{{economy_mode}}|${ECONOMY_MODE}|g" \
+        -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|{{verify_mode}}|${VERIFY_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|{{verify_status}}|${verify_status}|g" \
+        -e "s|{{pr_status}}|${pr_status}|g" \
+        "$template_file" > "$output_file"
+}
+
+# Initialize 00-context.md
+render_template "${TEMPLATE_DIR}/00-context.md" "${OUTPUT_DIR}/00-context.md"
+
+# Initialize other step files (only headers, content appended during execution)
+render_template "${TEMPLATE_DIR}/01-analyze.md" "${OUTPUT_DIR}/01-analyze.md"
+render_template "${TEMPLATE_DIR}/02-plan.md" "${OUTPUT_DIR}/02-plan.md"
+render_template "${TEMPLATE_DIR}/03-execute.md" "${OUTPUT_DIR}/03-execute.md"
+render_template "${TEMPLATE_DIR}/04-validate.md" "${OUTPUT_DIR}/04-validate.md"
+
+# Conditional templates
+if [[ "$EXAMINE_MODE" == "true" ]]; then
+    render_template "${TEMPLATE_DIR}/05-examine.md" "${OUTPUT_DIR}/05-examine.md"
+    render_template "${TEMPLATE_DIR}/06-resolve.md" "${OUTPUT_DIR}/06-resolve.md"
+fi
+
+if [[ "$TEST_MODE" == "true" ]]; then
+    render_template "${TEMPLATE_DIR}/07-tests.md" "${OUTPUT_DIR}/07-tests.md"
+    render_template "${TEMPLATE_DIR}/08-run-tests.md" "${OUTPUT_DIR}/08-run-tests.md"
+fi
+
+if [[ "$VERIFY_MODE" == "true" ]]; then
+    render_template "${TEMPLATE_DIR}/10-verify.md" "${OUTPUT_DIR}/10-verify.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
+
+# Output the generated task_id for capture by caller
+echo "TASK_ID=${TASK_ID}"
+echo "OUTPUT_DIR=${OUTPUT_DIR}"
+echo "✓ APEX templates initialized: ${OUTPUT_DIR}"
+exit 0

package/agents-config/skills/apex/scripts/update-progress.sh

@@ -0,0 +1,80 @@
+#!/bin/bash
+# APEX Progress Update Script
+# Updates 00-context.md progress table
+
+set -e
+
+# Arguments
+TASK_ID="$1"
+STEP_NUMBER="$2"
+STEP_NAME="$3"
+STATUS="$4"  # "in_progress" or "complete"
+
+# Validate required arguments
+if [[ -z "$TASK_ID" ]] || [[ -z "$STEP_NUMBER" ]] || [[ -z "$STEP_NAME" ]] || [[ -z "$STATUS" ]]; then
+    echo "Usage: $0 <task_id> <step_number> <step_name> <status>"
+    echo "Example: $0 01-add-auth 01 analyze complete"
+    exit 1
+fi
+
+# Find project root
+PROJECT_ROOT=$(git rev-parse --show-toplevel 2>/dev/null || pwd)
+CONTEXT_FILE="${PROJECT_ROOT}/.claude/output/apex/${TASK_ID}/00-context.md"
+
+# Validate context file exists
+if [[ ! -f "$CONTEXT_FILE" ]]; then
+    echo "Error: Context file not found: $CONTEXT_FILE"
+    exit 1
+fi
+
+# Get timestamp
+TIMESTAMP=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
+
+# Determine status symbol
+if [[ "$STATUS" == "in_progress" ]]; then
+    STATUS_SYMBOL="⏳ In Progress"
+elif [[ "$STATUS" == "complete" ]]; then
+    STATUS_SYMBOL="✓ Complete"
+else
+    echo "Error: Invalid status. Use 'in_progress' or 'complete'"
+    exit 1
+fi
+
+# Create temp file
+TEMP_FILE=$(mktemp)
+
+# Update the progress table
+awk -v step="${STEP_NUMBER}-${STEP_NAME}" \
+    -v status="$STATUS_SYMBOL" \
+    -v timestamp="$TIMESTAMP" '
+BEGIN { in_table = 0; found = 0 }
+{
+    # Detect progress table start
+    if ($0 ~ /^## Progress/) {
+        in_table = 1
+        print $0
+        next
+    }
+
+    # If in table and found the matching step
+    if (in_table && $0 ~ "\\| " step " \\|") {
+        printf "| %s | %s | %s |\n", step, status, timestamp
+        found = 1
+        next
+    }
+
+    # Print line as-is
+    print $0
+}
+END {
+    if (!found) {
+        print "Warning: Step not found in progress table" > "/dev/stderr"
+    }
+}
+' "$CONTEXT_FILE" > "$TEMP_FILE"
+
+# Replace original file
+mv "$TEMP_FILE" "$CONTEXT_FILE"
+
+echo "✓ Progress updated: ${STEP_NUMBER}-${STEP_NAME} → ${STATUS_SYMBOL}"
+exit 0