ac-framework 1.9.5 → 1.9.7

package/LICENSE

@@ -16,4 +16,5 @@ Copyright (c) 2026 Damola Akinleye
 Copyright (c) 2025 Jesse Vincent
 Copyright (c) 2024 Seth Hobson
 Copyright (c) 2026 Antigravity User
+Copyright (c) 2025 opencode
 (CREDITS)

package/README.md

@@ -141,18 +141,33 @@ Each role runs in turn against a shared, accumulating context so outputs from on
 | Command | Description |
 |---|---|
 | `acfm agents setup` | Install optional dependencies (`opencode` and `tmux`) |
+| `acfm agents doctor` | Validate OpenCode/tmux/model preflight before start |
 | `acfm agents install-mcps` | Install SynapseGrid MCP server for detected assistants |
 | `acfm agents uninstall-mcps` | Remove SynapseGrid MCP server from assistants |
-| `acfm agents start --task "..."` | Start a SynapseGrid collaborative session |
+| `acfm agents start --task "..." --model-coder provider/model` | Start session with optional per-role models |
 | `acfm agents resume` | Resume a previous session and recreate workers if needed |
 | `acfm agents list` | List recent SynapseGrid sessions |
 | `acfm agents attach` | Attach directly to the SynapseGrid tmux session |
+| `acfm agents live` | Attach to full live tmux view (all agents) |
 | `acfm agents logs` | Show recent worker logs (all roles or one role) |
 | `acfm agents export --format md --out file.md` | Export transcript in Markdown or JSON |
 | `acfm agents send "..."` | Send a new user message into the active session |
 | `acfm agents status` | Show current collaborative session state |
+| `acfm agents model get` | Show default model config (global and per-role) |
+| `acfm agents model set --role coder provider/model` | Persist a default model for one role |
+| `acfm agents model clear --role all` | Clear persisted model defaults |
 | `acfm agents stop` | Stop the active collaborative session |
 
+### SynapseGrid troubleshooting
+
+- If transcript entries show `Agent failed: spawn opencode ENOENT`, run `acfm agents setup` to install dependencies and then retry.
+- Attach to worker panes with `acfm agents live` (or `acfm agents attach`) to see real-time role discussion.
+- Inspect worker errors quickly with `acfm agents logs --role all --lines 120`.
+- MCP starts can now create tmux workers directly; if your assistant used headless steps before, start a new session and ensure worker spawning is enabled.
+- Configure role models directly at start (for example `--model-planner`, `--model-coder`) or persist defaults via `acfm agents model set`.
+- Default SynapseGrid model fallback is `opencode/minimax-m2.5-free`.
+- Run `acfm agents doctor` when panes look idle to confirm model/provider preflight health.
+
 ### Spec Workflow
 
 | Command | Description |

package/framework/mobile_development/.agent/workflows/ac.md

@@ -93,6 +93,46 @@ The AC Framework includes a persistent memory system that agents must use proact
 
 **User communication:** `Memory saved: [brief description]`
 
