stacklok / stacklok/mecatl

Document common mecatui delegation workflows

Open
#1,718 0 comments 0 reactions 1 assignee View on GitHub

@danbarr is already working on this.

Since Sep 18, 2026.

documentation
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: f6 for the Agents overlay, /team for its Teams tab, footer counts, ctrl+t for bounded child/tool details, and x to 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 /agents from the f6 live Agents overlay.
  • Shared delegation semantics remain canonical in the Capabilities documentation rather than being cloned into the guide.

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.