aiblueprint-cli 1.4.22 → 1.4.24

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

@@ -0,0 +1,303 @@
+---
+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] [-r <task-id>] <task description>"
+---
+
+<objective>
+Execute systematic implementation workflows using the APEX methodology. This skill uses progressive step loading to minimize context usage and supports saving outputs for review and resumption.
+</objective>
+
+<quick_start>
+**Basic usage:**
+
+```bash
+/apex add authentication middleware
+```
+
+**Recommended workflow (autonomous with save):**
+
+```bash
+/apex -a -s implement user registration
+```
+
+**With adversarial review:**
+
+```bash
+/apex -a -x -s fix login bug
+```
+
+**Flags:**
+
+- `-a` (auto): Skip confirmations
+- `-s` (save): Save outputs to `.claude/output/apex/`
+- `-x` (examine): Include adversarial code review
+- `-t` (test): Create and run tests
+- `-pr` (pull-request): Create PR at end
+
+See `<parameters>` for complete flag list.
+</quick_start>
+
+<parameters>
+
+<flags>
+**Enable flags (turn ON):**
+| Short | Long | Description |
+|-------|------|-------------|
+| `-a` | `--auto` | Autonomous mode: skip confirmations, auto-approve plans |
+| `-x` | `--examine` | Auto-examine mode: proceed to adversarial review |
+| `-s` | `--save` | Save mode: output each step to `.claude/output/apex/` |
+| `-t` | `--test` | Test mode: include test creation and runner steps |
+| `-e` | `--economy` | Economy mode: no subagents, save tokens (for limited plans) |
+| `-r` | `--resume` | Resume mode: continue from a previous task |
+| `-b` | `--branch` | Branch mode: verify not on main, create branch if needed |
+| `-pr` | `--pull-request` | PR mode: create pull request at end (enables -b) |
+| `-i` | `--interactive` | Interactive mode: configure flags via AskUserQuestion |
+
+**Disable flags (turn OFF):**
+| Short | Long | Description |
+|-------|------|-------------|
+| `-A` | `--no-auto` | Disable auto mode |
+| `-X` | `--no-examine` | Disable examine mode |
+| `-S` | `--no-save` | Disable save mode |
+| `-T` | `--no-test` | Disable test mode |
+| `-E` | `--no-economy` | Disable economy mode |
+| `-B` | `--no-branch` | Disable branch mode |
+| `-PR` | `--no-pull-request` | Disable PR mode |
+</flags>
+
+<examples>
+```bash
+# Basic
+/apex add auth middleware
+
+# Autonomous (skip confirmations)
+/apex -a add auth middleware
+
+# Save outputs + examine
+/apex -a -x -s add auth middleware
+
+# Full workflow with tests
+/apex -a -x -s -t add auth middleware
+
+# With PR creation
+/apex -a -pr add auth middleware
+
+# Resume previous task
+/apex -r 01-auth-middleware
+/apex -r 01  # Partial match
+
+# Economy mode (save tokens)
+/apex -e add auth middleware
+
+# Interactive flag config
+/apex -i add auth middleware
+
+# Disable flags (uppercase)
+/apex -A add auth middleware  # Disable auto
+```
+</examples>
+
+<parsing_rules>
+**Flag parsing:**
+
+1. Defaults loaded from `steps/step-00-init.md` `<defaults>` section
+2. Command-line flags override defaults (enable with lowercase `-x`, disable with uppercase `-X`)
+3. Flags removed from input, remainder becomes `{task_description}`
+4. Task ID generated as `NN-kebab-case-description`
+
+For detailed parsing algorithm, see `steps/step-00-init.md`.
+</parsing_rules>
+
+</parameters>
+
+<output_structure>
+**When `{save_mode}` = true:**
+
+All outputs saved to PROJECT directory (where Claude Code is running):
+```
+
+.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
+├── 05-examine.md # Review findings (if -x)
+├── 06-resolve.md # Resolution log (if -x)
+├── 07-tests.md # Test analysis and creation (if --test)
+├── 08-run-tests.md # Test runner log (if --test)
+└── 09-finish.md # Workflow finish and PR creation (if --pull-request)
+
+````
+
+**00-context.md structure:**
+```markdown
+# APEX Task: {task_id}
+
+**Created:** {timestamp}
+**Task:** {task_description}
+
+## Flags
+- Auto mode: {auto_mode}
+- Examine mode: {examine_mode}
+- Save mode: {save_mode}
+- Test mode: {test_mode}
+
+## User Request
+{original user input}
+
+## Acceptance Criteria
+- [ ] AC1: {inferred criterion}
+- [ ] AC2: {inferred criterion}
+````
+
+</output_structure>
+
+<resume_workflow>
+**Resume mode (`-r {task-id}`):**
+
+When provided, step-00 will:
+
+1. Locate the task folder in `.claude/output/apex/`
+2. Restore state from `00-context.md`
+3. Find the last completed step
+4. Continue from the next step
+
+Supports partial matching (e.g., `-r 01` finds `01-add-auth-middleware`).
+
+For implementation details, see `steps/step-00-init.md`.
+</resume_workflow>
+
+<workflow>
+**Standard flow:**
+1. Parse flags and task description
+2. If `-r`: Execute resume workflow
+3. If `-s`: Create output folder and 00-context.md
+4. Load step-01-analyze.md → gather context
+5. Load step-02-plan.md → create strategy
+6. Load step-03-execute.md → implement
+7. Load step-04-validate.md → verify
+8. If `--test`: Load step-07-tests.md → analyze and create tests
+9. If `--test`: Load step-08-run-tests.md → run until green
+10. If `-x` or user requests: Load step-05-examine.md → adversarial review
+11. If findings: Load step-06-resolve.md → fix findings
+12. If `-pr`: Load step-09-finish.md → create pull request
+</workflow>
+
+<state_variables>
+**Persist throughout all steps:**
+
+| Variable                | Type    | Description                                            |
+| ----------------------- | ------- | ------------------------------------------------------ |
+| `{task_description}`    | string  | What to implement (flags removed)                      |
+| `{feature_name}`        | string  | Kebab-case name without number (e.g., `add-auth-middleware`) |
+| `{task_id}`             | string  | Full identifier with number (e.g., `01-add-auth-middleware`) |
+| `{acceptance_criteria}` | list    | Success criteria (inferred or explicit)                |
+| `{auto_mode}`           | boolean | Skip confirmations, use recommended options            |
+| `{examine_mode}`        | boolean | Auto-proceed to adversarial review                     |
+| `{save_mode}`           | boolean | Save outputs to .claude/output/apex/                   |
+| `{test_mode}`           | boolean | Include test steps (07-08)                             |
+| `{economy_mode}`        | boolean | No subagents, direct tool usage only                   |
+| `{branch_mode}`         | boolean | Verify not on main, create branch if needed            |
+| `{pr_mode}`             | boolean | Create pull request at end                             |
+| `{interactive_mode}`    | boolean | Configure flags interactively                          |
+| `{resume_task}`         | string  | Task ID to resume (if -r provided)                     |
+| `{output_dir}`          | string  | Full path to output directory                          |
+| `{branch_name}`         | string  | Created branch name (if branch_mode)                   |
+
+</state_variables>
+
+<entry_point>
+
+**FIRST ACTION:** Load `steps/step-00-init.md`
+
+Step 00 handles:
+
+- Flag parsing (-a, -x, -s, -r, --test)
+- Resume mode detection and task lookup
+- Output folder creation (if save_mode)
+- 00-context.md creation (if save_mode)
+- State variable initialization
+
+After initialization, step-00 loads step-01-analyze.md.
+
+</entry_point>
+
+<step_files>
+**Progressive loading - only load current step:**
+
+| Step | File                         | Purpose                                              |
+| ---- | ---------------------------- | ---------------------------------------------------- |
+| 00   | `steps/step-00-init.md`      | Parse flags, create output folder, initialize state  |
+| 01   | `steps/step-01-analyze.md`   | Smart context gathering with 1-10 parallel agents based on complexity |
+| 02   | `steps/step-02-plan.md`      | File-by-file implementation strategy                 |
+| 03   | `steps/step-03-execute.md`   | Todo-driven implementation                           |
+| 04   | `steps/step-04-validate.md`  | Self-check and validation                            |
+| 05   | `steps/step-05-examine.md`   | Adversarial code review (optional)                   |
+| 06   | `steps/step-06-resolve.md`   | Finding resolution (optional)                        |
+| 07   | `steps/step-07-tests.md`     | Test analysis and creation (if --test)               |
+| 08   | `steps/step-08-run-tests.md` | Test runner loop until green (if --test)             |
+| 09   | `steps/step-09-finish.md`    | Create pull request (if --pull-request)              |
+
+</step_files>
+
+<execution_rules>
+
+- **Load one step at a time** - Only load the current step file
+- **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 (append to step file)
+- **Use parallel agents** for independent exploration tasks
+
+## 🧠 Smart Agent Strategy in Analyze Phase
+
+The analyze phase (step-01) uses **adaptive agent launching** (unless economy_mode):
+
+**Available agents:**
+- `explore-codebase` - Find existing patterns, files, utilities
+- `explore-docs` - Research library docs (use when unfamiliar with API)
+- `websearch` - Find approaches, best practices, gotchas
+
+**Launch 1-10 agents based on task complexity:**
+
+| Complexity | Agents | When |
+|------------|--------|------|
+| Simple | 1-2 | Bug fix, small tweak |
+| Medium | 2-4 | New feature in familiar stack |
+| Complex | 4-7 | Unfamiliar libraries, integrations |
+| Major | 6-10 | Multiple systems, many unknowns |
+
+**BE SMART:** Analyze what you actually need before launching. Don't over-launch for simple tasks, don't under-launch for complex ones.
+
+</execution_rules>
+
+<save_output_pattern>
+**When `{save_mode}` = true:**
+
+Step-00 runs `scripts/setup-templates.sh` to initialize all output files from `templates/` directory.
+
+**Each step then:**
+
+1. Run `scripts/update-progress.sh {task_id} {step_num} {step_name} "in_progress"`
+2. Append findings/outputs to the pre-created step file
+3. Run `scripts/update-progress.sh {task_id} {step_num} {step_name} "complete"`
+
+**Template system benefits:**
+
+- Reduces token usage by ~75% (1,350 tokens saved per workflow)
+- Templates in `templates/` directory (not inline in steps)
+- Scripts handle progress tracking automatically
+- See `templates/README.md` for details
+
+</save_output_pattern>
+
+<success_criteria>
+
+- Each step loaded progressively
+- All validation checks passing
+- Outputs saved if `{save_mode}` enabled
+- Tests passing if `{test_mode}` enabled
+- Clear completion summary provided
+  </success_criteria>

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

@@ -0,0 +1,134 @@
+#!/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}"
+BRANCH_NAME="${11:-}"
+ORIGINAL_INPUT="${12:-}"
+
+# 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"
+
+    # 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|{{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|{{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 [[ "$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/claude-code-config/skills/workflow-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