+### SynapseGrid Collaborative MCP Protocol (Optional)
+
+If SynapseGrid is enabled in `acfm init`, AC Framework installs the collaborative MCP server automatically for detected assistants.
+
+**Session-start requirement when collaboration is enabled:**
+1. Prefer the available SynapseGrid MCP tools for collaborative session control before falling back to direct CLI.
+2. Use shared session state and transcript as the source of truth for role-by-role collaboration.
+3. If collaborative MCP is unavailable, use CLI fallback commands and keep behavior equivalent.
+
+**How to use SynapseGrid collaboration:**
+```text
+Preferred: use SynapseGrid MCP tools (ac-framework-collab) for start/status/step/resume/stop.
+Fallback: use AC Framework agents CLI commands directly.
+```
+```bash
+# Install/update collaborative MCP server integrations
+acfm agents install-mcps
+
+# Start collaborative runtime with visible 4-pane tmux war-room
+acfm agents start --task "design and implement feature X" --attach --model-coder provider/model
+
+# If already running in background, attach to panes and inspect logs
+acfm agents live
+acfm agents logs --role all --lines 120
+
+# Resume/list/export operations
+acfm agents resume
+acfm agents list
+acfm agents export --format md --out synapse-session.md
+
+# Fast diagnostics for OpenCode resolution errors
+acfm agents setup
+```
+
+**Troubleshooting notes:**
+- If transcript shows `Agent failed: spawn opencode ENOENT`, run `acfm agents setup` and restart/resume session.
+- If session exists but panes are not visible, use `acfm agents live` (or `acfm agents attach`) or `tmux attach -t <session-name>`.
+- For MCP-first flows, ensure session start enables worker spawning so tmux panes are created.
+- Per-role models can be set at start (`--model-planner`, `--model-critic`, `--model-coder`, `--model-reviewer`) or persisted via `acfm agents model set`.
+
 ## SynapseGrid Collaborative MCP Protocol (Optional)
 
 If SynapseGrid is enabled in `acfm init`, AC Framework installs the collaborative MCP server automatically for detected assistants.
@@ -104,22 +144,35 @@ If SynapseGrid is enabled in `acfm init`, AC Framework installs the collaborativ
 
 **How to use SynapseGrid collaboration:**
 ```text
-Preferred: use SynapseGrid MCP tools (ac-framework-collab) for session start/status/step/stop.
+Preferred: use SynapseGrid MCP tools (ac-framework-collab) for start/status/step/resume/stop.
 Fallback: use AC Framework agents CLI commands directly.
 ```
 ```bash
-# Optional install/reinstall of collaborative MCP servers
+# Install/update collaborative MCP server integrations
 acfm agents install-mcps
 
-# Start collaborative runtime manually
-acfm agents start --task "design and implement feature X"
+# Start collaborative runtime with visible 4-pane tmux war-room
+acfm agents start --task "design and implement feature X" --attach --model-coder provider/model
+
+# If already running in background, attach to panes and inspect logs
+acfm agents live
+acfm agents logs --role all --lines 120
 
 # Resume/list/export operations
 acfm agents resume
 acfm agents list
 acfm agents export --format md --out synapse-session.md
+
+# Fast diagnostics for OpenCode resolution errors
+acfm agents setup
 ```
 
+**Troubleshooting notes:**
+- If transcript shows `Agent failed: spawn opencode ENOENT`, run `acfm agents setup` and restart/resume session.
+- If session exists but panes are not visible, use `acfm agents live` (or `acfm agents attach`) or `tmux attach -t <session-name>`.
+- For MCP-first flows, ensure session start enables worker spawning so tmux panes are created.
+- Per-role models can be set at start (`--model-planner`, `--model-critic`, `--model-coder`, `--model-reviewer`) or persisted via `acfm agents model set`.
+
 ---
 
 ## CRITICAL: How to Use Skills - ZERO SKIP POLICY

package/framework/mobile_development/.amazonq/prompts/ac.md

@@ -93,6 +93,46 @@ The AC Framework includes a persistent memory system that agents must use proact
 
 **User communication:** `Memory saved: [brief description]`
 
