workspace-maxxing 0.5.0 → 0.6.1

package/.agents/skills/workspace-maxxing/skills/architecture/SKILL.md

@@ -0,0 +1,95 @@
+---
+name: architecture
+description: "Designs workspace structure, plans folder layout, and creates the build plan. Use when planning workspace structure, designing folder hierarchy, or after research phase."
+triggers: ["design workspace", "plan structure", "folder layout", "build plan"]
+---
+
+## Overview
+
+Design the workspace structure based on research findings. Architecture translates research into a concrete, buildable plan.
+
+## When to Use
+
+- Phase 2 of the hybrid flow (after research)
+- When research is complete and building is next
+- When restructuring an existing workspace
+
+## When Not to Use
+
+- Before research is complete (use research sub-skill)
+- During building itself (use scaffold.ts directly)
+- For minor structural tweaks (use direct file operations)
+
+## The Iron Law
+
+NO ARCHITECTURE WITHOUT RESEARCH
+NO BUILDING WITHOUT APPROVED PLAN
+NO SKIPPING USER APPROVAL
+NO AMBIGUOUS STAGE DEFINITIONS
+
+## Scope Guardrails
+
+- Design only the ICM workspace architecture (folders, routing, context contracts).
+- Plan markdown workflow artifacts per stage; do not design application runtime components.
+- Keep architecture outputs directly consumable by scaffold.ts for file-structured markdown folders.
+- Treat product implementation asks as workflow requirements captured in stage docs.
+
+## The Process
+
+1. **Review research findings** - Read the research sub-skill report.
+2. **Define stage folders** - Determine numbered folder structure (01-xxx, 02-xxx, and so on) for workflow execution.
+3. **Design routing table** - Plan CONTEXT.md routing for each stage.
+4. **Define SYSTEM.md** - Plan the folder map, rules, and tool inventory.
+5. **Plan CONTEXT.md content** - Define what each stage CONTEXT.md must contain and which markdown artifacts it must produce.
+6. **Create build plan** - Document the scaffold.ts command with all parameters.
+7. **Get approval** - Present the plan to the user before building.
+
+## Red Flags
+
+- Stage folders do not follow sequential numbering
+- Routing table does not reference all stages
+- SYSTEM.md plan is missing or incomplete
+- Build plan is missing scaffold.ts parameters
+- User approval is skipped before build
+- Plan includes backend/frontend/database implementation details instead of workspace structure
+
+## Anti-Rationalization Table
+
+| Thought | Reality |
+|---------|---------|
+| "I will adjust the structure while building" | Structure changes mid-build are expensive. Plan first. |
+| "This stage name is good enough" | Stage names affect routing. Be precise. |
+| "The user will understand without approval" | Unapproved plans produce unwanted results. Always present the plan. |
+
+## Sub-Skill Dispatch
+
+- `status = passed` (plan approved) -> `nextSkill = none` and main workflow runs scaffold.ts.
+- `status = failed` (plan incomplete or not approved) -> `nextSkill = none`.
+- `status = escalated` (blocking uncertainty) -> `nextSkill = none`.
+
+## Report Format
+
+```json
+{
+  "skill": "architecture",
+  "status": "passed",
+  "timestamp": "2026-04-08T00:00:00Z",
+  "findings": ["Defined four sequential stages with explicit routing"],
+  "recommendations": ["Run scaffold.ts using the approved stage list"],
+  "metrics": {
+    "stagesPlanned": 4,
+    "toolsIdentified": 2
+  },
+  "nextSkill": "none"
+}
+```
+
+Allowed `status` values: `passed`, `failed`, `escalated`.
+
+Allowed `nextSkill` values: `none`.
+
+## Integration
+
+- Uses research output as architecture input.
+- Produces the approved plan consumed by scaffold.ts.
+

package/.agents/skills/workspace-maxxing/skills/fixer/SKILL.md

