feed-the-machine 1.5.0 → 1.6.0

package/ftm-executor/references/STYLE-TEMPLATE.md

@@ -1,73 +1,73 @@
-# Code Style — Optimized for AI Agents
-
-> This file defines the code standards for this project. It is read by Codex during adversarial review
-> and enforced automatically. Humans set it once; AI agents follow it on every commit.
-
-## Hard Limits
-
-| Rule | Limit | Rationale |
-|---|---|---|
-| Max lines per file | 1000 | Any AI agent can read one file and understand it without needing 10 others as context |
-| Max lines per function | 50 | Trace a bug by following imports without blowing context window |
-| Exports per component file | 1 (co-located helpers OK) | One responsibility per file, clear import targets |
-| Barrel files (index.ts re-exports) | Forbidden | Direct imports only — barrel files obscure dependency graphs |
-
-## Structure Rules
-
-- **Naming over comments**: If a function needs a comment to explain what it does, it's named wrong
-- **Max 3 nesting levels**: If a file has more than 3 levels of nesting, split it
-- **Co-locate related functions**: If two functions always get called together, they should be in the same module
-- **Max 5 dependencies per module**: If a module has 5+ imports from different modules, it's doing too much — split it
-
-## Why These Rules
-
-These aren't aesthetic preferences. They exist so any AI agent can:
-- **Read one file** and understand it without needing 10 others as context
-- **Trace a bug** by following imports without blowing context window
-- **Modify one function** without risking side effects in a 5000-line file
-- **Review changes** against INTENT.md without getting lost in complexity
-
-## Naming Conventions
-
-| Element | Convention | Example |
-|---|---|---|
-| Files (components) | PascalCase | `UserProfile.tsx` |
-| Files (utilities) | camelCase | `formatDate.ts` |
-| Files (hooks) | camelCase with `use` prefix | `useAuth.ts` |
-| Functions | camelCase | `validateInput()` |
-| Constants | UPPER_SNAKE_CASE | `MAX_RETRIES` |
-| Types/Interfaces | PascalCase | `UserSession` |
-| CSS classes | kebab-case | `.nav-container` |
-
-## Error Handling
-
-- **Fail fast, fail explicitly**: Detect and report errors immediately with meaningful context
-- **Never suppress silently**: All errors must be logged, handled, or escalated
-- **Context preservation**: Error messages include what was attempted, what failed, and where
-
-## Testing Standards
-
-- Tests live next to the code they test: `Component.test.tsx` alongside `Component.tsx`
-- Test file names mirror source file names with `.test.` or `.spec.` suffix
-- Each test file focuses on one module — no cross-module test files
-- Mock data must match real API contracts (see project CLAUDE.md)
-
-## Import Order
-
-1. External packages (react, next, etc.)
-2. Internal absolute imports (@/components, @/utils)
-3. Relative imports (./Component, ../utils)
-4. Type imports (import type { ... })
-5. Style imports (import './styles.css')
-
-Blank line between each group.
-
-## Customization
-
-This is a starting template. Projects should customize:
-- **Naming conventions**: Adapt to your language/framework conventions
-- **Hard limits**: Adjust thresholds if your domain requires longer functions (e.g., complex algorithms)
-- **Testing standards**: Add framework-specific patterns (Jest, Vitest, pytest, etc.)
-- **Import order**: Adapt to your project's module resolution strategy
-
-When customizing, keep the "Why These Rules" section — it reminds both humans and AI agents why the constraints exist.
+# Code Style — Optimized for AI Agents
+
+> This file defines the code standards for this project. It is read by Codex during adversarial review
+> and enforced automatically. Humans set it once; AI agents follow it on every commit.
+
+## Hard Limits
+
+| Rule | Limit | Rationale |
+|---|---|---|
+| Max lines per file | 1000 | Any AI agent can read one file and understand it without needing 10 others as context |
+| Max lines per function | 50 | Trace a bug by following imports without blowing context window |
+| Exports per component file | 1 (co-located helpers OK) | One responsibility per file, clear import targets |
+| Barrel files (index.ts re-exports) | Forbidden | Direct imports only — barrel files obscure dependency graphs |
+
+## Structure Rules
+
+- **Naming over comments**: If a function needs a comment to explain what it does, it's named wrong
+- **Max 3 nesting levels**: If a file has more than 3 levels of nesting, split it
+- **Co-locate related functions**: If two functions always get called together, they should be in the same module
+- **Max 5 dependencies per module**: If a module has 5+ imports from different modules, it's doing too much — split it
+
+## Why These Rules
+
+These aren't aesthetic preferences. They exist so any AI agent can:
+- **Read one file** and understand it without needing 10 others as context
+- **Trace a bug** by following imports without blowing context window
+- **Modify one function** without risking side effects in a 5000-line file
+- **Review changes** against INTENT.md without getting lost in complexity
+
+## Naming Conventions
+
+| Element | Convention | Example |
+|---|---|---|
+| Files (components) | PascalCase | `UserProfile.tsx` |
+| Files (utilities) | camelCase | `formatDate.ts` |
+| Files (hooks) | camelCase with `use` prefix | `useAuth.ts` |
+| Functions | camelCase | `validateInput()` |
+| Constants | UPPER_SNAKE_CASE | `MAX_RETRIES` |
+| Types/Interfaces | PascalCase | `UserSession` |
+| CSS classes | kebab-case | `.nav-container` |
+
+## Error Handling
+
+- **Fail fast, fail explicitly**: Detect and report errors immediately with meaningful context
+- **Never suppress silently**: All errors must be logged, handled, or escalated
+- **Context preservation**: Error messages include what was attempted, what failed, and where
+
+## Testing Standards
+
+- Tests live next to the code they test: `Component.test.tsx` alongside `Component.tsx`
+- Test file names mirror source file names with `.test.` or `.spec.` suffix
+- Each test file focuses on one module — no cross-module test files
+- Mock data must match real API contracts (see project CLAUDE.md)
+
+## Import Order
+
+1. External packages (react, next, etc.)
+2. Internal absolute imports (@/components, @/utils)
+3. Relative imports (./Component, ../utils)
+4. Type imports (import type { ... })
+5. Style imports (import './styles.css')
+
+Blank line between each group.
+
+## Customization
+
+This is a starting template. Projects should customize:
+- **Naming conventions**: Adapt to your language/framework conventions
+- **Hard limits**: Adjust thresholds if your domain requires longer functions (e.g., complex algorithms)
+- **Testing standards**: Add framework-specific patterns (Jest, Vitest, pytest, etc.)
+- **Import order**: Adapt to your project's module resolution strategy
+
+When customizing, keep the "Why These Rules" section — it reminds both humans and AI agents why the constraints exist.