+### SynapseGrid Collaborative MCP Protocol (Optional)
+
+If SynapseGrid is enabled in `acfm init`, AC Framework installs the collaborative MCP server automatically for detected assistants.
+
+**Session-start requirement when collaboration is enabled:**
+1. Prefer the available SynapseGrid MCP tools for collaborative session control before falling back to direct CLI.
+2. Use shared session state and transcript as the source of truth for role-by-role collaboration.
+3. If collaborative MCP is unavailable, use CLI fallback commands and keep behavior equivalent.
+
+**How to use SynapseGrid collaboration:**
+```text
+Preferred: use SynapseGrid MCP tools (ac-framework-collab) for start/status/step/resume/stop.
+Fallback: use AC Framework agents CLI commands directly.
+```
+```bash
+# Install/update collaborative MCP server integrations
+acfm agents install-mcps
+
+# Start collaborative runtime with visible 4-pane tmux war-room
+acfm agents start --task "design and implement feature X" --attach --model-coder provider/model
+
+# If already running in background, attach to panes and inspect logs
+acfm agents live
+acfm agents logs --role all --lines 120
+
+# Resume/list/export operations
+acfm agents resume
+acfm agents list
+acfm agents export --format md --out synapse-session.md
+
+# Fast diagnostics for OpenCode resolution errors
+acfm agents setup
+```
+
+**Troubleshooting notes:**
+- If transcript shows `Agent failed: spawn opencode ENOENT`, run `acfm agents setup` and restart/resume session.
+- If session exists but panes are not visible, use `acfm agents live` (or `acfm agents attach`) or `tmux attach -t <session-name>`.
+- For MCP-first flows, ensure session start enables worker spawning so tmux panes are created.
+- Per-role models can be set at start (`--model-planner`, `--model-critic`, `--model-coder`, `--model-reviewer`) or persisted via `acfm agents model set`.
+
 ## SynapseGrid Collaborative MCP Protocol (Optional)
 
 If SynapseGrid is enabled in `acfm init`, AC Framework installs the collaborative MCP server automatically for detected assistants.
@@ -104,22 +144,35 @@ If SynapseGrid is enabled in `acfm init`, AC Framework installs the collaborativ
 
 **How to use SynapseGrid collaboration:**
 ```text
-Preferred: use SynapseGrid MCP tools (ac-framework-collab) for session start/status/step/stop.
+Preferred: use SynapseGrid MCP tools (ac-framework-collab) for start/status/step/resume/stop.
 Fallback: use AC Framework agents CLI commands directly.
 ```
 ```bash
-# Optional install/reinstall of collaborative MCP servers
+# Install/update collaborative MCP server integrations
 acfm agents install-mcps
 
-# Start collaborative runtime manually
-acfm agents start --task "design and implement feature X"
+# Start collaborative runtime with visible 4-pane tmux war-room
+acfm agents start --task "design and implement feature X" --attach --model-coder provider/model
+
+# If already running in background, attach to panes and inspect logs
+acfm agents live
+acfm agents logs --role all --lines 120
 
 # Resume/list/export operations
 acfm agents resume
 acfm agents list
 acfm agents export --format md --out synapse-session.md
+
+# Fast diagnostics for OpenCode resolution errors
+acfm agents setup
 ```
 
+**Troubleshooting notes:**
+- If transcript shows `Agent failed: spawn opencode ENOENT`, run `acfm agents setup` and restart/resume session.
+- If session exists but panes are not visible, use `acfm agents live` (or `acfm agents attach`) or `tmux attach -t <session-name>`.
+- For MCP-first flows, ensure session start enables worker spawning so tmux panes are created.
+- Per-role models can be set at start (`--model-planner`, `--model-critic`, `--model-coder`, `--model-reviewer`) or persisted via `acfm agents model set`.
+
 ---
 
 ## CRITICAL: How to Use Skills - ZERO SKIP POLICY

package/framework/mobile_development/.antigravity/workflows/ac.md

@@ -93,6 +93,46 @@ The AC Framework includes a persistent memory system that agents must use proact
 
 **User communication:** `Memory saved: [brief description]`
 
