workspace-maxxing 0.1.0

package/docs/superpowers/specs/2026-04-07-autonomous-iteration-design.md

@@ -0,0 +1,214 @@
+# Workspace-Maxxing Design Spec — Sub-Project 3: Autonomous Iteration & Validation
+
+> **Phase 3 of 4:** Autonomous iteration engine + sub-agent orchestration. Phase 4 adds benchmarking and multi-agent support.
+
+## Context
+
+Sub-Project 1 delivered the npx CLI with skill installation. Sub-Project 2 added helper scripts (scaffold, validate, install-tool) for programmatic workspace creation. Sub-Project 3 adds autonomous iteration — the agent self-tests, self-evaluates, and improves the workspace without human involvement, escalating only when stuck.
+
+## Architecture
+
+### Data Flow
+
+```
+Agent scaffolds workspace → runs iterate.ts
+  │
+  ├─ Pass 1: Validate-Fix Loop
+  │   ├─ Run validate.ts
+  │   ├─ If failures → fix specific issues → re-validate
+  │   └─ Repeat until pass OR max retries (3) → escalate to human
+  │
+  ├─ Pass 2: Score-Driven Content Quality
+  │   ├─ Score workspace (structure + content quality, 0-100)
+  │   ├─ Identify lowest-scoring areas
+  │   └─ Agent improves content, re-scores until plateau
+  │
+  ├─ Pass 3: Completeness Checklist
+  │   ├─ Check: every stage has inputs/outputs/dependencies
+  │   ├─ Check: routing table references all folders
+  │   └─ Agent fills gaps
+  │
+  └─ Sub-Agent Testing (agent-orchestrated via SKILL.md)
+      ├─ Agent runs generate-tests.ts to create test cases
+      ├─ Agent spawns sub-agents: half generate, half evaluate
+      ├─ Results aggregated → agent reviews
+      └─ If confidence low → escalate to human
+```
+
+### Components
+
+#### 1. Iterate Script (`scripts/iterate.ts`)
+
+Orchestrates the 3-pass improvement loop.
+
+**CLI Interface:**
+```bash
+node scripts/iterate.ts --workspace ./workspace --max-retries 3
+```
+
+**Pass 1: Validate-Fix Loop**
+- Runs `validate.ts` programmatically (imports the module, not shell)
+- If failures exist, returns structured error details to the agent
+- Retries up to `--max-retries` times (default 3)
+- If still failing after max retries, returns `{ escalate: true }` with failure details
+- The agent reads the output and attempts fixes between retries
+
+**Pass 2: Score-Driven Content Quality**
+- Scores workspace on a 0-100 scale using these criteria:
+  - SYSTEM.md quality (has role, folder map, rules) — 20 points
+  - CONTEXT.md quality (has routing table, references all stages) — 20 points
+  - Each stage CONTEXT.md has purpose, inputs, outputs, dependencies — 15 points per stage (capped at 45 total for 3 stages)
+  - tools.md exists and has content — 15 points
+- Identifies lowest-scoring areas and reports them
+- Agent improves content between score runs
+
+**Pass 3: Completeness Checklist**
+- Fixed checklist of structural requirements:
+  - Every stage has inputs defined
+  - Every stage has outputs defined
+  - Every stage has dependencies defined
+  - Routing table references all numbered folders
+  - README.md exists and has usage instructions
+- Reports pass/fail per item
+
+**Output:** JSON to stdout with structured results:
+```json
+{
+  "passes": {
+    "validate": { "status": "passed", "retries": 1 },
+    "score": { "score": 78, "improvements": ["01-input missing dependencies"] },
+    "checklist": { "items": 5, "passed": 5, "failed": 0 }
+  },
+  "escalate": false
+}
+```
+
+**Dependencies:** Node.js builtins only (`fs`, `path`, `process`). Imports `validateWorkspace` from `validate.ts` directly.
+
+#### 2. Generate Tests Script (`scripts/generate-tests.ts`)
+
+Generates test cases for workspace evaluation.
+
+**CLI Interface:**
+```bash
+node scripts/generate-tests.ts --workspace ./workspace --output ./tests.json
+```
+
+**What it generates:**
+- For each numbered stage folder: 2-3 test cases
+- Test case types: `sample` (normal input), `edge-case` (boundary conditions), `empty` (missing input)
+- Each test case includes: stage name, type, sample input, expected output description
+
+**Output:** JSON file at `--output` path:
+```json
+{
+  "workspace": "research",
+  "testCases": [
+    {
+      "stage": "01-input",
+      "type": "sample",
+      "input": "A research question about climate change",
+      "expected": "Stage should collect and validate the research question"
+    },
+    {
+      "stage": "01-input",
+      "type": "edge-case",
+      "input": "",
+      "expected": "Stage should handle empty input gracefully"
+    }
+  ]
+}
+```
+
+**Dependencies:** Node.js builtins only
+
+#### 3. Enhanced SKILL.md
+
+Updated to include "## Autonomous Iteration" section with:
+- Instructions for running `iterate.ts` and interpreting results
+- How to fix validation failures between retries
+- How to improve scores between scoring runs
+- How to fill checklist gaps
+- Sub-agent spawning instructions:
+  - Run `generate-tests.ts` to create test cases
+  - Split test cases: half for generation sub-agents, half for evaluation sub-agents
+  - Generation sub-agents: create sample content for assigned test cases
+  - Evaluation sub-agents: review workspace against assigned test cases
+  - Aggregate results, assess confidence
+- Escalation criteria: present failures to human with proposed fix
+
+### File Structure
+
+```
+workspace-maxxing/
+├── src/
+│   ├── scripts/
+│   │   ├── iterate.ts          — Orchestration script source
+│   │   └── generate-tests.ts   — Test case generator source
+│   ├── index.ts                — Unchanged
+│   └── install.ts              — Modified: also copies new scripts
+├── templates/
+│   ├── SKILL.md                — Enhanced with autonomous iteration
+│   └── .workspace-templates/
+│       └── scripts/
+│           ├── iterate.ts      — Copy for distribution
+│           └── generate-tests.ts — Copy for distribution
+├── tests/
+│   ├── iterate.test.ts
+│   └── generate-tests.test.ts
+```
+
+### Changes to Existing Files
+
+**`src/install.ts`:** Add `iterate.ts` and `generate-tests.ts` to the scripts copy list.
+
+**`templates/SKILL.md`:** Add "## Autonomous Iteration" section with full instructions.
+
+### Error Handling
+
+- **iterate.ts:** Never crashes with unhandled exception. If validate fails after max retries, returns `{ escalate: true }` with structured failure details. Score and checklist passes are best-effort — they log warnings but don't block the process.
+- **generate-tests.ts:** If workspace has no numbered stage folders, returns empty test cases array with a warning message. Never throws.
+- **Escalation:** When `iterate.ts` returns `escalate: true`, SKILL.md instructs the agent to present the specific failures to the human with a proposed fix, rather than silently continuing.
+
+### Testing Strategy
+
+- **iterate.test.ts:**
+  - Mock `validateWorkspace` to return failures → verify retry logic
+  - Mock `validateWorkspace` to pass immediately → verify single pass, no retries
+  - Mock `validateWorkspace` to always fail → verify escalation after max retries
+  - Verify scoring function returns correct scores for known workspaces
+  - Verify checklist function reports correct pass/fail
+
+- **generate-tests.test.ts:**
+  - Create workspace with 3 stages → verify 6-9 test cases generated (2-3 per stage)
+  - Create workspace with no stages → verify empty test cases with warning
+  - Verify test case structure (stage, type, input, expected)
+  - Verify output file is valid JSON
+
+- **Integration:**
+  - Scaffold workspace → run iterate → verify score improves
+  - Scaffold workspace → run generate-tests → verify valid JSON output
+
+### Scope
+
+**In Scope (This Phase):**
+- `iterate.ts` with 3-pass loop (validate-fix, score, checklist)
+- `generate-tests.ts` for test case generation
+- Enhanced SKILL.md with autonomous iteration instructions
+- Tests for both scripts
+- Installer updated to copy new scripts
+
+**Out of Scope (Future Phases):**
+- Benchmark scoring system (Phase 4) — this is workspace quality scoring, not benchmark
+- Multi-agent CLI flags (--claude, --copilot, --gemini) (Phase 4)
+- External sub-agent API integration (sub-agents are spawned via agent's native tool use)
+- Hill-climbing algorithm automation (Phase 3 was scoped as agent-driven, not script-driven)
+
+### Success Criteria
+
+1. `node scripts/iterate.ts` runs 3-pass loop and returns structured results
+2. `node scripts/generate-tests.ts` generates test cases for all stages
+3. Enhanced SKILL.md documents autonomous iteration workflow
+4. Installer copies new scripts to skill directory
+5. All tests pass (Phase 1 + Phase 2 + Phase 3)
+6. Human escalation triggers correctly when validation fails after max retries

package/docs/superpowers/specs/2026-04-07-autonomous-iteration-sub-agent-batches-design.md

@@ -0,0 +1,188 @@
+# Autonomous Iteration with Sub-Agent Batches — Design Spec
+
+## Problem
+
+The current iteration workflow is script-driven (`iterate.ts`) with sequential validate-fix-score loops. Sub-skills lack obra/superpowers patterns (no YAML frontmatter, trigger phrases, anti-rationalization tables, iron laws). The goal is a truly autonomous workflow where fresh-context sub-agents execute test cases in parallel batches, validated by a dedicated validator agent, with fix loops for failures.
+
+## Solution
+
+New `orchestrator.ts` script coordinates batched parallel worker sub-agents with validator checkpoints and fix loops. Three new sub-skills (`worker`, `fixer`, enhanced `validation`). All 7 existing sub-skills rewritten with obra/superpowers patterns. `dispatch.ts` extended for parallel invocation.
+
+## Architecture
+
+### Core Components
+
+```
+orchestrator.ts (new)
+├── Generates test cases via generate-tests.ts
+├── Splits into batches (configurable via --batch-size, default 3)
+├── Dispatches worker sub-agents in parallel per batch
+├── Collects outputs (file + JSON)
+├── Dispatches validator sub-agent on batch results
+└── If batch score < threshold → dispatches fixer sub-agents → re-validates → next batch
+```
+
+### New Sub-Skills
+
+| Sub-Skill | Purpose | Trigger |
+|-----------|---------|---------|
+| `worker` | Executes a single test case against the workspace, produces output | "run test case", "execute workspace task" |
+| `fixer` | Applies targeted fixes to failing test case outputs | "fix failing test", "improve output" |
+| `validation` (enhanced) | Benchmarks batch outputs, returns structured score | "validate batch", "check results" |
+
+### Extended Components
+
+| Component | Change |
+|-----------|--------|
+| `dispatch.ts` | Added `--parallel` flag + `--batch-id` for grouped invocation |
+| `SKILL.md` | New "Autonomous Iteration Workflow" section replacing old iterate.ts docs |
+| All 7 existing sub-skills | Rewritten with obra patterns (YAML frontmatter, trigger phrases, anti-rationalization tables, iron laws) |
+
+### Output Structure
+
+```
+.agents/iteration/
+├── batch-01/
+│   ├── tc-001/
+│   │   ├── output.md          (worker output, human-readable)
+│   │   ├── report.json        (structured JSON for validation)
+│   │   └── fix-output.md      (fixer output if needed)
+│   ├── tc-002/
+│   └── batch-report.json      (validator benchmark results)
+├── batch-02/
+└── summary.json               (final aggregated results)
+```
+
+## Data Flow & Batch Lifecycle
+
+### Full Flow
+
+```
+1. GENERATE
+   orchestrator.ts → generate-tests.ts → tests.json
+
+2. BATCH SPLIT
+   tests.json → batches of N (default 3)
+
+3. WORKER DISPATCH (parallel per batch)
+   For each test case in batch:
+     dispatch.ts --skill worker --test-case <id> --batch <N> --workspace <path>
+     → reads workspace CONTEXT.md + test case
+     → executes task, writes output.md + report.json
+
+4. VALIDATOR DISPATCH
+   dispatch.ts --skill validation --batch <N> --workspace <path>
+   → reads all report.json files in batch directory
+   → runs benchmark scoring
+   → writes batch-report.json
+
+5. FIX LOOP (if batch score < threshold)
+   For each failing test case:
+     dispatch.ts --skill fixer --test-case <id> --batch <N> --workspace <path>
+     → reads validator findings + original output
+     → applies fixes, overwrites output.md + report.json
+   → re-run validator
+   → repeat until passing or max retries (default 3)
+
+6. NEXT BATCH or COMPLETE
+   If all batches done → write summary.json
+   If any batch escalated → report to human
+```
+
+### Key Interfaces
+
+- **Worker input:** test case JSON + workspace path + batch ID
+- **Worker output:** `output.md` (human-readable), `report.json` (structured: `{testCaseId, status, output, findings}`)
+- **Validator input:** batch directory path + workspace path
+- **Validator output:** `batch-report.json` (per-test scores, overall batch score, findings, fix suggestions)
+- **Fixer input:** validator findings + original output path
+- **Fixer output:** updated `output.md` + `report.json`
+
+### Concurrency Model
+
+- Workers within a batch run in parallel (via `dispatch.ts --parallel`)
+- Batches run sequentially (validator must complete before next batch starts)
+- Fix loop runs sequentially per batch (fixers parallel within a batch)
+
+## Sub-Skill Design Pattern
+
+All sub-skills follow this structure:
+
+```yaml
+---
+name: <skill-name>
+description: "<trigger-friendly description>"
+triggers: ["<phrase1>", "<phrase2>"]
+---
+```
+
+Then:
+- **Overview** — one paragraph
+- **When to Use / When Not to Use** — clear boundaries
+- **The Iron Law** — 3-4 non-negotiable rules
+- **The Process** — numbered steps
+- **Anti-Rationalization Table** — common excuses vs reality
+- **Sub-Skill Dispatch** (if applicable) — what to dispatch next
+- **Report Format** — structured JSON schema
+
+### New Sub-Skills Specifics
+
+**`worker` SKILL.md:**
+- Focus: read test case, load relevant workspace sections, execute task, produce output
+- Iron Law: NO SKIPPING TEST CASE STEPS, NO MODIFYING WORKSPACE STRUCTURE, NO CLAIMING DONE WITHOUT OUTPUT
+- Dispatches to: `validation` after output complete
+
+**`fixer` SKILL.md:**
+- Focus: read validator findings, identify root cause, apply minimal fix, re-validate
+- Iron Law: NO BLIND RETRIES, NO COSMETIC FIXES, NO FIXING WHAT ISN'T BROKEN
+- Dispatches to: `validation` after fix applied
+
+**`validation` (enhanced) SKILL.md:**
+- Focus: batch-level benchmark scoring, per-test findings, fix suggestions
+- Iron Law: NO SCORE INFLATION, NO SKIPPING FAILURES, NO VALIDATING WITHOUT BENCHMARK
+- Dispatches to: `fixer` if score < threshold, `orchestrator` if passing
+
+## dispatch.ts Changes
+
+- `--parallel` flag: spawns multiple sub-agent invocations concurrently
+- `--batch-id` flag: tags outputs to batch directory
+- Returns aggregated JSON when `--parallel` is used
+
+## File Changes
+
+### New Files
+- `src/scripts/orchestrator.ts` — Batch orchestrator
+- `templates/.workspace-templates/skills/worker/SKILL.md` — Worker sub-skill
+- `templates/.workspace-templates/skills/fixer/SKILL.md` — Fixer sub-skill
+
+### Modified Files
+- `src/scripts/dispatch.ts` — Parallel dispatch, batch ID support
+- `templates/SKILL.md` — New "Autonomous Iteration Workflow" section
+- `templates/.workspace-templates/skills/validation/SKILL.md` — Enhanced with batch validation
+- `templates/.workspace-templates/skills/iteration/SKILL.md` — Rewritten with obra patterns
+- `templates/.workspace-templates/skills/research/SKILL.md` — Rewritten with obra patterns
+- `templates/.workspace-templates/skills/architecture/SKILL.md` — Rewritten with obra patterns
+- `templates/.workspace-templates/skills/testing/SKILL.md` — Rewritten with obra patterns
+- `templates/.workspace-templates/skills/prompt-engineering/SKILL.md` — Rewritten with obra patterns
+- `templates/.workspace-templates/skills/tooling/SKILL.md` — Rewritten with obra patterns
+
+### New Test Files
+- `tests/orchestrator.test.ts`
+- `tests/dispatch-parallel.test.ts`
+- `tests/worker-skill.test.ts`
+- `tests/fixer-skill.test.ts`
+- `tests/validation-enhanced.test.ts`
+
+## Error Handling
+
+- **Worker timeout:** If a worker doesn't complete within timeout (default 300s), mark test case as failed, continue with batch
+- **Validator failure:** If validator can't parse outputs, escalate to human
+- **Fix loop exhaustion:** After max retries (default 3), mark batch as partially failed, continue to next batch
+- **Orchestrator crash:** Summary.json written at each batch boundary for recovery
+
+## Testing Strategy
+
+- **Unit tests:** orchestrator.ts batch splitting, dispatch.ts parallel invocation, report aggregation
+- **Integration tests:** full batch lifecycle (generate → dispatch → validate → fix → complete)
+- **Sub-skill tests:** each sub-skill's report format, trigger phrases, iron law compliance
+- **Edge cases:** empty test case list, single test case, all failures, all passes, mixed results

package/docs/superpowers/specs/2026-04-07-autonomous-workflow-sub-skill-design.md

@@ -0,0 +1,137 @@
+# Sub-Project 5: Autonomous Workflow & Sub-Skill Framework — Design Spec
+
+## Overview
+
+Transform workspace-maxxing from a single-skill tool into a comprehensive autonomous workflow system using obra/superpowers patterns. Add YAML frontmatter, trigger phrases, anti-rationalization tables, sub-skill dispatch, and a hybrid phase-driven → condition-driven flow.
+
+## Architecture
+
+### File Structure
+
+```
+templates/
+├── SKILL.md                          # Main entry point (rewritten)
+└── .workspace-templates/
+    ├── skills/
+    │   ├── validation/SKILL.md       # Workspace compliance checking
+    │   ├── research/SKILL.md         # Pattern investigation & context gathering
+    │   ├── prompt-engineering/SKILL.md # Prompt improvement & optimization
+    │   ├── testing/SKILL.md          # Test generation & evaluation
+    │   ├── iteration/SKILL.md        # Autonomous improvement loop
+    │   ├── architecture/SKILL.md     # Workspace structure design
+    │   └── tooling/SKILL.md          # Tool assessment & installation
+    └── references/
+        ├── anti-patterns.md          # Shared rationalization tables
+        ├── reporting-format.md       # Standard sub-skill report structure
+        └── iron-laws.md              # Shared discipline rules
+```
+
+### Main SKILL.md — Rewritten with obra patterns
+
+**YAML Frontmatter:**
+```yaml
+---
+name: workspace-maxxing
+description: "Autonomously creates, validates, and improves ICM-compliant workspaces. Use when user asks to 'build a workspace', 'create a workflow', 'automate a process', 'improve this workspace', 'validate this workspace', or 'iterate on this workspace'."
+---
+```
+
+**Core Sections:**
+- `## Overview` — Single-line core principle
+- `## When to Use` — Decision tree (when/when not)
+- `## The Iron Law` — Absolute gates (no build without plan, no plan without research)
+- `## Hybrid Flow` — Phase-driven → condition-driven workflow diagram (DOT)
+- `## Sub-Skill Dispatch` — Table mapping conditions to sub-skills
+- `## Available Scripts` — Existing script documentation
+- `## Anti-Rationalization Table` — Pre-empts agent shortcuts
+- `## Integration` — How sub-skills connect
+
+### Sub-Skills — Each follows obra SKILL.md pattern
+
+Every sub-skill SKILL.md contains:
+1. YAML frontmatter with name + description + trigger phrases
+2. `## Overview` — What it does in one line
+3. `## When to Use` — Decision criteria
+4. `## The Process` — Step-by-step workflow
+5. `## Red Flags` — What to watch for
+6. `## Report Format` — Structured JSON output
+7. `## Integration` — Which sub-skill to dispatch next
+
+### Shared References
+
+**anti-patterns.md:**
+- Common rationalizations agents use to skip steps
+- Reality checks for each rationalization
+- Applies to all sub-skills
+
+**reporting-format.md:**
+- Standard JSON report structure all sub-skills return
+- Fields: skill, status, findings, recommendations, nextSkill
+- Ensures consistent handoff between sub-skills
+
+**iron-laws.md:**
+- NO BUILD WITHOUT PLAN
+- NO PLAN WITHOUT RESEARCH
+- NO IMPROVEMENT WITHOUT VALIDATION
+- NO COMPLETION CLAIM WITHOUT VERIFICATION
+
+### Hybrid Flow
+
+```
+Phase 1: RESEARCH (dispatch research sub-skill)
+  ↓
+Phase 2: ARCHITECTURE (dispatch architecture sub-skill)
+  ↓
+Phase 3: BUILD (use scaffold.ts script)
+  ↓
+Phase 4: VALIDATE (dispatch validation sub-skill)
+  ↓
+Condition Loop (repeat until score > 85 AND all validations pass):
+  ├─ If validation failed → dispatch validation sub-skill
+  ├─ If score < 80 → dispatch prompt-engineering sub-skill
+  ├─ If no tests exist → dispatch testing sub-skill
+  ├─ If score plateaued → dispatch iteration sub-skill
+  └─ If tools missing → dispatch tooling sub-skill
+  ↓
+Phase 5: DELIVER
+```
+
+### Sub-Skill Dispatch Script
+
+New file: `src/scripts/dispatch.ts`
+
+- Loads sub-skill SKILL.md from `skills/<name>/SKILL.md`
+- Prints the sub-skill's full instructions to stdout for the agent to follow
+- Accepts `--skill <name>` and `--workspace <path>` flags
+- Returns the sub-skill's report as JSON when the agent completes its work
+- Zero dependencies (Node.js builtins only)
+
+**Usage:**
+```bash
+node scripts/dispatch.ts --skill validation --workspace ./workspace
+```
+
+The agent reads the dispatched instructions, executes the sub-skill's workflow, and writes the report JSON to stdout.
+
+### Integration Points
+
+- `install.ts` enhanced to copy `skills/` and `references/` directories during install
+- `dispatch.ts` invoked by agents via shell command from skill directory
+- Existing scripts (scaffold, validate, iterate, benchmark) remain unchanged
+- Sub-skills reference existing scripts where applicable
+
+## Testing Strategy
+
+- `tests/dispatch.test.ts` — Sub-skill dispatch and report structure
+- `tests/sub-skill-integration.test.ts` — End-to-end sub-skill workflow
+- `tests/templates-enhanced.test.ts` — Verify all sub-skill SKILL.md files have required sections
+- All existing tests must continue passing (95/95 baseline)
+
+## Constraints
+
+- Zero external dependencies (Node.js builtins only)
+- Scripts invoked via shell commands, not as CLI flags on main package
+- Sub-skills follow obra/superpowers SKILL.md format
+- Main SKILL.md uses YAML frontmatter for trigger detection
+- Progressive disclosure: sub-skill content only loaded when dispatched
+- All sub-skills return structured JSON reports

package/docs/superpowers/specs/2026-04-07-benchmarking-multi-agent-design.md

@@ -0,0 +1,105 @@
+# Sub-Project 4: Benchmarking & Multi-Agent Support — Design Spec
+
+## Overview
+
+Add weighted benchmark scoring, multi-agent CLI installation targeting, guided iteration reports, and console+JSON benchmark output to workspace-maxxing.
+
+## Architecture
+
+### New File: `src/scripts/benchmark.ts`
+
+Zero-dependency Node.js script. Exports:
+- `calculateBenchmark(workspacePath: string)` — scans workspace, calls validate logic, applies weights, returns benchmark data object
+- `formatBenchmarkTable(data)` — returns formatted string for console output
+- `saveBenchmarkReport(workspacePath, data)` — writes JSON to `.workspace-benchmarks/<name>-<timestamp>.json`
+
+### Weighted Scoring Engine
+
+**Default weights:**
+| Stage | Weight | Rationale |
+|-------|--------|-----------|
+| `01-ideation` | 1.5x | Core thinking quality — most critical |
+| `02-research` | 1.3x | Evidence gathering — high importance |
+| `03-architecture` | 1.2x | Structural decisions — important |
+| All other stages | 1.0x | Baseline |
+
+**Formula:**
+```
+weightedStageScore = rawStageScore × weight
+finalScore = Σ(weightedStageScores) / Σ(appliedWeights) × (100 / maxRawScore)
+```
+
+- Stages that don't exist in a workspace are excluded from both numerator and denominator
+- `maxRawScore` = 45 (the per-stage cap from validate.ts)
+- Final score normalized to 0-100
+
+### Multi-Agent CLI Flags
+
+**Flag behavior:**
+| Flag | Installation Target |
+|------|-------------------|
+| (none) | `.agents/skills/workspace-maxxing/` (agent-agnostic default) |
+| `--opencode` | `.agents/skills/workspace-maxxing/` (same as default) |
+| `--claude` | `.claude/skills/` |
+| `--copilot` | `.github/copilot-instructions/` |
+| `--gemini` | `.gemini/skills/` |
+
+**Implementation:**
+- `src/index.ts` parses flags before install
+- `install.ts` receives `targetAgent` parameter
+- Agent-specific paths defined in a single config map
+- All scripts and templates remain identical — only destination changes
+- SKILL.md includes metadata note about which agent it was installed for (no behavioral changes)
+
+### Guided Iteration Reports
+
+**Flow:**
+1. Agent runs `iterate.ts`
+2. Each pass: `validate.ts` → `benchmark.ts` → structured report returned
+3. Report includes: current score, weighted benchmark score, per-stage breakdown, fix suggestions, `improvementPotential` flag
+4. Agent decides whether to apply fixes and re-run
+5. No automatic looping — agent is in control
+
+**Report structure:**
+```json
+{
+  "workspace": "my-project",
+  "agent": "opencode",
+  "timestamp": "2026-04-07T...",
+  "rawScore": 72,
+  "weightedScore": 78,
+  "stages": [
+    { "name": "01-ideation", "raw": 85, "weight": 1.5, "weighted": 95 },
+    { "name": "02-research", "raw": 60, "weight": 1.3, "weighted": 58 }
+  ],
+  "fixSuggestions": ["Add research sources to 02-research", "Expand architecture diagrams"],
+  "improvementPotential": true
+}
+```
+
+### Benchmark Output
+
+**Console:** Formatted table with stage names, raw scores, weights, weighted scores, and total.
+
+**JSON:** Saved to `.workspace-benchmarks/<workspace-name>-<timestamp>.json` with full metadata: workspace path, agent flag used, timestamp, all scores, weights applied.
+
+## Integration Points
+
+- `validate.ts` already returns per-stage scores — `benchmark.ts` consumes those and applies weights
+- `iterate.ts` calls `validate.ts` internally — extended return value includes weighted benchmark data
+- `install.ts` enhanced with agent-targeting flag parsing
+- `src/index.ts` enhanced with CLI flag parsing for `--claude`, `--copilot`, `--gemini`, `--opencode`
+
+## Testing Strategy
+
+- `tests/benchmark.test.ts` — weighted scoring calculations, edge cases (missing stages, zero scores, normalization)
+- `tests/cli-flags.test.ts` — flag parsing and installation targeting
+- `tests/iterate-enhanced.test.ts` — guided iteration report structure
+- All existing tests must continue passing (75/75 baseline)
+
+## Constraints
+
+- Zero external dependencies (Node.js builtins only: `fs`, `path`, `process`, `child_process`)
+- Scripts invoked via shell commands, not as CLI flags on main package
+- Agent-agnostic by default (no flag = universal behavior)
+- Guided iterations only (no autonomous hill-climbing loop)