package/ftm-executor/references/phases/PHASE-0-VERIFICATION.md

@@ -1,62 +1,62 @@
-# Phase 0.5 — Plan Verification
-
-## Plan Checker Agent Prompt
-
-Spawn a **Plan Checker** agent with this prompt (use `planning` model from ftm-config):
-
-```
-You are a plan quality checker. Analyze this implementation plan and report issues.
-Do NOT implement anything — just verify the plan is sound.
-
-Plan path: [path]
-
-Check these dimensions:
-
-1. STRUCTURAL INTEGRITY
-   - Every task has: description, files list, dependencies, acceptance criteria
-   - Task numbering is consistent (no gaps, no duplicates)
-   - Dependencies reference valid task numbers
-   - No circular dependencies (Task A depends on B, B depends on A)
-
-2. DEPENDENCY GRAPH VALIDITY
-   - Build the full dependency graph
-   - Verify all referenced tasks exist
-   - Check for implicit dependencies (two tasks modifying the same file
-     but not declared as dependent)
-   - Flag tasks with too many dependencies (>3 usually means bad decomposition)
-
-3. FILE CONFLICT DETECTION
-   - Map every task to its file list
-   - Flag any files touched by multiple tasks in the same wave
-   - These MUST be sequential, not parallel — if the plan puts them
-     in the same wave, that's a bug
-
-4. SCOPE REASONABLENESS
-   - Flag tasks that touch >10 files (probably too big for one agent)
-   - Flag tasks with vague acceptance criteria ("make it work", "looks good")
-   - Flag tasks with no verification steps
-
-5. PROJECT COMPATIBILITY
-   - Check that file paths reference real directories in the project
-   - Verify the tech stack matches what the plan assumes
-   - Check that dependencies/libraries the plan references are installed
-     or listed in package.json/requirements.txt
-
-Return a structured report:
-
-PASS — plan is sound, proceed to execution
-WARN — issues found but execution can proceed (list warnings)
-FAIL — critical issues that must be fixed before execution (list blockers)
-
-For FAIL findings, suggest specific fixes.
-```
-
-## Interpreting Results
-
-- **PASS**: Proceed to Phase 1
-- **WARN**: Show warnings to user, proceed unless they object
-- **FAIL**: Present blockers and suggested fixes. Ask user: fix the plan and re-run, or override and execute anyway?
-
-## File Conflict Auto-Resolution
-
-If the plan checker finds file conflicts between tasks in the same wave, automatically restructure the wave ordering to make conflicting tasks sequential. Report the change to the user before proceeding.
+# Phase 0.5 — Plan Verification
+
+## Plan Checker Agent Prompt
+
+Spawn a **Plan Checker** agent with this prompt (use `planning` model from ftm-config):
+
+```
+You are a plan quality checker. Analyze this implementation plan and report issues.
+Do NOT implement anything — just verify the plan is sound.
+
+Plan path: [path]
+
+Check these dimensions:
+
+1. STRUCTURAL INTEGRITY
+   - Every task has: description, files list, dependencies, acceptance criteria
+   - Task numbering is consistent (no gaps, no duplicates)
+   - Dependencies reference valid task numbers
+   - No circular dependencies (Task A depends on B, B depends on A)
+
+2. DEPENDENCY GRAPH VALIDITY
+   - Build the full dependency graph
+   - Verify all referenced tasks exist
+   - Check for implicit dependencies (two tasks modifying the same file
+     but not declared as dependent)
+   - Flag tasks with too many dependencies (>3 usually means bad decomposition)
+
+3. FILE CONFLICT DETECTION
+   - Map every task to its file list
+   - Flag any files touched by multiple tasks in the same wave
+   - These MUST be sequential, not parallel — if the plan puts them
+     in the same wave, that's a bug
+
+4. SCOPE REASONABLENESS
+   - Flag tasks that touch >10 files (probably too big for one agent)
+   - Flag tasks with vague acceptance criteria ("make it work", "looks good")
+   - Flag tasks with no verification steps
+
+5. PROJECT COMPATIBILITY
+   - Check that file paths reference real directories in the project
+   - Verify the tech stack matches what the plan assumes
+   - Check that dependencies/libraries the plan references are installed
+     or listed in package.json/requirements.txt
+
+Return a structured report:
+
+PASS — plan is sound, proceed to execution
+WARN — issues found but execution can proceed (list warnings)
+FAIL — critical issues that must be fixed before execution (list blockers)
+
+For FAIL findings, suggest specific fixes.
+```
+
+## Interpreting Results
+
+- **PASS**: Proceed to Phase 1
+- **WARN**: Show warnings to user, proceed unless they object
+- **FAIL**: Present blockers and suggested fixes. Ask user: fix the plan and re-run, or override and execute anyway?
+
+## File Conflict Auto-Resolution
+
+If the plan checker finds file conflicts between tasks in the same wave, automatically restructure the wave ordering to make conflicting tasks sequential. Report the change to the user before proceeding.