+### SynapseGrid Collaborative MCP Protocol (Optional)
+
+If SynapseGrid is enabled in `acfm init`, AC Framework installs the collaborative MCP server automatically for detected assistants.
+
+**Session-start requirement when collaboration is enabled:**
+1. Prefer the available SynapseGrid MCP tools for collaborative session control before falling back to direct CLI.
+2. Use shared session state and transcript as the source of truth for role-by-role collaboration.
+3. If collaborative MCP is unavailable, use CLI fallback commands and keep behavior equivalent.
+
+**How to use SynapseGrid collaboration:**
+```text
+Preferred: use SynapseGrid MCP tools (ac-framework-collab) for start/status/step/resume/stop.
+Fallback: use AC Framework agents CLI commands directly.
+```
+```bash
+# Install/update collaborative MCP server integrations
+acfm agents install-mcps
+
+# Start collaborative runtime with visible 4-pane tmux war-room
+acfm agents start --task "design and implement feature X" --attach --model-coder provider/model
+
+# If already running in background, attach to panes and inspect logs
+acfm agents live
+acfm agents logs --role all --lines 120
+
+# Resume/list/export operations
+acfm agents resume
+acfm agents list
+acfm agents export --format md --out synapse-session.md
+
+# Fast diagnostics for OpenCode resolution errors
+acfm agents setup
+```
+
+**Troubleshooting notes:**
+- If transcript shows `Agent failed: spawn opencode ENOENT`, run `acfm agents setup` and restart/resume session.
+- If session exists but panes are not visible, use `acfm agents live` (or `acfm agents attach`) or `tmux attach -t <session-name>`.
+- For MCP-first flows, ensure session start enables worker spawning so tmux panes are created.
+- Per-role models can be set at start (`--model-planner`, `--model-critic`, `--model-coder`, `--model-reviewer`) or persisted via `acfm agents model set`.
+
 ## SynapseGrid Collaborative MCP Protocol (Optional)
 
 If SynapseGrid is enabled in `acfm init`, AC Framework installs the collaborative MCP server automatically for detected assistants.
@@ -104,22 +144,35 @@ If SynapseGrid is enabled in `acfm init`, AC Framework installs the collaborativ
 
 **How to use SynapseGrid collaboration:**
 ```text
-Preferred: use SynapseGrid MCP tools (ac-framework-collab) for session start/status/step/stop.
+Preferred: use SynapseGrid MCP tools (ac-framework-collab) for start/status/step/resume/stop.
 Fallback: use AC Framework agents CLI commands directly.
 ```
 ```bash
-# Optional install/reinstall of collaborative MCP servers
+# Install/update collaborative MCP server integrations
 acfm agents install-mcps
 
-# Start collaborative runtime manually
-acfm agents start --task "design and implement feature X"
+# Start collaborative runtime with visible 4-pane tmux war-room
+acfm agents start --task "design and implement feature X" --attach --model-coder provider/model
+
+# If already running in background, attach to panes and inspect logs
+acfm agents live
+acfm agents logs --role all --lines 120
 
 # Resume/list/export operations
 acfm agents resume
 acfm agents list
 acfm agents export --format md --out synapse-session.md
+
+# Fast diagnostics for OpenCode resolution errors
+acfm agents setup
 ```
 
+**Troubleshooting notes:**
+- If transcript shows `Agent failed: spawn opencode ENOENT`, run `acfm agents setup` and restart/resume session.
+- If session exists but panes are not visible, use `acfm agents live` (or `acfm agents attach`) or `tmux attach -t <session-name>`.
+- For MCP-first flows, ensure session start enables worker spawning so tmux panes are created.
+- Per-role models can be set at start (`--model-planner`, `--model-critic`, `--model-coder`, `--model-reviewer`) or persisted via `acfm agents model set`.
+
 ---
 
 ## CRITICAL: How to Use Skills - ZERO SKIP POLICY

package/framework/mobile_development/.augment/commands/ac.md

@@ -93,6 +93,46 @@ The AC Framework includes a persistent memory system that agents must use proact
 
 **User communication:** `Memory saved: [brief description]`
 
