workstream

Workstream

Run large, multi-step tasks across specialized subagents that hand off work verbatim. The shared thread.md is the medium — agents append full entries; the orchestrator only routes, it never summarizes. This avoids the lossy "orchestrator hands over a summary" pattern.

Core idea

• One workstream = one directory at <WORKSPACE>/.work/<Ymd-His>-<slug>/; the timestamped slug names it and lets you resume it later by slug.
• brief.md holds the request / context / expected outputs. thread.md is an append-only log.
• Each subagent reads brief.md + thread.md (verbatim), does its part, and appends one entry ending in Next steps that route to the next @role.
• The orchestrator (you, the main loop) reads only the latest Next steps to decide who runs next, and passes the directory path — never a summary.

Start or resume

A new workstream is opened only by invoking this skill. What you pass decides the action:

• Resume — if the argument matches an existing <WORKSPACE>/.work/*-<slug>/ dir (e.g. after a session restart), do not scaffold: open that dir and continue from the latest thread.md entry.
• New — otherwise, create one:
  1. Slug. If a bare slug was given, use it. If the argument is instead a task description / initial prompt, derive and propose a concise kebab-case slug from it (the user can override).
  2. Run this skill's scripts/new-workstream.sh <slug> to create <WORKSPACE>/.work/<Ymd-His>-<slug>/ and seed brief.md, thread.md, and PROTOCOL.md (the subagent contract is copied in, so the workstream is self-contained — subagents don't auto-load this skill). When installed as a plugin the script is at ${CLAUDE_PLUGIN_ROOT}/skills/workstream/scripts/new-workstream.sh.
  3. Fill in brief.md. If a prompt/context was provided, seed it there (Request + Context + expected outputs) verbatim — don't paraphrase away detail.

Then run the loop below until a next step routes to @done or @user.

Orchestrator loop (your only job)

Repeat:

1. Read the latest entry's ### Next steps in <dir>/thread.md.

2. For each step routed to a subagent role, spawn that subagent with a prompt like:

   Your workstream is <dir>. Read PROTOCOL.md, brief.md, and thread.md there, then action this next step: "". Append your entry per PROTOCOL.md.

   Pass the path only — never paste thread content or a summary into the prompt.

3. When a step is → @user, surface it to the user and wait.

You never summarize, merge, or rewrite entries — subagents read the verbatim thread themselves.

thread.md entry format

Defined in PROTOCOL.md. Each entry is: a numbered title line ## <n> — <Title> · @<role> · <Ymd-His>, a verbatim body, then a ### Next steps list where every item ends in → @role / → @user / → @done.

Consolidation

When the user asks to promote part of the work into a durable document (ADR, PRD, architecture spec):

1. Write the consolidated doc in its real home (e.g. docs/adr/NNNN-*.md), not under .work/.
2. In the workstream, replace the promoted content with a reference link to the new doc.
3. Append a thread entry noting what was consolidated and where it went.

.work/ is scratch (gitignored); consolidated docs are the durable, reviewed record.

Rules

• Never duplicate. Reference source files by path / path:line instead of pasting.
• Large artifacts (research, generated code, test output) get their own file in the workstream; thread.md links to them.
• Append-only: never edit or delete earlier thread entries.