aiblueprint-cli 1.4.23 → 1.4.25

package/claude-code-config/skills/workflow-apex/templates/README.md

@@ -0,0 +1,195 @@
+# APEX Template System
+
+## Overview
+
+This directory contains template files used to initialize APEX workflow outputs when save mode (`-s`) is enabled. This template system significantly reduces token usage by moving repetitive content out of step files.
+
+## Template Files
+
+| Template | Purpose | Created When |
+|----------|---------|--------------|
+| `00-context.md` | Workflow configuration and progress tracking | Always (if save_mode) |
+| `01-analyze.md` | Analysis findings | Always (if save_mode) |
+| `02-plan.md` | Implementation plan | Always (if save_mode) |
+| `03-execute.md` | Implementation log | Always (if save_mode) |
+| `04-validate.md` | Validation results | Always (if save_mode) |
+| `05-examine.md` | Adversarial review findings | Only if examine_mode enabled |
+| `06-resolve.md` | Finding resolution log | Only if examine_mode enabled |
+| `07-tests.md` | Test analysis and creation | Only if test_mode enabled |
+| `08-run-tests.md` | Test runner log | Only if test_mode enabled |
+| `09-finish.md` | PR creation log | Only if pr_mode enabled |
+| `step-complete.md` | Completion marker template | Referenced in steps |
+
+## Template Variables
+
+Templates use `{{variable}}` syntax for placeholders:
+
+| Variable | Description | Example |
+|----------|-------------|---------|
+| `{{task_id}}` | Kebab-case task identifier | `01-add-auth-middleware` |
+| `{{task_description}}` | Plain text task description | `add authentication middleware` |
+| `{{timestamp}}` | ISO 8601 timestamp | `2026-01-12T10:30:00Z` |
+| `{{auto_mode}}` | Auto mode flag | `true` or `false` |
+| `{{examine_mode}}` | Examine mode flag | `true` or `false` |
+| `{{save_mode}}` | Save mode flag | `true` or `false` |
+| `{{test_mode}}` | Test mode flag | `true` or `false` |
+| `{{economy_mode}}` | Economy mode flag | `true` or `false` |
+| `{{branch_mode}}` | Branch mode flag | `true` or `false` |
+| `{{pr_mode}}` | PR mode flag | `true` or `false` |
+| `{{interactive_mode}}` | Interactive mode flag | `true` or `false` |
+| `{{branch_name}}` | Git branch name | `feature/add-auth` |
+| `{{original_input}}` | Raw user input | `/apex -a -s add auth` |
+| `{{examine_status}}` | Progress status for examine steps | `⏸ Pending` or `⏭ Skip` |
+| `{{test_status}}` | Progress status for test steps | `⏸ Pending` or `⏭ Skip` |
+| `{{pr_status}}` | Progress status for PR step | `⏸ Pending` or `⏭ Skip` |
+
+## Setup Script
+
+### `setup-templates.sh`
+
+Initializes all template files in the output directory with variables replaced.
+
+**Usage:**
+```bash
+bash scripts/setup-templates.sh \
+  "task_id" \
+  "task_description" \
+  "auto_mode" \
+  "examine_mode" \
+  "save_mode" \
+  "test_mode" \
+  "economy_mode" \
+  "branch_mode" \
+  "pr_mode" \
+  "interactive_mode" \
+  "branch_name" \
+  "original_input"
+```
+
+**Output:**
+```
+.claude/output/apex/01-add-auth-middleware/
+├── 00-context.md      # Always created
+├── 01-analyze.md      # Always created
+├── 02-plan.md         # Always created
+├── 03-execute.md      # Always created
+├── 04-validate.md     # Always created
+├── 05-examine.md      # Only if examine_mode
+├── 06-resolve.md      # Only if examine_mode
+├── 07-tests.md        # Only if test_mode
+├── 08-run-tests.md    # Only if test_mode
+└── 09-finish.md       # Only if pr_mode
+```
+
+## Progress Update Script
+
+### `update-progress.sh`
+
+Updates the progress table in `00-context.md` without manual markdown editing.
+
+**Usage:**
+```bash
+bash scripts/update-progress.sh <task_id> <step_number> <step_name> <status>
+```
+
+**Examples:**
+```bash
+# Mark step 01 as in progress
+bash scripts/update-progress.sh "01-add-auth" "01" "analyze" "in_progress"
+
+# Mark step 01 as complete
+bash scripts/update-progress.sh "01-add-auth" "01" "analyze" "complete"
+
+# Mark step 02 as in progress
+bash scripts/update-progress.sh "01-add-auth" "02" "plan" "in_progress"
+```
+
+**Status Values:**
+- `in_progress` → `⏳ In Progress`
+- `complete` → `✓ Complete`
+
+## Token Savings
+
+### Before Optimization
+
+Each step file contained full template content inline:
+
+```markdown
+### 1. Initialize Save Output (if save_mode)
+
+**If `{save_mode}` = true:**
+
+Create `{output_dir}/01-analyze.md`:
+```markdown
+# Step 01: Analyze
+
+**Task:** {task_description}
+**Started:** {ISO timestamp}
+
+---
+
+## Context Discovery
+```
+
+Update `00-context.md` progress:
+```markdown
+| 01-analyze | ⏳ In Progress | {timestamp} |
+```
+```
+
+**Token cost per step:** ~200 tokens × 9 steps = ~1,800 tokens
+
+### After Optimization
+
+Step files now reference templates and scripts:
+
+```markdown
+### 1. Initialize Save Output (if save_mode)
+
+**If `{save_mode}` = true:**
+
+The file `{output_dir}/01-analyze.md` has already been created by the setup script.
+
+Update progress:
+```bash
+bash {skill_dir}/scripts/update-progress.sh "{task_id}" "01" "analyze" "in_progress"
+```
+
+Append your findings to `01-analyze.md` as you work.
+```
+
+**Token cost per step:** ~50 tokens × 9 steps = ~450 tokens
+
+**Total savings:** ~1,350 tokens per workflow execution (75% reduction)
+
+## How It Works
+
+1. **Initialization (step-00-init.md):**
+   - Runs `setup-templates.sh` once at workflow start
+   - Creates all template files with variables replaced
+   - Output directory is ready with pre-initialized files
+
+2. **Each Step:**
+   - Runs `update-progress.sh` to mark step as "in_progress"
+   - Appends findings/logs to the pre-created step file
+   - Runs `update-progress.sh` again to mark step as "complete"
+
+3. **Benefits:**
+   - AI doesn't need to hold template content in context
+   - Consistent formatting across all workflows
+   - Easy to update templates without editing step files
+   - Scripts handle the tedious markdown updates
+
+## Updating Templates
+
+To modify template content:
+
+1. Edit the template file in `templates/`
+2. Changes apply to all future workflows automatically
+3. No need to update step files
+
+## Maintenance
+
+- Templates are stateless (no workflow-specific logic)
+- Scripts are idempotent (safe to run multiple times)
+- Variables use `{{var}}` syntax to avoid conflicts with markdown