+### SynapseGrid Collaborative MCP Protocol (Optional)
+
+If SynapseGrid is enabled in `acfm init`, AC Framework installs the collaborative MCP server automatically for detected assistants.
+
+**Session-start requirement when collaboration is enabled:**
+1. Prefer the available SynapseGrid MCP tools for collaborative session control before falling back to direct CLI.
+2. Use shared session state and transcript as the source of truth for role-by-role collaboration.
+3. If collaborative MCP is unavailable, use CLI fallback commands and keep behavior equivalent.
+
+**How to use SynapseGrid collaboration:**
+```text
+Preferred: use SynapseGrid MCP tools (ac-framework-collab) for start/status/step/resume/stop.
+Fallback: use AC Framework agents CLI commands directly.
+```
+```bash
+# Install/update collaborative MCP server integrations
+acfm agents install-mcps
+
+# Start collaborative runtime with visible 4-pane tmux war-room
+acfm agents start --task "design and implement feature X" --attach --model-coder provider/model
+
+# If already running in background, attach to panes and inspect logs
+acfm agents live
+acfm agents logs --role all --lines 120
+
+# Resume/list/export operations
+acfm agents resume
+acfm agents list
+acfm agents export --format md --out synapse-session.md
+
+# Fast diagnostics for OpenCode resolution errors
+acfm agents setup
+```
+
+**Troubleshooting notes:**
+- If transcript shows `Agent failed: spawn opencode ENOENT`, run `acfm agents setup` and restart/resume session.
+- If session exists but panes are not visible, use `acfm agents live` (or `acfm agents attach`) or `tmux attach -t <session-name>`.
+- For MCP-first flows, ensure session start enables worker spawning so tmux panes are created.
+- Per-role models can be set at start (`--model-planner`, `--model-critic`, `--model-coder`, `--model-reviewer`) or persisted via `acfm agents model set`.
+
 ## SynapseGrid Collaborative MCP Protocol (Optional)
 
 If SynapseGrid is enabled in `acfm init`, AC Framework installs the collaborative MCP server automatically for detected assistants.
@@ -104,22 +144,35 @@ If SynapseGrid is enabled in `acfm init`, AC Framework installs the collaborativ
 
 **How to use SynapseGrid collaboration:**
 ```text
-Preferred: use SynapseGrid MCP tools (ac-framework-collab) for session start/status/step/stop.
+Preferred: use SynapseGrid MCP tools (ac-framework-collab) for start/status/step/resume/stop.
 Fallback: use AC Framework agents CLI commands directly.
 ```
 ```bash
-# Optional install/reinstall of collaborative MCP servers
+# Install/update collaborative MCP server integrations
 acfm agents install-mcps
 
-# Start collaborative runtime manually
-acfm agents start --task "design and implement feature X"
+# Start collaborative runtime with visible 4-pane tmux war-room
+acfm agents start --task "design and implement feature X" --attach --model-coder provider/model
+
+# If already running in background, attach to panes and inspect logs
+acfm agents live
+acfm agents logs --role all --lines 120
 
 # Resume/list/export operations
 acfm agents resume
 acfm agents list
 acfm agents export --format md --out synapse-session.md
+
+# Fast diagnostics for OpenCode resolution errors
+acfm agents setup
 ```
 
+**Troubleshooting notes:**
+- If transcript shows `Agent failed: spawn opencode ENOENT`, run `acfm agents setup` and restart/resume session.
+- If session exists but panes are not visible, use `acfm agents live` (or `acfm agents attach`) or `tmux attach -t <session-name>`.
+- For MCP-first flows, ensure session start enables worker spawning so tmux panes are created.
+- Per-role models can be set at start (`--model-planner`, `--model-critic`, `--model-coder`, `--model-reviewer`) or persisted via `acfm agents model set`.
+
 ---
 
 ## CRITICAL: How to Use Skills - ZERO SKIP POLICY

package/framework/mobile_development/.claude/commands/opsx/ac.md

@@ -93,6 +93,46 @@ The AC Framework includes a persistent memory system that agents must use proact
 
 **User communication:** `Memory saved: [brief description]`
 