@@ -0,0 +1,109 @@
+---
+name: fixer
+description: "Applies targeted fixes to failing test case outputs. Use when fixing failed worker outputs, improving low-scoring results, or addressing validator findings."
+triggers: ["fix failing test", "improve output", "address validation failure", "apply targeted fix"]
+---
+
+## Overview
+
+Read validator findings and original worker output, identify the root cause of failure, apply the minimal fix needed, and prepare the case for re-validation. Each fixer runs with fresh context.
+
+## When to Use
+
+- Dispatched by orchestrator in a fix loop
+- Validator identifies specific failures for a test case
+- Worker output is incomplete, incorrect, or misaligned with expectations
+
+## When Not to Use
+
+- Generating new output from scratch (use worker sub-skill)
+- Validating outputs (use validation sub-skill)
+- Redesigning workspace structure (use architecture sub-skill)
+
+## The Iron Law
+
+NO BLIND RETRIES
+NO COSMETIC FIXES
+NO FIXING WHAT IS NOT BROKEN
+NO CLAIMING FIX WITHOUT RE-VALIDATION
+
+## The Process
+
+1. **Read validator findings** - Load `batch-report.json` from the batch directory
+2. **Read original output** - Load `output.md` and `report.json` from `.agents/iteration/batch-<N>/<testCaseId>/`
+3. **Identify root cause** - Map each finding to a specific defect in the output
+4. **Apply minimal fix** - Change only what is needed to resolve each finding
+5. **Update output.md** - Write the fixed output for the same test case
+6. **Write report.json** - Structured JSON with `{skill, status, timestamp, testCaseId, batchId, findings, fixesApplied, recommendations, metrics, nextSkill}`
+7. **Dispatch validation** - Signal that the fix is ready for re-validation
+
+## External Runner Contract
+
+- Fixer execution in autonomous iteration is orchestrated via `--subagent-runner`.
+- Direct fixer dispatch must provide `--runner-command` with placeholders `{skill}`, `{workspace}`, `{batchId}`, `{testCaseId}`.
+- Runner output must be JSON and include `report.json` compatible fields:
+  - `skill`, `status`, `timestamp`, `findings`, `recommendations`, `metrics`, `nextSkill`
+- Missing/invalid runner output is a failure, not a simulated success path.
+- Use `.agents/iteration/runs/*.json` telemetry to debug command rendering and runner payload issues.
+
+## Agent-Driven Test-Case Generation (Required)
+
+- **Agent ownership:** Test-cases MUST be discovered and authored by an agent using the workspace context. Do not rely on hardcoded script-generated test cases.
+- **Where to write:** The agent must write the test-case bundle to `.agents/iteration/test-cases.json` inside the workspace before the orchestrator or validator dispatches workers. Validators and orchestrator flows will treat this file as the authoritative source of inputs for the iteration.
+- **Discovery guidance:** Agents should inspect repo files (SYSTEM.md, CONTEXT.md, stage CONTEXTs, user prompts, examples, and any domain files) to infer realistic inputs, edge cases, and acceptance criteria. Test-cases should reflect actual workspace intent and cover positive, negative, and boundary cases.
+- **Schema (minimal):** The file must be valid JSON and an array of objects with the following fields:
+
+```json
+[
+  {
+    "id": "tc-001",
+    "title": "Short descriptive title",
+    "input": {"type": "text", "payload": "..."},
+    "expected": {"criteria": ["..."], "matcher": "contains|equals|schema"},
+    "metadata": {"priority": "high|medium|low", "sourceHints": ["SYSTEM.md"]}
+  }
+]
+```
+
+- **Idempotence:** Agents may re-generate or refine the file across iterations, but each write must be complete (no partial artifacts) and timestamped inside the JSON if updated.
+- **Signal readiness:** After creating `.agents/iteration/test-cases.json` the agent should also write a single-line marker file `.agents/iteration/.test-cases-ready` to avoid race conditions with orchestrators reading stdout.
+
+## Enforcement Notes
+
+- **Validator contract:** The validation step is expected to check for `.agents/iteration/test-cases.json` when running in agent-driven mode and fail fast if missing or malformed. This ensures the orchestrator cannot fall back to hardcoded script cases.
+- **Orchestrator behavior:** When agent-driven mode is enabled, the orchestrator must prefer `.agents/iteration/test-cases.json` and should not call or rely on any built-in `generate-tests` script to produce authoritative inputs.
+- **Audit trail:** Agents should include a `generatedBy` and `timestamp` field in the test-cases file to aid debugging and reproducibility.
+
+## Anti-Rationalization Table
+
+| Thought | Reality |
+|---------|---------|
+| "I will just re-run the worker logic" | Blind retries do not fix root causes. Address the findings directly. |
+| "This looks better now" | Better is subjective. The fix must satisfy the validator criteria. |
+| "I will fix other things while I am here" | Scope creep adds risk. Fix only what was flagged. |
+| "The fix is obvious" | Obvious assumptions cause regressions. Tie every change to a finding. |
+| "I do not need to re-validate" | Unvalidated fixes are guesses. Always dispatch validation. |
+
+## Sub-Skill Dispatch
+
+- After fix applied -> validation sub-skill
+
+## Report Format
+
+```json
+{
+  "skill": "fixer",
+  "status": "passed|failed|escalated",
+  "timestamp": "2026-04-08T00:00:00Z",
+  "testCaseId": "tc-001",
+  "batchId": 1,
+  "findings": ["Missing expected acceptance criteria section"],
+  "fixesApplied": ["Added acceptance criteria section from validator recommendation"],
+  "recommendations": ["Run validation to confirm all findings are cleared"],
+  "metrics": {
+    "findingsAddressed": 1,
+    "fixesApplied": 1
+  },
+  "nextSkill": "validation"
+}
+```

