aiblueprint-cli 1.4.99 → 1.4.100

package/agents-config/skills/use-goal/references/verification-harnesses.md

@@ -1,7 +1,108 @@
 # Verification Harnesses For Refactors
 
-Use this reference when a Goal involves refactoring, deletion, migration, moving files, eliminating a pattern, or reducing a code smell.
+Use this reference when a Goal involves refactoring, deletion, migration, moving files, eliminating a pattern, or reducing a code smell. The core tactic is to create a small measurable harness before the main work, then make the Goal continue until the harness reaches the target.
 
-Convert the desired end state into a deterministic count, list, or command result. First establish the baseline before editing. Prefer existing repository tooling; otherwise create a narrow, deterministic checker that prints grouped findings and exits non-zero while work remains. Exclude generated, vendored, build, lockfile, snapshot, and binary content unless the task includes it.
+## Principle
 
-For deletion or migration Goals, verify both the old surface is gone and the new surface works: no imports, string references, routes, config entries, or tests should point at removed paths, and typecheck/build/test should pass. Rerun the harness after each change and report the delta.
+For broad changes, do not rely only on subjective review. Convert the desired end state into a number, list, or deterministic command result.
+
+Examples:
+
+- Remove all explicit TypeScript `any` -> count explicit `any` occurrences and require `0`.
+- Delete dead files -> scan imports/references and require no references to removed paths.
+- Move a module -> scan imports and require all imports use the new path.
+- Rename an API -> count old symbol references and require `0`, then run tests/typecheck.
+- Remove a dependency -> scan package manifests and lockfiles, then run install/typecheck/test.
+- Split a large file -> check file size or exported symbol boundaries, then run typecheck/test.
+
+The harness should make progress visible after every iteration.
+
+## Harness Rules
+
+1. First establish the baseline count or failure list before editing.
+2. Prefer existing repo tooling: tests, lint rules, typecheck, dependency analyzers, codemods, static analyzers.
+3. If no existing command measures the target, create a narrow validation script.
+4. Make the script deterministic and fast enough to run repeatedly.
+5. Exclude generated, vendored, build output, lockfiles, snapshots, and irrelevant binary assets unless the task explicitly includes them.
+6. Print actionable output: total count, grouped files, and the top remaining offenders.
+7. Exit with code `0` only when the target condition is met. Exit non-zero while work remains.
+8. Keep the harness scoped to the Goal. Remove temporary harnesses before completion unless they are useful project validation and the user or repo conventions support keeping them.
+
+## Goal Pattern
+
+Use this shape for count-based refactor Goals:
+
+```text
+<desired refactor>, verified by `<validation command>` returning success with <target count/list condition>, while preserving <tests/typecheck/public behavior>. First establish the baseline with `<validation command>` and inspect the highest-signal offenders. Work in checkpoints: after each batch, rerun `<validation command>`, record the count/list delta, run the narrowest relevant tests, and continue until the validation command exits 0. If the target cannot be reached safely, stop with the remaining offenders, attempted paths, failing output, and the decision needed.
+```
+
+Example:
+
+```text
+Remove all explicit TypeScript `any` from the codebase, verified by `node scripts/check-explicit-any.mjs` exiting 0 with count 0, while keeping `pnpm typecheck` and relevant tests green. First run the checker to record the baseline and prioritize files with the most occurrences. Work in checkpoints: after each batch, rerun the checker, record the remaining count, and run the narrowest relevant typecheck/tests. Continue until the checker exits 0. If some `any` cannot be removed safely, stop with the remaining locations, attempted replacements, compiler/test output, and the type information needed.
+```
+
+## Script Patterns
+
+Use structured parsers when reasonable. For TypeScript, prefer the TypeScript compiler API, `ts-morph`, ESLint, or an existing lint rule over raw text search when false positives matter.
+
+For a quick bootstrap harness, a text scanner is acceptable if the Goal explicitly treats it as an approximate first pass and follows up with typecheck/lint.
+
+Example quick scanner:
+
+```js
+#!/usr/bin/env node
+import { readdirSync, readFileSync, statSync } from "node:fs";
+import { join } from "node:path";
+
+const root = process.cwd();
+const ignoredDirs = new Set([".git", "node_modules", "dist", "build", ".next", "coverage"]);
+const extensions = new Set([".ts", ".tsx"]);
+const matches = [];
+
+function walk(dir) {
+  for (const entry of readdirSync(dir)) {
+    const path = join(dir, entry);
+    const stat = statSync(path);
+    if (stat.isDirectory()) {
+      if (!ignoredDirs.has(entry)) walk(path);
+      continue;
+    }
+    if (![...extensions].some((ext) => path.endsWith(ext))) continue;
+    const text = readFileSync(path, "utf8");
+    const lines = text.split("\n");
+    lines.forEach((line, index) => {
+      if (/\bany\b/.test(line)) matches.push(`${path.replace(`${root}/`, "")}:${index + 1}: ${line.trim()}`);
+    });
+  }
+}
+
+walk(root);
+
+console.log(`explicit_any_count=${matches.length}`);
+for (const match of matches.slice(0, 50)) console.log(match);
+if (matches.length > 50) console.log(`...and ${matches.length - 50} more`);
+process.exit(matches.length === 0 ? 0 : 1);
+```
+
+## Refactor Targets
+
+For deletion Goals, verify both absence and behavior:
+
+- target files or symbols are gone
+- no imports, string references, routes, config entries, docs links, or tests point to them
+- typecheck/build/test still passes
+
+For moving Goals, verify all call sites:
+
+- old import path count is `0`
+- new import path exists where expected
+- public exports remain compatible unless changing them is part of the Goal
+- typecheck/build/test still passes
+
+For migration Goals, verify old surface removal and new surface behavior:
+
+- old package/API/pattern count reaches `0` or the explicitly allowed exception list
+- new package/API/pattern is used consistently
+- tests/typecheck/build pass
+- manual or browser verification is included when behavior is visual or interactive

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "aiblueprint-cli",
-  "version": "1.4.99",
+  "version": "1.4.100",
   "description": "AIBlueprint CLI for setting up AI coding configurations",
   "author": "AIBlueprint",
   "license": "MIT",