+### SynapseGrid Collaborative MCP Protocol (Optional)
+
+If SynapseGrid is enabled in `acfm init`, AC Framework installs the collaborative MCP server automatically for detected assistants.
+
+**Session-start requirement when collaboration is enabled:**
+1. Prefer the available SynapseGrid MCP tools for collaborative session control before falling back to direct CLI.
+2. Use shared session state and transcript as the source of truth for role-by-role collaboration.
+3. If collaborative MCP is unavailable, use CLI fallback commands and keep behavior equivalent.
+
+**How to use SynapseGrid collaboration:**
+```text
+Preferred: use SynapseGrid MCP tools (ac-framework-collab) for start/status/step/resume/stop.
+Fallback: use AC Framework agents CLI commands directly.
+```
+```bash
+# Install/update collaborative MCP server integrations
+acfm agents install-mcps
+
+# Start collaborative runtime with visible 4-pane tmux war-room
+acfm agents start --task "design and implement feature X" --attach --model-coder provider/model
+
+# If already running in background, attach to panes and inspect logs
+acfm agents live
+acfm agents logs --role all --lines 120
+
+# Resume/list/export operations
+acfm agents resume
+acfm agents list
+acfm agents export --format md --out synapse-session.md
+
+# Fast diagnostics for OpenCode resolution errors
+acfm agents setup
+```
+
+**Troubleshooting notes:**
+- If transcript shows `Agent failed: spawn opencode ENOENT`, run `acfm agents setup` and restart/resume session.
+- If session exists but panes are not visible, use `acfm agents live` (or `acfm agents attach`) or `tmux attach -t <session-name>`.
+- For MCP-first flows, ensure session start enables worker spawning so tmux panes are created.
+- Per-role models can be set at start (`--model-planner`, `--model-critic`, `--model-coder`, `--model-reviewer`) or persisted via `acfm agents model set`.
+
 ## SynapseGrid Collaborative MCP Protocol (Optional)
 
 If SynapseGrid is enabled in `acfm init`, AC Framework installs the collaborative MCP server automatically for detected assistants.
@@ -104,22 +144,35 @@ If SynapseGrid is enabled in `acfm init`, AC Framework installs the collaborativ
 
 **How to use SynapseGrid collaboration:**
 ```text
-Preferred: use SynapseGrid MCP tools (ac-framework-collab) for session start/status/step/stop.
+Preferred: use SynapseGrid MCP tools (ac-framework-collab) for start/status/step/resume/stop.
 Fallback: use AC Framework agents CLI commands directly.
 ```
 ```bash
-# Optional install/reinstall of collaborative MCP servers
+# Install/update collaborative MCP server integrations
 acfm agents install-mcps
 
-# Start collaborative runtime manually
-acfm agents start --task "design and implement feature X"
+# Start collaborative runtime with visible 4-pane tmux war-room
+acfm agents start --task "design and implement feature X" --attach --model-coder provider/model
+
+# If already running in background, attach to panes and inspect logs
+acfm agents live
+acfm agents logs --role all --lines 120
 
 # Resume/list/export operations
 acfm agents resume
 acfm agents list
 acfm agents export --format md --out synapse-session.md
+
+# Fast diagnostics for OpenCode resolution errors
+acfm agents setup
 ```
 
+**Troubleshooting notes:**
+- If transcript shows `Agent failed: spawn opencode ENOENT`, run `acfm agents setup` and restart/resume session.
+- If session exists but panes are not visible, use `acfm agents live` (or `acfm agents attach`) or `tmux attach -t <session-name>`.
+- For MCP-first flows, ensure session start enables worker spawning so tmux panes are created.
+- Per-role models can be set at start (`--model-planner`, `--model-critic`, `--model-coder`, `--model-reviewer`) or persisted via `acfm agents model set`.
+
 ---
 
 ## CRITICAL: How to Use Skills - ZERO SKIP POLICY

package/framework/mobile_development/.cline/commands/opsx/ac.md

@@ -93,6 +93,46 @@ The AC Framework includes a persistent memory system that agents must use proact
 
 **User communication:** `Memory saved: [brief description]`
 
