feed-the-machine 1.0.0

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

@@ -0,0 +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.

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

@@ -0,0 +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.

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

@@ -0,0 +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.

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

@@ -0,0 +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`.

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

@@ -0,0 +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"
+```

package/ftm-executor/references/phases/PHASE-4-DISPATCH.md

@@ -0,0 +1,66 @@
+# Phase 4 — Agent Dispatch Prompt Template
+
+## Full Prompt Template
+
+Use this structure for every agent dispatched in Phase 4. Fill in bracketed fields from the plan and execution context.
+
+```
+You are working in an isolated git worktree at: [worktree path]
+Your working directory is: [worktree path]
+
+## Your Assignment
+
+Execute the following tasks from the plan:
+
+[paste the relevant task sections verbatim from the plan doc]
+
+## Plan Context
+
+Full plan: [plan path]
+Your tasks: [task numbers]
+Dependencies satisfied: [list what was already completed in prior waves]
+
+## Execution Loop
+
+For EACH task, follow this cycle:
+
+1. **Implement** — Follow the plan's steps exactly. Read files before modifying them. Use the project's existing patterns.
+
+2. **Commit** — Stage and commit your changes with a clear message describing what was done. Never reference AI/agent tools in commit messages.
+
+2.5. **Document** — Every commit must include documentation updates:
+   - Update the module's INTENT.md: add entries for new functions, update entries for changed functions (Does/Why/Relationships/Decisions format)
+   - Update the module's DIAGRAM.mmd: add nodes for new functions, update edges for changed dependencies
+   - If you created a new module directory, also create its INTENT.md and DIAGRAM.mmd, and add rows to root INTENT.md module map and root ARCHITECTURE.mmd
+   - Reference STYLE.md for code standards — your code must comply with all Hard Limits and Structure Rules
+
+3. **Review** — After committing, review your own changes:
+   - Run `git diff HEAD~1` to see what changed
+   - Check for: bugs, missing error handling, type errors, style inconsistencies
+   - Run any verification commands the plan specifies
+   - Run the project's linter/typecheck if available
+
+4. **Fix** — If the review surfaces issues:
+   - Fix them immediately
+   - Commit the fixes
+   - Review again
+   - Repeat until clean
+
+5. **Continue** — Move to the next task. Do not stop to ask questions. If something is ambiguous, make the best technical decision and document it in your commit message.
+
+## Rules
+
+- NEVER stop to ask for input. Make decisions and keep going.
+- ALWAYS commit after each task (not one big commit at the end).
+- ALWAYS review after each commit. The review-fix loop is not optional.
+- Follow the plan's steps exactly — don't improvise unless the plan is clearly wrong.
+- Stay in your worktree. Don't touch files outside your assigned scope.
+- If a verification step fails and you can't fix it in 3 attempts, note it in a commit message and move on.
+- Run tests/build after each task if the project supports it.
+- Read STYLE.md at the project root before writing code. Follow all Hard Limits and Structure Rules.
+- Every commit must include: code changes + tests + INTENT.md update + DIAGRAM.mmd update. A commit without documentation updates is incomplete.
+```
+
+## Model Selection
+
+Pass the `execution` model from ftm-config as the `model` parameter when spawning dispatch agents. If the profile specifies `inherit`, omit the `model` parameter.

package/ftm-executor/references/phases/PHASE-5-5-CODEX-GATE.md