package/.agents/skills/workspace-maxxing/skills/iteration/SKILL.md

@@ -0,0 +1,89 @@
+---
+name: iteration
+description: "Runs autonomous improvement loops with benchmark scoring. Use when score plateaued, deeper fixes needed, or after testing identifies patterns."
+triggers: ["run improvement loop", "iterate on workspace", "deeper fixes", "score plateau"]
+---
+
+## Overview
+
+Execute improvement loops until quality thresholds are met. Iteration applies systematic fixes when first-pass prompt improvements are not enough.
+
+## When to Use
+
+- Score is plateaued across runs
+- Testing finds repeated failure patterns
+- Validation failures persist after prompt-engineering
+- The condition-driven improvement loop requires deeper fixes
+- Latest benchmark score is strictly between 80 and 85 (`80 < score < 85`)
+- Score is 80 or lower (`score <= 80`) after prompt-engineering stops improving
+
+## When Not to Use
+
+- For first-pass improvements (use prompt-engineering first)
+- When workspace is new and untested (use testing first)
+- When structural redesign is needed (use architecture)
+
+## The Iron Law
+
+NO CLAIMING IMPROVEMENT WITHOUT RE-RUNNING BENCHMARK
+NO SKIPPING FIX SUGGESTIONS
+NO INFINITE ITERATION LOOPS
+NO SKIPPING ESCALATION WHEN STUCK
+
+## The Process
+
+1. **Run iterate.ts** - Execute `node scripts/iterate.ts --workspace <path> --max-retries 3`.
+2. **Read benchmark results** - Parse score, fixSuggestions, and improvementPotential.
+3. **Identify improvement areas** - Prioritize changes with highest impact.
+4. **Apply fixes** - Address each suggestion systematically.
+5. **Re-run iteration** - Verify score movement.
+6. **Repeat until threshold** - Continue until score is 85 or higher (`score >= 85`) or no improvement is possible.
+7. **Escalate if stuck** - If score remains below 85 after 3 attempts, escalate.
+
+## Red Flags
+
+- Improvement is claimed without fresh benchmark evidence
+- Fix suggestions are ignored
+- Loop runs beyond max retries
+- Escalation is skipped despite stalled score
+
+## Anti-Rationalization Table
+
+| Thought | Reality |
+|---------|---------|
+| "I will just run it again" | Re-running without fixes wastes cycles. |
+| "The score improved by one point" | Marginal gains are not enough. Target is 85 or higher. |
+| "I will keep iterating until it works" | Maximum 3 attempts, then escalate. |
+
+## Sub-Skill Dispatch
+
+- `status = passed` (`score >= 85`) -> `nextSkill = none`.
+- `status = failed` (`score < 85` after max retries) -> `nextSkill = none` and require human follow-up.
+- `status = escalated` (critical blocker prevents safe continuation) -> `nextSkill = none`.
+
+## Report Format
+
+```json
+{
+  "skill": "iteration",
+  "status": "passed",
+  "timestamp": "2026-04-08T00:00:00Z",
+  "findings": ["Resolved two repeated edge-case failures"],
+  "recommendations": ["Run final validation and testing before delivery"],
+  "metrics": {
+    "scoreBefore": 81,
+    "scoreAfter": 88,
+    "iterationsRun": 2
+  },
+  "nextSkill": "none"
+}
+```
+
+Allowed `status` values: `passed`, `failed`, `escalated`.
+
+Allowed `nextSkill` values: `none`.
+
+## Integration
+
+- Works after testing or prompt-engineering when quality is stuck.
+- Hands final results back to validation and completion checks.

