* docs(skill): restructure around a delegation playbook
SKILL.md becomes a slim routing layer: a what-are-you-here-to-do section up
front, the pane/run/wait primitives, and four delegation rules that survive
even when the reference is skipped. Everything specific to running another
agent moves to references/delegation.md, which adds what the old text never
had: per-worker git worktree isolation, a delivery contract collected through
git instead of screen scraping, a launch-verification checklist, a babysit
loop, and a fan-out harvest with short per-worker timeouts so one stuck
worker cannot stall the round. Also replaces the last remaining 'claude -p'
example (the fan-out one #699 missed) and keeps every snippet valid under
both bash 3.2 and zsh.
* docs(skill): un-deadlock the fan-out harvest loop
Fresh read of SKILL.md and references/delegation.md. Every internal anchor
resolves and the two files agree on the primitives; three things did not
hold up:
- The harvest loop passed `--changed`, which cannot work there. `wait`
compares against the state standing when *that* wait began, so a worker
that reached `done` while you were waiting on a different one is already
in `done` when its own turn in the round comes up — refused, every round,
forever. Each pane runs one turn, so a standing `done` is this turn's;
drop the flag and note the one thing it was buying (a just-answered
`waiting` worker needs to leave that state before it is requeued).
- The same loop folded `wait`'s exit 1 into its 124 branch, so a pane that
died got requeued instead of reported — and requeued at full speed,
since a dead pane answers immediately. Split the three codes.
- SKILL.md described `--plain` unwrapping "a line the shell wrapped at
column 249" while two other passages state a pane is 120 columns.
Say "at the pane's width", as references/commands.md already does.
No typos or grammar slips found. Every bash block in both files parses
under bash 3.2 and zsh.
* docs(skill): two failure modes from the playbook's first live run
Dogfooded the delegation playbook end to end (worker reviewing this very
file). Two failures it hit that the text did not cover:
- A turn aborted by an API error emits no turn boundary, so the status
stands at 'working' forever and wait sleeps through it. Diagnose from
the screen's error line; recover by telling the still-alive interactive
session to continue.
- A short capture tail cuts off the spinner line and shows only the TUI's
always-present input box, which reads as idle. Tail 15+ lines and read
for the spinner; 'bottom looks like a prompt' is only evidence on a
shell pane.
`skills add` does not refresh a skill that is already installed, so the
one install line left existing users with no documented way forward.
Add the `skills update tty7` counterpart to both READMEs and give the
agent-skill page a short Updating section covering update and remove.
The in-app switch that wrote `~/.claude/skills/tty7-orchestration` was
removed in da6df70, before any release carried it — `git grep` finds it in
no tag. The changelog entry recording it landed the same day, written from
the branch's state rather than the tree's, and the documentation site (#478)
was then written from the changelog, so the feature reappeared on three
pages describing something the app has never shipped.
The orchestration page now says what is true: nothing is installed for you,
the agent-facing contract is `skills/tty7` and you add it yourself with
`npx skills add l0ng-ai/tty7`. That skill covers driving panes; `wait` is
documented on the orchestration page itself, so neither page promises what
the other holds.
38 pages under docs/, written against the source rather than the README:
config keys and their clamps from core::config, default keybindings from
ui::keymap, every CLI verb and flag from tty7-cli, agent aliases and
hook/fork/resume support from core::cli_agent, and Settings paths taken
from the actual en-US strings.
docs/features.md and its zh-CN translation are retired — everything in
them now lives in a page of its own, plus the two things they carried
that nothing else did (IME input, the performance notes). README and
README.zh-CN point at docs/ instead.
Screenshots and videos are placeholders for now: docs/images/placeholder.svg
with a caption naming what each shot should be.
Co-authored-by: l0ng-ai <24760907+l0ng-ai@users.noreply.github.com>
l0ng-ai
l0ng-aiandl0ng-ai