@@ -0,0 +1,73 @@
+# Phase 5.5 — Codex Gate (Wave Boundary Validation)
+
+## When to Invoke
+
+- After EVERY wave completes and is merged — this is the heavy validation gate
+- For single-task plans, invoke on task completion instead of wave completion
+
+## Inputs for ftm-codex-gate
+
+- `file_list`: All files changed across the wave (`git diff --name-only` against pre-wave state)
+- `acceptance_criteria`: Combined acceptance criteria from all tasks in the wave
+- `wave_context`: Summary of what the wave accomplished (task titles + brief descriptions)
+- `project_root`: The project working directory
+- `mode`: `"wave"` for multi-task waves, `"single-task"` for single-task runs
+
+## Result Interpretation
+
+**PASS (no issues found):**
+- Log in PROGRESS.md: "Codex gate PASSED — 0 issues"
+- Proceed to next wave (or Phase 6 if this was the last wave)
+
+**PASS_WITH_FIXES (issues found and auto-fixed by Codex):**
+- Codex committed fixes directly — review the fix commits
+- Diff each fix commit against INTENT.md entries for the affected functions
+- No INTENT.md conflict → accept the fixes, log in PROGRESS.md and DEBUG.md, proceed
+- INTENT.md conflict detected → see INTENT.md Conflict Resolution below
+
+**FAIL (issues Codex could not fix):**
+- Attempt to fix them yourself (you have full context from the wave)
+- If fixed, commit and re-run the Codex gate
+- If unresolved after 2 attempts, report to user:
+  ```
+  Codex gate FAILED for Wave [N] — manual intervention needed:
+  - [remaining issue 1]
+  - [remaining issue 2]
+  Codex attempted [N] fixes but these remain unresolved.
+  ```
+  Wait for user input before continuing.
+
+## INTENT.md Conflict Resolution
+
+A conflict exists when Codex's fix changes a function's behavior, reverts a deliberate choice, or changes a signature that INTENT.md documents.
+
+**Step 1 — Detect:** Compare the Codex fix diff against the INTENT.md entry for the affected function.
+
+**Step 2 — Invoke ftm-council** with this structured payload:
+```
+CONFLICT TYPE: Codex fix contradicts INTENT.md
+
+ORIGINAL INTENT (from INTENT.md):
+[paste the full INTENT.md entry for the affected function]
+
+CODEX'S CHANGE:
+[paste the diff of what Codex changed]
+
+CODEX'S REASONING:
+[paste Codex's explanation from the gate results]
+
+THE CODE IN QUESTION:
+[file path and relevant code section]
+
+DEBUG.md HISTORY:
+[paste relevant entries from DEBUG.md so the council doesn't suggest already-failed approaches]
+
+QUESTION FOR THE COUNCIL:
+Should we (A) update INTENT.md to match Codex's fix, or (B) revert Codex's fix and keep the original intent?
+```
+
+**Step 3 — Execute the verdict:**
+- Verdict A (update intent): Update the INTENT.md entry. Commit: "Update intent: [function] — council verdict [round N]"
+- Verdict B (revert fix): Revert Codex's fix commit. Commit: "Revert codex fix: [function] — council verdict preserves original intent"
+- Log full decision + reasoning in DEBUG.md
+- Continue to next wave after all conflicts are resolved

package/ftm-executor/references/protocols/DOCUMENTATION-BOOTSTRAP.md

@@ -0,0 +1,36 @@
+# Phase 1.5 — Documentation Layer Bootstrap
+
+## Purpose
+
+Before dispatching any agents, ensure the project has the required documentation layer. This bootstrap runs once at the start of execution. If all files already exist, skip this phase entirely.
+
+## Files to Check and Create
+
+**1. INTENT.md** (project root)
+
+If missing, bootstrap from the plan's Vision and Architecture Decisions sections. Use the ftm-intent skill's root template format.
+
+**2. ARCHITECTURE.mmd** (project root)
+
+If missing, bootstrap by scanning the codebase for modules and their import relationships. Use the ftm-diagram skill's root template format.
+
+**3. STYLE.md** (project root)
+
+If missing, copy from `~/.claude/skills/ftm-executor/references/STYLE-TEMPLATE.md` into the project root.
+
+**4. DEBUG.md** (project root)
+
+If missing, create with this header:
+
+```markdown
+# Debug Log
+
+Failed approaches and their outcomes. Append here — never retry what's already logged.
+```
+
+## Bootstrap Rules
+
+- Check all four files first, then create only the ones that are missing
+- Do not overwrite existing files — presence check only
+- Creation order: STYLE.md (copy) → DEBUG.md (header only) → INTENT.md (plan-derived) → ARCHITECTURE.mmd (scan-derived)
+- Bootstrap content is minimal scaffolding — agents will expand it as they work