package/.agents/skills/workspace-maxxing/skills/prompt-engineering/SKILL.md

@@ -0,0 +1,87 @@
+---
+name: prompt-engineering
+description: "Improves CONTEXT.md and SYSTEM.md prompts for better agent behavior. Use when workspace score is 80 or lower, prompts need improvement, or after validation identifies content gaps."
+triggers: ["improve prompts", "fix content gaps", "optimize prompts", "clarify instructions"]
+---
+
+## Overview
+
+Optimize workspace prompts for clarity, completeness, and agent guidance. Prompt engineering resolves content-level quality issues without structural redesign.
+
+## When to Use
+
+- Score is 80 or lower in benchmark results (`score <= 80`)
+- Validation identifies missing or weak content
+- Prompts are vague or incomplete
+- Agent behavior does not match expectations
+
+## When Not to Use
+
+- For structural issues (use architecture or fixer)
+- When workspace has no content yet (use worker)
+- For dependency installation (use tooling)
+
+## The Iron Law
+
+NO COSMETIC CHANGES WITHOUT FUNCTIONAL IMPROVEMENT
+NO CHANGING PROMPTS WITHOUT RE-VALIDATING
+NO REMOVING CONTENT WITHOUT REPLACEMENT
+NO CLAIMING IMPROVEMENT WITHOUT SCORE CHECK
+
+## The Process
+
+1. **Identify weak prompts** - Read benchmark findings and validation failures.
+2. **Analyze current prompts** - Identify what is missing, vague, or contradictory.
+3. **Apply prompt patterns** - Use clear structure, examples, constraints, and output format guidance.
+4. **Update CONTEXT.md files** - Improve stage-specific instructions.
+5. **Update SYSTEM.md if needed** - Improve folder map, rules, and tool inventory guidance.
+6. **Re-run validation** - Verify improvements did not break compliance.
+7. **Re-run benchmark** - Confirm score movement.
+
+## Red Flags
+
+- Cosmetic wording changes with no measurable improvement
+- Prompt edits made without re-validation
+- Content removed without replacement
+- No before/after score comparison
+
+## Anti-Rationalization Table
+
+| Thought | Reality |
+|---------|---------|
+| "This wording change is enough" | Wording changes must produce functional improvement. |
+| "I will remove vague sections" | Removing sections creates gaps. Improve, do not delete. |
+| "The score did not change, but it is better" | No score change means no proven improvement. Iterate again. |
+
+## Sub-Skill Dispatch
+
+- `status = passed` (`scoreAfter > 80`) -> `nextSkill = testing`.
+- `status = failed` (`scoreAfter <= 80` or no measurable improvement) -> `nextSkill = iteration`.
+- `status = escalated` (requirements conflict or critical blocker) -> `nextSkill = none`.
+
+## Report Format
+
+```json
+{
+  "skill": "prompt-engineering",
+  "status": "passed",
+  "timestamp": "2026-04-08T00:00:00Z",
+  "findings": ["Clarified output constraints in two stage prompts"],
+  "recommendations": ["Run testing to verify edge-case behavior"],
+  "metrics": {
+    "scoreBefore": 74,
+    "scoreAfter": 83,
+    "promptsUpdated": 3
+  },
+  "nextSkill": "testing"
+}
+```
+
+Allowed `status` values: `passed`, `failed`, `escalated`.
+
+Allowed `nextSkill` values: `testing`, `iteration`, `none`.
+
+## Integration
+
+- Consumes findings from validation and benchmark.
+- Produces higher-quality prompt content for testing and iteration.

