feed-the-machine 1.5.0 → 1.6.0

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

@@ -1,66 +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.
+# 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

@@ -1,73 +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
+# 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

@@ -1,36 +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
+# 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

@@ -1,44 +1,59 @@
-# 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
-```
+# Phase 0.7 — Model Profile and Agent Mode Loading
+
+## Reading ftm-config.yml
+
+Read `~/.claude/ftm-config.yml` to determine which models and permission mode 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.
+
+## Agent Permission Mode
+
+Read `execution.agent_mode` from ftm-config.yml. Pass this as the `mode` parameter on **every** Agent tool call in all phases. This controls the permission level for spawned agents.
+
+| Value | Behavior |
+|-------|----------|
+| `bypassPermissions` | Agent runs without prompting user (default) |
+| `acceptEdits` | Agent can edit files but prompts for other actions |
+| `dontAsk` | Agent makes all decisions autonomously |
+| `default` | Uses Claude Code's default permission behavior |
+| `auto` | Automatic permission selection |
+
+If `agent_mode` is not set in config, default to `bypassPermissions`.
+
+## Example ftm-config.yml Structure
+
+```yaml
+execution:
+  agent_mode: bypassPermissions   # permission mode for all spawned agents
+
+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

@@ -1,66 +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.
+# 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.