mirror of
https://github.com/l0ng-ai/tty7.git
synced 2026-09-21 16:02:20 +00:00
l0ng-ai
024d368925
* 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.
108 lines
4.1 KiB
Plaintext
108 lines
4.1 KiB
Plaintext
---
|
|
title: "The agent skill"
|
|
description: "Teaching a coding agent to use tty7 properly — including when not to."
|
|
---
|
|
|
|
The CLI is only half of the story. An agent has to know *when* reaching for a
|
|
pane beats running a command, and — more importantly — which panes it must not
|
|
touch. That is what the skill is for.
|
|
|
|
## Installing it
|
|
|
|
```bash
|
|
npx skills add l0ng-ai/tty7
|
|
```
|
|
|
|
The source lives at
|
|
[`skills/tty7/`](https://github.com/l0ng-ai/tty7/tree/main/skills/tty7) in the
|
|
repository: a `SKILL.md` and two references — the full command table, and a
|
|
delegation playbook the agent reads before handing work to another agent.
|
|
|
|
<Note>
|
|
This is the only skill tty7 has — nothing in **Settings → Agents** installs
|
|
one for you. Using the CLI to run *other* agents — a worker pane, `tty7 wait`,
|
|
collecting the result — is covered separately.
|
|
[Orchestration →](/agents/orchestration)
|
|
</Note>
|
|
|
|
## Updating it
|
|
|
|
`add` does not refresh a skill that is already installed — updating is its own
|
|
command, and the skill is named `tty7`:
|
|
|
|
```bash
|
|
npx skills update tty7 # this one
|
|
npx skills update # everything you have installed
|
|
```
|
|
|
|
The CLI records where each skill came from, so `update` re-downloads only what
|
|
has drifted. `npx skills remove tty7` takes it back out.
|
|
|
|
## What it teaches
|
|
|
|
### When to use a pane instead of a plain command
|
|
|
|
The Bash-style tool an agent already has is right for anything that starts, does
|
|
its job, and exits. A pane is right when:
|
|
|
|
- **It should not block.** A dev server, a watcher, `tail -f`, a long test run.
|
|
- **It is interactive or stateful.** A REPL, `ssh`, a database shell — anything
|
|
where you send, read, then send again. A pane keeps the session alive between
|
|
turns; a one-shot call cannot.
|
|
- **It needs a real TTY.** Programs that detect a pipe and change behaviour —
|
|
colour, progress bars, TUIs, `top`, raw mode.
|
|
- **The user should be able to watch.** Anything in a pane shows up live in
|
|
their window. That is often the whole point.
|
|
- **You are being asked about something you did not start.** "What's running in
|
|
that pane?", "why is port 3000 taken?", "what are my agents doing?"
|
|
|
|
### The safety rules
|
|
|
|
<Warning>
|
|
The panes on this machine are the user's real work, and some of them are other
|
|
coding agents mid-task. Anything the agent did not create is read-only.
|
|
</Warning>
|
|
|
|
- **Never `send` into a pane you did not open.** Keystrokes land in the middle
|
|
of whatever is happening there. Check `tty7 agents` first.
|
|
- **Never close a pane, tab, or workspace you did not create.**
|
|
- **Never `server stop` or `server restart`.** Every pane on the machine dies
|
|
with the server, including yours.
|
|
- **Never `tty7 server start` on your own initiative** when `doctor` says the
|
|
server is unreachable — starting one the user did not ask for changes what
|
|
their GUI attaches to. Tell them instead.
|
|
- **Clean up what you did create.** `tty7 pane close %83` when the scratch pane
|
|
is done with.
|
|
|
|
### The reliable idioms
|
|
|
|
Rather than screen-scraping, the skill points agents at the primitives that
|
|
actually answer the question:
|
|
|
|
```bash
|
|
# is it finished? — when only the depth-0 shell is left, yes
|
|
tty7 procs %83 --json
|
|
|
|
# the answer, not the view
|
|
tty7 send "$PANE" 'cargo test > /tmp/t.log 2>&1; echo $? > /tmp/t.rc' --enter
|
|
|
|
# wake up exactly when the other agent needs something
|
|
tty7 wait %3 --until waiting,done --changed --timeout 600
|
|
```
|
|
|
|
### How to delegate
|
|
|
|
`references/delegation.md` is the part the agent reads before spawning a
|
|
worker: give the worker its own git worktree and workspace, hand the task over
|
|
in interactive mode with the delivery contract in the prompt, prove the
|
|
command actually started, babysit with `tty7 wait`, collect the result out of
|
|
git rather than the screen, clean up — and, for a fan-out, harvest with short
|
|
per-worker timeouts so one stuck worker cannot stall the round.
|
|
|
|
## For humans writing their own tooling
|
|
|
|
The same material is worth reading even if you are not an agent — it is the
|
|
shortest description of how to use tty7 as a job runner. Start with the
|
|
[CLI overview](/cli/overview), then the
|
|
[command reference](/cli/reference).
|