Document common mecatui delegation workflows
@danbarr is already working on this.
Since Sep 18, 2026.
- Dominant language
- Go
- Stars
- 152
- Forks
- 16
- Avg merge
- 14h 48m
- Merged PRs (30d)
- 536
Description
Summary
Document common, real-world mecatui delegation workflows for people running Mecatl locally or connecting mecatui to a shared remote service. This is independent of the public-documentation IA restructuring.
The goal is to help people decide when to use their main session, Subagents, Parallel branches, or Teams; start the right mode through a normal prompt; and monitor the work from mecatui.
Proposed documentation
Add a task-oriented mecatui guide (for example, Work with delegated agents) that:
- gives a concise decision guide for the main session, Subagents, Parallel, and Teams;
- explains each mode through realistic workloads, including bounded investigation, independent implementation, and a read-only panel review of a shared working tree or diff;
- provides clearly labeled Copy this prompt into Mecatl examples, including an optional mode-selection prompt that asks Mecatl to recommend a mode before it changes anything;
- explains that people initiate delegation through a normal prompt rather than a dedicated TUI workflow;
- documents live supervision in
mecatui:f6for the Agents overlay,/teamfor its Teams tab, footer counts,ctrl+tfor bounded child/tool details, andxto cancel a background child; - distinguishes
/agents(named-agent-definition inventory) from the live delegation monitor; - states that connected-server capabilities and policy govern availability for remote sessions.
Scope and ownership
Keep the guide procedural and user-task-focused under user-docs/mecatui/. Link to the canonical capability material in user-docs/features/subagents-and-teams.md for lifecycle, workspace, isolation, direct-write, merge, and API semantics. Do not duplicate those implementation details per workflow.
Non-goals
- Change delegation behavior or build a new UI.
- Document builder extension points or SDK APIs.
- Treat Parallel temporary workspaces as a persistent manual-review workflow.
Acceptance criteria
- A reader can select an appropriate delegation mode for at least investigation, isolated implementation, and collaborative/panel review work.
- Every documented guided task includes an actionable prompt and a way to monitor or cancel the work in
mecatui. - The guide accurately distinguishes
/agentsfrom thef6live Agents overlay. - Shared delegation semantics remain canonical in the Capabilities documentation rather than being cloned into the guide.
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Assessment
This issue has not been assessed yet.