package/agents-config/skills/apex/templates/00-context.md

@@ -1,55 +0,0 @@
-# APEX Task: {{task_id}}
-
-**Created:** {{timestamp}}
-**Task:** {{task_description}}
-
----
-
-## Configuration
-
-| Flag | Value |
-|------|-------|
-| Auto mode (`-a`) | {{auto_mode}} |
-| Examine mode (`-x`) | {{examine_mode}} |
-| Save mode (`-s`) | {{save_mode}} |
-| Test mode (`-t`) | {{test_mode}} |
-| Economy mode (`-e`) | {{economy_mode}} |
-| Branch mode (`-b`) | {{branch_mode}} |
-| PR mode (`-pr`) | {{pr_mode}} |
-| Interactive mode (`-i`) | {{interactive_mode}} |
-| Tasks mode (`-k`) | {{tasks_mode}} |
-| Verify mode (`-v`) | {{verify_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 | |
-| 02b-tasks | {{tasks_status}} | |
-| 03-execute | ⏸ Pending | |
-| 04-validate | ⏸ Pending | |
-| 05-examine | {{examine_status}} | |
-| 06-resolve | {{examine_status}} | |
-| 07-tests | {{test_status}} | |
-| 08-run-tests | {{test_status}} | |
-| 10-verify | {{verify_status}} | |
-| 09-finish | {{pr_status}} | |

package/agents-config/skills/apex/templates/01-analyze.md

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

package/agents-config/skills/apex/templates/02-plan.md

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

package/agents-config/skills/apex/templates/03-execute.md

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

package/agents-config/skills/apex/templates/04-validate.md

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

package/agents-config/skills/apex/templates/05-examine.md

@@ -1,10 +0,0 @@
-# Step 05: Examine
-
-**Task:** {{task_description}}
-**Started:** {{timestamp}}
-
----
-
-## Adversarial Review
-
-_Review findings will be documented here..._

package/agents-config/skills/apex/templates/06-resolve.md

@@ -1,10 +0,0 @@
-# Step 06: Resolve
-
-**Task:** {{task_description}}
-**Started:** {{timestamp}}
-
----
-
-## Resolution Log
-
-_Fixes will be logged here..._

package/agents-config/skills/apex/templates/07-tests.md

@@ -1,10 +0,0 @@
-# Step 07: Tests
-
-**Task:** {{task_description}}
-**Started:** {{timestamp}}
-
----
-
-## Test Analysis and Creation
-
-_Test strategy and implementation will be documented here..._

package/agents-config/skills/apex/templates/08-run-tests.md

@@ -1,10 +0,0 @@
-# Step 08: Run Tests
-
-**Task:** {{task_description}}
-**Started:** {{timestamp}}
-
----
-
-## Test Runner Log
-
-_Test execution results will be logged here..._

package/agents-config/skills/apex/templates/09-finish.md

@@ -1,10 +0,0 @@
-# Step 09: Finish
-
-**Task:** {{task_description}}
-**Started:** {{timestamp}}
-
----
-
-## Pull Request Creation
-
-_PR creation process will be logged here..._

package/agents-config/skills/apex/templates/10-verify.md

@@ -1,9 +0,0 @@
-# Step 10: Verify - {{task_id}}
-
-**Task:** {{task_description}}
-
----
-
-## Verification Results
-
-_Results will be appended during execution_

package/agents-config/skills/apex/templates/README.md

@@ -1,195 +0,0 @@
-# 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/agents-config/skills/apex/templates/step-complete.md

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