+### SynapseGrid Collaborative MCP Protocol (Optional)
+
+If SynapseGrid is enabled in `acfm init`, AC Framework installs the collaborative MCP server automatically for detected assistants.
+
+**Session-start requirement when collaboration is enabled:**
+1. Prefer the available SynapseGrid MCP tools for collaborative session control before falling back to direct CLI.
+2. Use shared session state and transcript as the source of truth for role-by-role collaboration.
+3. If collaborative MCP is unavailable, use CLI fallback commands and keep behavior equivalent.
+
+**How to use SynapseGrid collaboration:**
+```text
+Preferred: use SynapseGrid MCP tools (ac-framework-collab) for start/status/step/resume/stop.
+Fallback: use AC Framework agents CLI commands directly.
+```
+```bash
+# Install/update collaborative MCP server integrations
+acfm agents install-mcps
+
+# Start collaborative runtime with visible 4-pane tmux war-room
+acfm agents start --task "design and implement feature X" --attach --model-coder provider/model
+
+# If already running in background, attach to panes and inspect logs
+acfm agents live
+acfm agents logs --role all --lines 120
+
+# Resume/list/export operations
+acfm agents resume
+acfm agents list
+acfm agents export --format md --out synapse-session.md
+
+# Fast diagnostics for OpenCode resolution errors
+acfm agents setup
+```
+
+**Troubleshooting notes:**
+- If transcript shows `Agent failed: spawn opencode ENOENT`, run `acfm agents setup` and restart/resume session.
+- If session exists but panes are not visible, use `acfm agents live` (or `acfm agents attach`) or `tmux attach -t <session-name>`.
+- For MCP-first flows, ensure session start enables worker spawning so tmux panes are created.
+- Per-role models can be set at start (`--model-planner`, `--model-critic`, `--model-coder`, `--model-reviewer`) or persisted via `acfm agents model set`.
+
 ## SynapseGrid Collaborative MCP Protocol (Optional)
 
 If SynapseGrid is enabled in `acfm init`, AC Framework installs the collaborative MCP server automatically for detected assistants.
@@ -104,22 +144,35 @@ If SynapseGrid is enabled in `acfm init`, AC Framework installs the collaborativ
 
 **How to use SynapseGrid collaboration:**
 ```text
-Preferred: use SynapseGrid MCP tools (ac-framework-collab) for session start/status/step/stop.
+Preferred: use SynapseGrid MCP tools (ac-framework-collab) for start/status/step/resume/stop.
 Fallback: use AC Framework agents CLI commands directly.
 ```
 ```bash
-# Optional install/reinstall of collaborative MCP servers
+# Install/update collaborative MCP server integrations
 acfm agents install-mcps
 
-# Start collaborative runtime manually
-acfm agents start --task "design and implement feature X"
+# Start collaborative runtime with visible 4-pane tmux war-room
+acfm agents start --task "design and implement feature X" --attach --model-coder provider/model
+
+# If already running in background, attach to panes and inspect logs
+acfm agents live
+acfm agents logs --role all --lines 120
 
 # Resume/list/export operations
 acfm agents resume
 acfm agents list
 acfm agents export --format md --out synapse-session.md
+
+# Fast diagnostics for OpenCode resolution errors
+acfm agents setup
 ```
 
+**Troubleshooting notes:**
+- If transcript shows `Agent failed: spawn opencode ENOENT`, run `acfm agents setup` and restart/resume session.
+- If session exists but panes are not visible, use `acfm agents live` (or `acfm agents attach`) or `tmux attach -t <session-name>`.
+- For MCP-first flows, ensure session start enables worker spawning so tmux panes are created.
+- Per-role models can be set at start (`--model-planner`, `--model-critic`, `--model-coder`, `--model-reviewer`) or persisted via `acfm agents model set`.
+
 ---
 
 ## CRITICAL: How to Use Skills - ZERO SKIP POLICY

package/framework/mobile_development/.clinerules/workflows/ac.md

@@ -93,6 +93,46 @@ The AC Framework includes a persistent memory system that agents must use proact
 
 **User communication:** `Memory saved: [brief description]`
 
