contextstream-coach

Agent Coach Kit

The person is teaching you a piece of work they need again and again. Each time, do the work well, make giving feedback easy, and carry what they teach you into the next job.

Words

• Workflow: the recurring work (weekly-note). It has a goal: what good looks like every time.
• Job: one occasion of the work (weekly-note#4). It has an objective: what this one must achieve.
• Version: each draft you save (weekly-note#4/v2).
• Feedback: the person's own words about one version, kept exactly as said (weekly-note#4/f1). It is either reusable (later jobs too) or this job only.
• Guidance: your reading of reusable feedback (weekly-note/g3). The person can edit it, limit where it applies, retire it or remove it.

Everything lives in the person's ContextStream account. scripts/coach.py talks to it.

• Run it as python3 .agents/skills/contextstream-coach/scripts/coach.py, written coach.py below.
• coach.py needs network access. In Codex Cloud, run its commands with network access enabled. If one fails with "needs network access", run it again with network enabled.
• Run coach.py doctor once per task. If it fails, show its message and stop; setup is in the kit's README.

Each job

1. Find the workflow with coach.py list.
   • For new work, help the person turn a rough idea into a short goal: who it's for, the result they want, an example or two, and any limits.
   • Show the goal you propose in one line and ask only about what's missing. Then run coach.py create --name "..." --goal "...".
   • A rough goal is fine; it gets sharper as you go.
2. Propose the objective.
   • coach.py get WORKFLOW shows recent objectives, the guidance, what still needs attention in an open job, and any coaching preference the person set. Feedback it shows from earlier jobs is history: never apply it.
   • Show the objective you propose in one line, and ask only about what changed or is missing. If the person asked for quick coaching, state it in that line and go on.
   • Then run coach.py start-job WORKFLOW --objective "...". To pick up an open job, use coach.py context JOB.
3. Use what you were given. The context holds the goal, the active guidance, this job's own feedback, and approved examples. Each guidance item shows what the person actually said beside your earlier reading, plus any limit on where it applies.
   • Apply each guidance item that fits this job. If its limit says it doesn't apply here, say so.
   • Approved examples show what worked. Learn from them, but don't copy them: a different result can be just as good.
   • Feedback from other jobs is left out on purpose. Don't bring back one-off choices you remember from them.
4. Save the draft before you show it.
   • Text: coach.py save-output JOB --file draft.md --carry-note "...".
   • A linked artifact: --url https://... in place of --file.
   • An image, audio, video or document: --media PATH in place of --file.
   • A revision: add --revises VERSION.
   • The carry note says briefly what you kept from approvals and which feedback you applied.
   • Name the same items with --carried, one each: --carried g1:applied --carried f2:kept. g1 is guidance, f2 this job's feedback, #3/f1 an earlier job's; the how is kept, adapted, applied or not_applied. Items marked applied or kept stop showing as needing attention.
5. Show it with its version reference. In a line or two, say what changed since the last version and why, and what still needs attention.
6. Record each reaction. When the person reacts to a version, record their words exactly: coach.py add-feedback VERSION --kind correction|approval|direction --scope reusable|this-job --text "<their words>" --reading "<your reading>"
   • Recording the reaction is part of revising; tell them what you recorded rather than asking first whether to remember it.
   • Choose the scope from what they said, and say which in one line: "Saved for later jobs too; say 'just this job' if not." Ask only when a wrong guess would matter.
   • To change the scope later: coach.py rescope FEEDBACK --scope this-job|reusable.
   • When they approve one part, add --excerpt "...". For audio or video, add --from 0:34 --to 0:41.
   • When they repeat something already in the guidance, add --repeat-of GUIDANCE. That shows the coaching didn't stick.
7. Revise or finish.
   • When they're happy: coach.py close-job JOB --used VERSION.
   • To compare with the last job: coach.py compare JOB, then ask which is better.
   • As soon as they say, record their verdict with their words: coach.py verdict JOB --verdict better|same|worse --said "<their words>". Add --candidate VERSION when they judged a version other than the latest. It works before or after the job is closed.
   • The verdict is the person's choice.