aiblueprint-cli 1.4.23 → 1.4.25

package/claude-code-config/skills/workflow-apex-free/steps/step-04-validate.md

@@ -0,0 +1,251 @@
+---
+name: step-04-validate
+description: Self-check - run tests, verify AC, audit implementation quality, complete workflow
+prev_step: steps/step-03-execute.md
+next_step: null
+---
+
+# Step 4: Validate (Self-Check)
+
+## MANDATORY EXECUTION RULES (READ FIRST):
+
+- 🛑 NEVER claim checks pass when they don't
+- 🛑 NEVER skip any validation step
+- ✅ ALWAYS run typecheck, lint, and tests
+- ✅ ALWAYS verify each acceptance criterion
+- ✅ ALWAYS fix failures before proceeding
+- 📋 YOU ARE A VALIDATOR, not an implementer
+- 💬 FOCUS on "Does it work correctly?"
+- 🚫 FORBIDDEN to proceed with failing checks
+
+## EXECUTION PROTOCOLS:
+
+- 🎯 Run all validation commands
+- 💾 Log results to output (if save_mode)
+- 📖 Check each AC against implementation
+- 🚫 FORBIDDEN to mark complete with failures
+
+## CONTEXT BOUNDARIES:
+
+- Implementation from step-03 is complete
+- Tests may or may not pass yet
+- Type errors may exist
+- Focus is on verification, not new implementation
+
+## YOUR TASK:
+
+Validate the implementation by running checks, verifying acceptance criteria, and ensuring quality.
+
+---
+
+<available_state>
+From previous steps:
+
+| Variable | Description |
+|----------|-------------|
+| `{task_description}` | What was implemented |
+| `{task_id}` | Kebab-case identifier |
+| `{acceptance_criteria}` | Success criteria |
+| `{auto_mode}` | Skip confirmations |
+| `{save_mode}` | Save outputs to files |
+| `{economy_mode}` | No subagents mode |
+| `{output_dir}` | Path to output (if save_mode) |
+| Implementation | Completed in step-03 |
+</available_state>
+
+---
+
+## EXECUTION SEQUENCE:
+
+### 1. Initialize Save Output (if save_mode)
+
+**If `{save_mode}` = true:**
+
+```bash
+bash {skill_dir}/scripts/update-progress.sh "{task_id}" "04" "validate" "in_progress"
+```
+
+Append results to `{output_dir}/04-validate.md` as you work.
+
+### 2. Discover Available Commands
+
+Check `package.json` for exact command names:
+```bash
+cat package.json | grep -A 20 '"scripts"'
+```
+
+Look for: `typecheck`, `lint`, `test`, `build`, `format`
+
+### 3. Run Validation Suite
+
+**3.1 Typecheck**
+```bash
+pnpm run typecheck  # or npm run typecheck
+```
+
+**MUST PASS.** If fails:
+1. Read error messages
+2. Fix type issues
+3. Re-run until passing
+
+**3.2 Lint**
+```bash
+pnpm run lint
+```
+
+**MUST PASS.** If fails:
+1. Try auto-fix: `pnpm run lint --fix`
+2. Manually fix remaining
+3. Re-run until passing
+
+**3.3 Tests**
+```bash
+pnpm run test -- --filter={affected-area}
+```
+
+**MUST PASS.** If fails:
+1. Identify failing test
+2. Determine if code bug or test bug
+3. Fix the root cause
+4. Re-run until passing
+
+**If `{save_mode}` = true:** Log each result
+
+### 4. Self-Audit Checklist
+
+Verify each item:
+
+**Tasks Complete:**
+- [ ] All todos from step-03 marked complete
+- [ ] No tasks skipped without reason
+- [ ] Any blocked tasks have explanation
+
+**Tests Passing:**
+- [ ] All existing tests pass
+- [ ] New tests written for new functionality
+- [ ] No skipped tests without reason
+
+**Acceptance Criteria:**
+- [ ] Each AC demonstrably met
+- [ ] Can explain how implementation satisfies AC
+- [ ] Edge cases considered
+
+**Patterns Followed:**
+- [ ] Code follows existing patterns
+- [ ] Error handling consistent
+- [ ] Naming conventions match
+
+### 5. Format Code
+
+If format command available:
+```bash
+pnpm run format
+```
+
+### 6. Final Verification
+
+Re-run all checks:
+```bash
+pnpm run typecheck && pnpm run lint
+```
+
+Both MUST pass.
+
+### 7. Present Validation Results
+
+```
+**Validation Complete**
+
+**Typecheck:** ✓ Passed
+**Lint:** ✓ Passed
+**Tests:** ✓ {X}/{X} passing
+**Format:** ✓ Applied
+
+**Acceptance Criteria:**
+- [✓] AC1: Verified by [how]
+- [✓] AC2: Verified by [how]
+
+**Files Modified:** {list}
+
+**Summary:** All checks passing, ready for next step.
+```
+
+### 8. Complete Workflow
+
+**Show final summary:**
+
+```
+✅ APEX Workflow Complete
+
+**Task:** {task_description}
+**Task ID:** {task_id}
+
+**Validation Results:**
+- Typecheck: ✓ Passed
+- Lint: ✓ Passed
+- Tests: ✓ Passed
+
+**Acceptance Criteria:**
+- [✓] AC1: Verified
+- [✓] AC2: Verified
+
+**Files Modified:** {list}
+
+🎉 Implementation complete and validated!
+```
+
+### 9. Complete Save Output (if save_mode)
+
+**If `{save_mode}` = true:**
+
+Append to `{output_dir}/04-validate.md`:
+```markdown
+---
+## Step Complete
+**Status:** ✓ Complete
+**Typecheck:** ✓
+**Lint:** ✓
+**Tests:** ✓
+**Workflow:** Complete
+**Timestamp:** {ISO timestamp}
+```
+
+Run: `bash {skill_dir}/scripts/update-progress.sh "{task_id}" "04" "validate" "complete"`
+
+---
+
+## SUCCESS METRICS:
+
+✅ Typecheck passes
+✅ Lint passes
+✅ All tests pass
+✅ All AC verified
+✅ Code formatted
+✅ User informed of status
+✅ Workflow completed
+
+## FAILURE MODES:
+
+❌ Claiming checks pass when they don't
+❌ Not running all validation commands
+❌ Skipping tests for modified code
+❌ Missing AC verification
+❌ Proceeding with failures
+
+## VALIDATION PROTOCOLS:
+
+- Run EVERY validation command
+- Fix failures IMMEDIATELY
+- Don't proceed until all green
+- Verify EACH acceptance criterion
+- Document all results
+
+---
+
+## WORKFLOW COMPLETE
+
+This is the final step. After validation passes, the APEX workflow is complete.
+
+<critical>
+Remember: NEVER claim completion with failing checks - fix everything first!
+</critical>