package/.agents/skills/workspace-maxxing/skills/research/SKILL.md

@@ -0,0 +1,94 @@
+---
+name: research
+description: "Investigates patterns, gathers context, and identifies best practices for workspace design. Use when starting a new workspace, researching workflow patterns, or before architecture planning."
+triggers: ["research workflow", "gather context", "identify patterns", "best practices"]
+---
+
+## Overview
+
+Gather context and identify patterns before building. Research ensures the workspace design is informed by real requirements, not assumptions.
+
+## When to Use
+
+- Phase 1 of the hybrid flow (always first)
+- Before architecture planning
+- When the user asks for a novel workflow type
+- When existing patterns do not fit the use case
+
+## When Not to Use
+
+- After architecture is already planned (use architecture sub-skill)
+- When workspace structure already exists (use validation sub-skill)
+- For simple file creation (use direct file operations)
+
+## The Iron Law
+
+NO BUILD WITHOUT RESEARCH
+NO GENERIC FINDINGS
+NO SKIPPING INPUT/OUTPUT ANALYSIS
+NO ASSUMPTIONS WITHOUT EVIDENCE
+
+## Scope Guardrails
+
+- Research the workflow needed to produce outcomes, not the product implementation stack.
+- Convert domain asks (for example, "football predictor") into stageable workflow responsibilities.
+- Keep research outputs markdown-first and suitable for numbered folder CONTEXT contracts.
+- Do not produce backend/frontend/data-model implementation plans in this phase.
+
+## The Process
+
+1. **Identify workflow type** - Determine what process is being automated as a file-structured markdown workflow.
+2. **Research similar patterns** - Review existing workspaces, docs, and best practices.
+3. **Identify key stages** - Define the natural workflow phases.
+4. **Determine inputs and outputs** - Capture what goes in and what markdown artifacts come out at each stage.
+5. **Identify tooling needs** - List tools commonly needed for this workflow.
+6. **Document findings** - Create a concise research summary for architecture.
+
+## Red Flags
+
+- Research is too generic and not tied to the requested workflow
+- Input and output analysis is missing
+- Tooling assessment is missing
+- Architecture starts before research findings are complete
+- Findings drift into app architecture, model design, or runtime repository scaffolding
+
+## Anti-Rationalization Table
+
+| Thought | Reality |
+|---------|---------|
+| "I already know this workflow type" | Knowledge is not research. Document findings for the next agent. |
+| "Research is taking too long" | Research prevents wasted build time. Be thorough. |
+| "I will figure it out while building" | Building without research produces generic, non-optimal workspaces. |
+| "The user will clarify later" | Ask now. Ambiguous requirements produce ambiguous workspaces. |
+
+## Sub-Skill Dispatch
+
+- `status = passed` -> `nextSkill = architecture`.
+- `status = failed` (research incomplete but recoverable) -> `nextSkill = none` and request missing inputs before rerun.
+- `status = escalated` (blocking ambiguity or conflicting constraints) -> `nextSkill = none`.
+
+## Report Format
+
+```json
+{
+  "skill": "research",
+  "status": "passed",
+  "timestamp": "2026-04-08T00:00:00Z",
+  "findings": ["Identified three reusable workflow stage patterns"],
+  "recommendations": ["Use a three-stage layout with explicit input/output boundaries"],
+  "metrics": {
+    "patternsIdentified": 3,
+    "stagesIdentified": 3
+  },
+  "nextSkill": "architecture"
+}
+```
+
+Allowed `status` values: `passed`, `failed`, `escalated`.
+
+Allowed `nextSkill` values: `architecture`, `none`.
+
+## Integration
+
+- Feeds architecture with concrete findings and stage proposals.
+- Reduces rework by grounding structure decisions in evidence.