package/claude-code-config/skills/workflow-apex/templates/step-complete.md

@@ -0,0 +1,7 @@
+---
+
+## Step Complete
+
+**Status:** ✓ Complete
+**Next:** {{next_step}}
+**Timestamp:** {{timestamp}}

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

@@ -0,0 +1,261 @@
+---
+name: apex
+description: Systematic implementation using APEX methodology (Analyze-Plan-Execute-Validate) with parallel agents and self-validation. Use when implementing features, fixing bugs, or making code changes that benefit from structured workflow.
+argument-hint: "[-a] [-s] [-e] [-b] [-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
+```
+
+**Flags:**
+
+- `-a` (auto): Skip confirmations
+- `-s` (save): Save outputs to `.claude/output/apex/`
+- `-e` (economy): No subagents, save tokens
+
+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 |
+| `-s` | `--save` | Save mode: output each step to `.claude/output/apex/` |
+| `-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 |
+| `-i` | `--interactive` | Interactive mode: configure flags via AskUserQuestion |
+
+**Disable flags (turn OFF):**
+| Short | Long | Description |
+|-------|------|-------------|
+| `-A` | `--no-auto` | Disable auto mode |
+| `-S` | `--no-save` | Disable save mode |
+| `-E` | `--no-economy` | Disable economy mode |
+| `-B` | `--no-branch` | Disable branch mode |
+</flags>
+
+<examples>
+```bash
+# Basic
+/apex add auth middleware
+
+# Autonomous (skip confirmations)
+/apex -a add auth middleware
+
+# Save outputs
+/apex -a -s 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
+```
+
+**00-context.md structure:**
+```markdown
+# APEX Task: {task_id}
+
+**Created:** {timestamp}
+**Task:** {task_description}
+
+## Flags
+- Auto mode: {auto_mode}
+- Save mode: {save_mode}
+- Economy mode: {economy_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 and complete
+</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            |
+| `{save_mode}`           | boolean | Save outputs to .claude/output/apex/                   |
+| `{economy_mode}`        | boolean | No subagents, direct tool usage only                   |
+| `{branch_mode}`         | boolean | Verify not on main, create branch if needed            |
+| `{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, validation, and workflow completion      |
+
+</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
+- Clear completion summary provided
+</success_criteria>

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

@@ -0,0 +1,100 @@
+#!/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}"
+SAVE_MODE="${4:-false}"
+ECONOMY_MODE="${5:-false}"
+BRANCH_MODE="${6:-false}"
+INTERACTIVE_MODE="${7:-false}"
+BRANCH_NAME="${8:-}"
+ORIGINAL_INPUT="${9:-}"
+
+# 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"
+
+    # 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|{{save_mode}}|${SAVE_MODE}|g" \
+        -e "s|{{economy_mode}}|${ECONOMY_MODE}|g" \
+        -e "s|{{branch_mode}}|${BRANCH_MODE}|g" \
+        -e "s|{{interactive_mode}}|${INTERACTIVE_MODE}|g" \
+        -e "s|{{branch_name}}|${BRANCH_NAME}|g" \
+        -e "s|{{original_input}}|${ORIGINAL_INPUT}|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"
+
+# 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-free/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