package/ftm-executor/references/phases/PHASE-2-AGENT-ASSEMBLY.md

@@ -1,34 +1,34 @@
-# Phase 2 — Agent Assembly
-
-## Matching Domain Clusters to Agents
-
-For each domain cluster identified in Phase 1, select the best-fit agent from the table below:
-
-| Domain | Likely Agent |
-|--------|-------------|
-| React/UI/CSS/components | frontend-developer |
-| API/server/database | backend-architect |
-| CI/CD/deploy/infra | devops-automator |
-| Tests/coverage | test-writer-fixer |
-| Mobile/native | mobile-app-builder |
-| AI/ML features | ai-engineer |
-| General coding | general-purpose |
-
-Check available agent types in the Agent tool. Map each cluster to the closest fit before considering custom creation.
-
-## Creating Custom Agents
-
-When no existing agent covers a task cluster adequately — for example, "theme system with CSS custom properties and dark mode" or "WebSocket terminal integration" — create a purpose-built agent prompt.
-
-Write a focused agent definition with these sections:
-
-- **Domain expertise**: What this agent knows deeply
-- **Task context**: The specific tasks from the plan it will handle
-- **Standards**: Coding conventions from the project (infer from existing code)
-- **Constraints**: Don't touch files outside your scope
-
-The prompt text becomes the `prompt` parameter when spawning the agent in Phase 4.
-
-## Building the Agent Library
-
-Store custom agent prompts in the skill workspace as reference prompts so they can be reused across projects. A "theme-engineer" agent created for one project's CSS system can be reused next time themes come up. Over time, the agent library grows with battle-tested specialists.
+# Phase 2 — Agent Assembly
+
+## Matching Domain Clusters to Agents
+
+For each domain cluster identified in Phase 1, select the best-fit agent from the table below:
+
+| Domain | Likely Agent |
+|--------|-------------|
+| React/UI/CSS/components | frontend-developer |
+| API/server/database | backend-architect |
+| CI/CD/deploy/infra | devops-automator |
+| Tests/coverage | test-writer-fixer |
+| Mobile/native | mobile-app-builder |
+| AI/ML features | ai-engineer |
+| General coding | general-purpose |
+
+Check available agent types in the Agent tool. Map each cluster to the closest fit before considering custom creation.
+
+## Creating Custom Agents
+
+When no existing agent covers a task cluster adequately — for example, "theme system with CSS custom properties and dark mode" or "WebSocket terminal integration" — create a purpose-built agent prompt.
+
+Write a focused agent definition with these sections:
+
+- **Domain expertise**: What this agent knows deeply
+- **Task context**: The specific tasks from the plan it will handle
+- **Standards**: Coding conventions from the project (infer from existing code)
+- **Constraints**: Don't touch files outside your scope
+
+The prompt text becomes the `prompt` parameter when spawning the agent in Phase 4.
+
+## Building the Agent Library
+
+Store custom agent prompts in the skill workspace as reference prompts so they can be reused across projects. A "theme-engineer" agent created for one project's CSS system can be reused next time themes come up. Over time, the agent library grows with battle-tested specialists.