package/.agents/skills/workspace-maxxing/skills/testing/SKILL.md

@@ -0,0 +1,89 @@
+---
+name: testing
+description: "Generates and runs test cases, evaluates results, and identifies gaps. Use when testing workspace quality, generating test cases, or after prompt improvements."
+triggers: ["generate test cases", "run tests", "test workspace", "evaluate quality"]
+---
+
+## Overview
+
+Verify workspace quality through systematic testing. Testing confirms outputs across sample, edge-case, and empty-input scenarios.
+
+## When to Use
+
+- After prompt-engineering improvements
+- When no tests exist for the workspace
+- Before claiming delivery
+- When benchmark score is strictly between 80 and 85 (`80 < score < 85`)
+- When score is 85 or higher and final evidence is still required
+
+## When Not to Use
+
+- Before workspace build is complete (run scaffold.ts first)
+- For structural validation (use validation sub-skill)
+- When applying direct fixes to failures (use fixer sub-skill)
+- When benchmark score is 80 or lower (`score <= 80`) (use prompt-engineering first)
+
+## The Iron Law
+
+NO SKIPPING TEST GENERATION
+NO IGNORING FAILED TESTS
+NO CLAIMING QUALITY WITHOUT EVIDENCE
+NO TESTING WITHOUT TEST CASES
+
+## The Process
+
+1. **Generate test cases** - Run `node scripts/generate-tests.ts --workspace <path> --output ./tests.json`.
+2. **Read test cases** - Parse generated test cases and expected outcomes.
+3. **Run generation tests** - Produce sample content each stage should output.
+4. **Run evaluation tests** - Review CONTEXT.md files against expected behavior.
+5. **Aggregate results** - Identify recurring patterns and quality gaps.
+6. **Document findings** - Create a pass/fail report per test case.
+
+## Red Flags
+
+- Test generation is skipped
+- Generation tests run without evaluation tests
+- Failed test cases are ignored
+- Failure patterns are undocumented
+
+## Anti-Rationalization Table
+
+| Thought | Reality |
+|---------|---------|
+| "The workspace looks fine, no need to test" | Looks can deceive. Tests reveal behavior. |
+| "One failed test is a fluke" | Failed tests are signals. Investigate each one. |
+| "I will test after delivery" | Untested delivery is a gamble. Test first. |
+
+## Sub-Skill Dispatch
+
+- `status = passed` (all required tests pass and `benchmarkScore >= 85`) -> `nextSkill = none`.
+- `status = failed` (any required test fails or `benchmarkScore < 85`) -> `nextSkill = iteration`.
+- `status = escalated` (testing cannot run reliably due to blockers) -> `nextSkill = none`.
+
+## Report Format
+
+```json
+{
+  "skill": "testing",
+  "status": "failed",
+  "timestamp": "2026-04-08T00:00:00Z",
+  "findings": ["Two edge-case outputs failed acceptance checks"],
+  "recommendations": ["Run iteration to address repeated edge-case defects"],
+  "metrics": {
+    "benchmarkScore": 82,
+    "testCasesGenerated": 9,
+    "testCasesPassed": 7,
+    "testCasesFailed": 2
+  },
+  "nextSkill": "iteration"
+}
+```
+
+Allowed `status` values: `passed`, `failed`, `escalated`.
+
+Allowed `nextSkill` values: `iteration`, `none`.
+
+## Integration
+
+- Uses generate-tests.ts output as primary test input.
+- Supplies pass/fail evidence for iteration and final verification.