package/claude-code-config/skills/workflow-apex-free/templates/00-context.md

@@ -0,0 +1,43 @@
+# APEX Task: {{task_id}}
+
+**Created:** {{timestamp}}
+**Task:** {{task_description}}
+
+---
+
+## Configuration
+
+| Flag | Value |
+|------|-------|
+| Auto mode (`-a`) | {{auto_mode}} |
+| Save mode (`-s`) | {{save_mode}} |
+| Economy mode (`-e`) | {{economy_mode}} |
+| Branch mode (`-b`) | {{branch_mode}} |
+| Interactive mode (`-i`) | {{interactive_mode}} |
+| Branch name | {{branch_name}} |
+
+---
+
+## User Request
+
+```
+{{original_input}}
+```
+
+---
+
+## Acceptance Criteria
+
+_To be defined in step-01-analyze.md_
+
+---
+
+## Progress
+
+| Step | Status | Timestamp |
+|------|--------|-----------|
+| 00-init | ⏸ Pending | |
+| 01-analyze | ⏸ Pending | |
+| 02-plan | ⏸ Pending | |
+| 03-execute | ⏸ Pending | |
+| 04-validate | ⏸ Pending | |

package/claude-code-config/skills/workflow-apex-free/templates/01-analyze.md

@@ -0,0 +1,10 @@
+# Step 01: Analyze
+
+**Task:** {{task_description}}
+**Started:** {{timestamp}}
+
+---
+
+## Context Discovery
+
+_Findings will be appended here as exploration progresses..._

package/claude-code-config/skills/workflow-apex-free/templates/02-plan.md

@@ -0,0 +1,10 @@
+# Step 02: Plan
+
+**Task:** {{task_description}}
+**Started:** {{timestamp}}
+
+---
+
+## Planning Progress
+
+_Implementation plan will be written here..._

package/claude-code-config/skills/workflow-apex-free/templates/03-execute.md

@@ -0,0 +1,10 @@
+# Step 03: Execute
+
+**Task:** {{task_description}}
+**Started:** {{timestamp}}
+
+---
+
+## Implementation Log
+
+_Changes will be logged here as implementation progresses..._

package/claude-code-config/skills/workflow-apex-free/templates/04-validate.md

@@ -0,0 +1,10 @@
+# Step 04: Validate
+
+**Task:** {{task_description}}
+**Started:** {{timestamp}}
+
+---
+
+## Validation Progress
+
+_Validation results will be appended here..._

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

@@ -0,0 +1,176 @@
+# 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 and workflow completion | Always (if save_mode) |
+| `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` |
+| `{{save_mode}}` | Save mode flag | `true` or `false` |
+| `{{economy_mode}}` | Economy mode flag | `true` or `false` |
+| `{{branch_mode}}` | Branch 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` |
+
+## Setup Script
+
+### `setup-templates.sh`
+
+Initializes all template files in the output directory with variables replaced.
+
+**Usage:**
+```bash
+bash scripts/setup-templates.sh \
+  "feature_name" \
+  "task_description" \
+  "auto_mode" \
+  "save_mode" \
+  "economy_mode" \
+  "branch_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
+```
+
+## 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 × 5 steps = ~1,000 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 × 5 steps = ~250 tokens
+
+**Total savings:** ~750 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-free/templates/step-complete.md

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