package/ftm-executor/references/protocols/MODEL-PROFILE.md

@@ -0,0 +1,44 @@
+# Phase 0.7 — Model Profile Loading
+
+## Reading ftm-config.yml
+
+Read `~/.claude/ftm-config.yml` to determine which models to use when spawning agents. If the file doesn't exist, use these balanced defaults:
+
+| Role | Default Model |
+|------|--------------|
+| Planning agents | opus |
+| Execution agents | sonnet |
+| Review/audit agents | sonnet |
+
+## Model Assignment by Phase
+
+When spawning agents in subsequent phases, pass the `model` parameter based on role:
+
+| Phase | Agent Role | Model Key |
+|-------|-----------|-----------|
+| Phase 0.5 (plan checking) | Planning | `planning` |
+| Phase 2 (team assembly) | Planning | `planning` |
+| Phase 4 (task execution) | Execution | `execution` |
+| Phase 4.5 (audit) | Review | `review` |
+
+If the profile specifies `inherit` for a role, omit the `model` parameter entirely — the agent uses the session default.
+
+## Example ftm-config.yml Structure
+
+```yaml
+active_profile: balanced
+
+profiles:
+  balanced:
+    planning: opus
+    execution: sonnet
+    review: sonnet
+  fast:
+    planning: sonnet
+    execution: sonnet
+    review: sonnet
+  quality:
+    planning: opus
+    execution: opus
+    review: opus
+```

package/ftm-executor/references/protocols/PROGRESS-TRACKING.md

@@ -0,0 +1,66 @@
+# Progress Tracking — PROGRESS.md Template and Update Rules
+
+## Enabling Progress Tracking
+
+If `progress_tracking` is enabled in `~/.claude/ftm-config.yml` (default: true), create `PROGRESS.md` in the project root at the start of Phase 3.5.
+
+## Initial File Template
+
+Create the file with this structure, filling in plan details:
+
+```markdown
+# FTM Executor — Progress
+
+**Plan:** [plan title]
+**Started:** [timestamp]
+**Status:** IN PROGRESS
+
+## Execution Summary
+| Wave | Tasks | Status | Started | Completed |
+|------|-------|--------|---------|-----------|
+| 1 | [task list] | PENDING | — | — |
+| 2 | [task list] | PENDING | — | — |
+| ... | | | | |
+
+## Task Status
+| # | Title | Agent | Status | Audit | Notes |
+|---|-------|-------|--------|-------|-------|
+| 1 | [title] | [agent] | PENDING | — | |
+| 2 | [title] | [agent] | PENDING | — | |
+| ... | | | | | |
+
+## Activity Log
+[reverse chronological — newest first]
+```
+
+## Update Events
+
+Update PROGRESS.md at these events:
+
+- **Wave starts** → update wave status to `IN PROGRESS`, add timestamp to Started column
+- **Task agent returns** → update task status to `COMPLETE` or `FAILED`, add audit result
+- **Wave completes** → update wave status to `COMPLETE`, add timestamp to Completed column
+- **Merge completes** → add to activity log
+- **Errors/blockers** → add to activity log with details
+
+## Activity Log Format
+
+Each entry uses this format:
+```
+### [HH:MM] [event type]
+[brief description]
+```
+
+Example entries (newest first):
+```
+### 14:32 Wave 1 complete
+Tasks 1-4 merged to main. All audits passed. 2 auto-fixes applied.
+
+### 14:15 Task 3 audit — auto-fix
+Added missing import for UserPreferences in SettingsView.tsx
+
+### 13:45 Wave 1 started
+Dispatching 4 agents in parallel: frontend (tasks 1,2), backend (task 3), testing (task 4)
+```
+
+This file is for human consumption — the user can check it at any time without interrupting execution. Keep entries concise and informative.