package/ftm-executor/references/phases/PHASE-3-WORKTREES.md

@@ -1,38 +1,38 @@
-# Phase 3 — Worktree Setup
-
-## Per-Agent Worktree Creation
-
-Each agent in the current wave gets its own isolated worktree. Run these steps for every agent before dispatch:
-
-**1. Ensure `.worktrees/` is in `.gitignore`**
-
-Check the project's `.gitignore`. If `.worktrees/` is missing, add it before creating any worktrees.
-
-**2. Create the worktree branch and directory**
-
-```bash
-git worktree add .worktrees/plan-exec-<agent-name> -b plan-exec/<agent-name>
-```
-
-Example for frontend agent handling tasks 1–4:
-```bash
-git worktree add .worktrees/plan-exec-frontend-tasks-1-4 -b plan-exec/frontend-tasks-1-4
-```
-
-**3. Run project setup in the worktree**
-
-```bash
-cd .worktrees/plan-exec-<agent-name>
-npm install   # or yarn install / pip install / etc.
-```
-
-**4. Verify the worktree starts clean**
-
-Run the test suite or at minimum the build. If the baseline is already failing, note it before dispatch so the agent doesn't get blamed for pre-existing failures.
-
-## Naming Convention
-
-Branch names: `plan-exec/<agent-name>`
-Worktree paths: `.worktrees/plan-exec-<agent-name>`
-
-Use the agent's role as the name component — e.g., `frontend`, `backend`, `testing`, `devops`. For waves with multiple agents of the same type, append a task range: `frontend-tasks-1-4`.
+# Phase 3 — Worktree Setup
+
+## Per-Agent Worktree Creation
+
+Each agent in the current wave gets its own isolated worktree. Run these steps for every agent before dispatch:
+
+**1. Ensure `.worktrees/` is in `.gitignore`**
+
+Check the project's `.gitignore`. If `.worktrees/` is missing, add it before creating any worktrees.
+
+**2. Create the worktree branch and directory**
+
+```bash
+git worktree add .worktrees/plan-exec-<agent-name> -b plan-exec/<agent-name>
+```
+
+Example for frontend agent handling tasks 1–4:
+```bash
+git worktree add .worktrees/plan-exec-frontend-tasks-1-4 -b plan-exec/frontend-tasks-1-4
+```
+
+**3. Run project setup in the worktree**
+
+```bash
+cd .worktrees/plan-exec-<agent-name>
+npm install   # or yarn install / pip install / etc.
+```
+
+**4. Verify the worktree starts clean**
+
+Run the test suite or at minimum the build. If the baseline is already failing, note it before dispatch so the agent doesn't get blamed for pre-existing failures.
+
+## Naming Convention
+
+Branch names: `plan-exec/<agent-name>`
+Worktree paths: `.worktrees/plan-exec-<agent-name>`
+
+Use the agent's role as the name component — e.g., `frontend`, `backend`, `testing`, `devops`. For waves with multiple agents of the same type, append a task range: `frontend-tasks-1-4`.