package/.agents/skills/workspace-maxxing/skills/tooling/SKILL.md

@@ -0,0 +1,87 @@
+---
+name: tooling
+description: "Assesses, installs, and configures tools for the workspace. Use when tools are missing, tool inventory needs updating, or workspace requires specific dependencies."
+triggers: ["install tools", "assess tooling", "update tool inventory", "configure dependencies"]
+---
+
+## Overview
+
+Ensure workspace has the right tools installed and configured. Tooling manages the dependency layer of the workspace.
+
+## When to Use
+
+- Tool inventory is empty or incomplete
+- Workspace requires specific dependencies
+- Architecture identifies missing tooling needs
+- User requests specific tool installation
+
+## When Not to Use
+
+- For non-tool structural changes (use architecture)
+- For content quality improvements (use prompt-engineering)
+- When no additional tools are needed
+
+## The Iron Law
+
+NO INSTALLING TOOLS WITHOUT USER APPROVAL
+NO SKIPPING TOOL INVENTORY UPDATES
+NO INSTALLING UNNECESSARY TOOLS
+NO SKIPPING VERIFICATION AFTER INSTALLATION
+
+## The Process
+
+1. **Scan current tools** - Read SYSTEM.md tool inventory.
+2. **Identify missing tools** - Compare requirements against installed tools.
+3. **Propose tools** - Provide recommended tools with justification.
+4. **Get approval** - Present the tool plan before installing.
+5. **Install tools** - Run `node scripts/install-tool.ts --tool <name> --manager <mgr> --workspace <path>`.
+6. **Update inventory** - Confirm SYSTEM.md or inventory section is updated.
+7. **Verify installation** - Confirm each installed tool is accessible.
+
+## Red Flags
+
+- Tools installed without approval
+- Inventory not updated after install
+- Unnecessary tools installed
+- Installation not verified
+
+## Anti-Rationalization Table
+
+| Thought | Reality |
+|---------|---------|
+| "This tool might be useful" | "Might" is not enough. Every tool needs explicit justification. |
+| "I will install now and tell the user later" | Approval must come before installation. |
+| "The install probably worked" | Probably is not verified. Validate each install. |
+
+## Sub-Skill Dispatch
+
+- `status = passed` (approved tooling installed and verified) -> `nextSkill = none`.
+- `status = failed` (installation incomplete or verification failed) -> `nextSkill = none`.
+- `status = escalated` (blocked by permissions, policy, or unresolved conflicts) -> `nextSkill = none`.
+
+## Report Format
+
+```json
+{
+  "skill": "tooling",
+  "status": "passed",
+  "timestamp": "2026-04-08T00:00:00Z",
+  "findings": ["Installed two approved dependencies"],
+  "recommendations": ["Run validation to confirm inventory consistency"],
+  "metrics": {
+    "toolsInstalled": 2,
+    "toolsProposed": 2,
+    "toolsFailed": 0
+  },
+  "nextSkill": "none"
+}
+```
+
+Allowed `status` values: `passed`, `failed`, `escalated`.
+
+Allowed `nextSkill` values: `none`.
+
+## Integration
+
+- Consumes architecture and requirement signals to propose tools.
+- Produces verified dependency state for downstream validation.