+### SynapseGrid Collaborative MCP Protocol (Optional)
+
+If SynapseGrid is enabled in `acfm init`, AC Framework installs the collaborative MCP server automatically for detected assistants.
+
+**Session-start requirement when collaboration is enabled:**
+1. Prefer the available SynapseGrid MCP tools for collaborative session control before falling back to direct CLI.
+2. Use shared session state and transcript as the source of truth for role-by-role collaboration.
+3. If collaborative MCP is unavailable, use CLI fallback commands and keep behavior equivalent.
+
+**How to use SynapseGrid collaboration:**
+```text
+Preferred: use SynapseGrid MCP tools (ac-framework-collab) for start/status/step/resume/stop.
+Fallback: use AC Framework agents CLI commands directly.
+```
+```bash
+# Install/update collaborative MCP server integrations
+acfm agents install-mcps
+
+# Start collaborative runtime with visible 4-pane tmux war-room
+acfm agents start --task "design and implement feature X" --attach --model-coder provider/model
+
+# If already running in background, attach to panes and inspect logs
+acfm agents live
+acfm agents logs --role all --lines 120
+
+# Resume/list/export operations
+acfm agents resume
+acfm agents list
+acfm agents export --format md --out synapse-session.md
+
+# Fast diagnostics for OpenCode resolution errors
+acfm agents setup
+```
+
+**Troubleshooting notes:**
+- If transcript shows `Agent failed: spawn opencode ENOENT`, run `acfm agents setup` and restart/resume session.
+- If session exists but panes are not visible, use `acfm agents live` (or `acfm agents attach`) or `tmux attach -t <session-name>`.
+- For MCP-first flows, ensure session start enables worker spawning so tmux panes are created.
+- Per-role models can be set at start (`--model-planner`, `--model-critic`, `--model-coder`, `--model-reviewer`) or persisted via `acfm agents model set`.
+
 ## SynapseGrid Collaborative MCP Protocol (Optional)
 
 If SynapseGrid is enabled in `acfm init`, AC Framework installs the collaborative MCP server automatically for detected assistants.
@@ -104,22 +144,35 @@ If SynapseGrid is enabled in `acfm init`, AC Framework installs the collaborativ
 
 **How to use SynapseGrid collaboration:**
 ```text
-Preferred: use SynapseGrid MCP tools (ac-framework-collab) for session start/status/step/stop.
+Preferred: use SynapseGrid MCP tools (ac-framework-collab) for start/status/step/resume/stop.
 Fallback: use AC Framework agents CLI commands directly.
 ```
 ```bash
-# Optional install/reinstall of collaborative MCP servers
+# Install/update collaborative MCP server integrations
 acfm agents install-mcps
 
-# Start collaborative runtime manually
-acfm agents start --task "design and implement feature X"
+# Start collaborative runtime with visible 4-pane tmux war-room
+acfm agents start --task "design and implement feature X" --attach --model-coder provider/model
+
+# If already running in background, attach to panes and inspect logs
+acfm agents live
+acfm agents logs --role all --lines 120
 
 # Resume/list/export operations
 acfm agents resume
 acfm agents list
 acfm agents export --format md --out synapse-session.md
+
+# Fast diagnostics for OpenCode resolution errors
+acfm agents setup
 ```
 
+**Troubleshooting notes:**
+- If transcript shows `Agent failed: spawn opencode ENOENT`, run `acfm agents setup` and restart/resume session.
+- If session exists but panes are not visible, use `acfm agents live` (or `acfm agents attach`) or `tmux attach -t <session-name>`.
+- For MCP-first flows, ensure session start enables worker spawning so tmux panes are created.
+- Per-role models can be set at start (`--model-planner`, `--model-critic`, `--model-coder`, `--model-reviewer`) or persisted via `acfm agents model set`.
+
 ---
 
 ## CRITICAL: How to Use Skills - ZERO SKIP POLICY