package/ftm-executor/references/phases/PHASE-4-5-AUDIT.md

@@ -1,72 +1,72 @@
-# Phase 4.5 — Post-Task Audit Gate
-
-## Per-Task Verification Gate
-
-Before running ftm-audit, verify these four checks for every task:
-
-1. **Tests pass** — any tests written or affected by the task must be green
-2. **INTENT.md updated** — check that new/changed functions have entries in their module's INTENT.md
-3. **Diagram updated** — check that new/changed functions have nodes in their module's DIAGRAM.mmd
-4. **Full suite still green** — run the project's test suite (if one exists) and verify no regressions
-
-5. **Visual smoke test (optional)** — If the project has a running dev server (detected via `lsof -i :3000` or `lsof -i :5173` or configured in plan metadata as `dev_server_url`), run:
-   - `$PB goto <dev_server_url>`
-   - `$PB screenshot`
-   - Verify the screenshot shows a rendered page (not a blank screen or error page)
-   - If the task modified UI components, `$PB snapshot -i` to verify new elements appear in the ARIA tree
-
-   Where `$PB` is `$HOME/.claude/skills/ftm-browse/bin/ftm-browse`.
-
-   **Graceful degradation**: If ftm-browse binary is not installed, skip visual checks with a note: "Visual smoke test skipped — ftm-browse not installed." Do not fail the task.
-
-A task is NOT marked complete until checks 1–4 pass (check 5 is optional).
-
-**Failure handling:**
-- Test failures → agent must fix before task completes
-- Missing INTENT.md entries → add them (use ftm-intent format)
-- Missing diagram nodes → add them (use ftm-diagram format)
-- Regression failures → investigate and fix before continuing
-
-## Running ftm-audit
-
-Use `review` model from ftm-config when spawning audit agents.
-
-**Invoke ftm-audit** scoped to the files the task modified (check the agent's commits). If the task has a `Wiring:` contract in the plan, pass it to ftm-audit for contract checking. Run all three layers: knip static analysis → adversarial audit → auto-fix.
-
-## Interpreting Audit Results
-
-**PASS (no findings):** Mark task complete, proceed to next task.
-
-**PASS after auto-fix:** FTM-audit found issues and fixed them automatically. Commit the fixes in the agent's worktree with message "Auto-fix: wire [description]". Mark task complete.
-
-**FAIL (manual intervention needed):** Task stays in-progress. Report to the user:
-```
-Task [N] audit failed — manual intervention needed:
-- [finding 1 with file:line]
-- [finding 2 with file:line]
-Suggested fixes: [ftm-audit's suggestions]
-```
-Wait for user input before continuing to next task.
-
-## Task Completion Report Format
-
-```
-Task [N]: [title] — COMPLETE
-Audit: PASS (0 findings) | PASS after auto-fix (2 fixed) | FAIL (1 manual)
-[if auto-fixed: list what was fixed]
-[if failed: list outstanding issues]
-```
-
-## When to Skip the Audit
-
-**Skip when:**
-- The task only modified `.md`, `.txt`, `.json` (config), or `.yml` files
-- The task is explicitly marked as a "setup" or "scaffold" task
-- The project has no `package.json` AND no identifiable entry point
-- The plan marks the task with `audit: skip`
-
-The plan syntax for explicit skipping:
-```yaml
-audit: skip
-reason: "Documentation-only task" | "Config change" | "Test-only change"
-```
+# Phase 4.5 — Post-Task Audit Gate
+
+## Per-Task Verification Gate
+
+Before running ftm-audit, verify these four checks for every task:
+
+1. **Tests pass** — any tests written or affected by the task must be green
+2. **INTENT.md updated** — check that new/changed functions have entries in their module's INTENT.md
+3. **Diagram updated** — check that new/changed functions have nodes in their module's DIAGRAM.mmd
+4. **Full suite still green** — run the project's test suite (if one exists) and verify no regressions
+
+5. **Visual smoke test (optional)** — If the project has a running dev server (detected via `lsof -i :3000` or `lsof -i :5173` or configured in plan metadata as `dev_server_url`), run:
+   - `$PB goto <dev_server_url>`
+   - `$PB screenshot`
+   - Verify the screenshot shows a rendered page (not a blank screen or error page)
+   - If the task modified UI components, `$PB snapshot -i` to verify new elements appear in the ARIA tree
+
+   Where `$PB` is `$HOME/.claude/skills/ftm-browse/bin/ftm-browse`.
+
+   **Graceful degradation**: If ftm-browse binary is not installed, skip visual checks with a note: "Visual smoke test skipped — ftm-browse not installed." Do not fail the task.
+
+A task is NOT marked complete until checks 1–4 pass (check 5 is optional).
+
+**Failure handling:**
+- Test failures → agent must fix before task completes
+- Missing INTENT.md entries → add them (use ftm-intent format)
+- Missing diagram nodes → add them (use ftm-diagram format)
+- Regression failures → investigate and fix before continuing
+
+## Running ftm-audit
+
+Use `review` model from ftm-config when spawning audit agents.
+
+**Invoke ftm-audit** scoped to the files the task modified (check the agent's commits). If the task has a `Wiring:` contract in the plan, pass it to ftm-audit for contract checking. Run all three layers: knip static analysis → adversarial audit → auto-fix.
+
+## Interpreting Audit Results
+
+**PASS (no findings):** Mark task complete, proceed to next task.
+
+**PASS after auto-fix:** FTM-audit found issues and fixed them automatically. Commit the fixes in the agent's worktree with message "Auto-fix: wire [description]". Mark task complete.
+
+**FAIL (manual intervention needed):** Task stays in-progress. Report to the user:
+```
+Task [N] audit failed — manual intervention needed:
+- [finding 1 with file:line]
+- [finding 2 with file:line]
+Suggested fixes: [ftm-audit's suggestions]
+```
+Wait for user input before continuing to next task.
+
+## Task Completion Report Format
+
+```
+Task [N]: [title] — COMPLETE
+Audit: PASS (0 findings) | PASS after auto-fix (2 fixed) | FAIL (1 manual)
+[if auto-fixed: list what was fixed]
+[if failed: list outstanding issues]
+```
+
+## When to Skip the Audit
+
+**Skip when:**
+- The task only modified `.md`, `.txt`, `.json` (config), or `.yml` files
+- The task is explicitly marked as a "setup" or "scaffold" task
+- The project has no `package.json` AND no identifiable entry point
+- The plan marks the task with `audit: skip`
+
+The plan syntax for explicit skipping:
+```yaml
+audit: skip
+reason: "Documentation-only task" | "Config change" | "Test-only change"
+```