Skills — workstream pipeline

Claude-native (Tier A)

Skills are a Claude Code feature — a way to orchestrate a subagent chain. They are the Tier A implementation of the seven workstreams. Single-agent (Tier B) clients — Codex, Gemini, Cursor, Copilot — run the same seven workstreams sequentially from AGENTS.md + MCP calls; they have no skill files and must not invent them. See the Tier B digest and the agents standard.

A skill is a SKILL.md file that orchestrates an agent chain for a specific workstream. Skills live in .claude/skills/<name>/SKILL.md inside a repo. When a command is invoked, it calls the matching skill, which drives the agent chain to completion.

Skills do not call tools directly (tools: []). They define the pipeline — which agents run in what order, with what prompts, and what gates must pass.

---

Format

---
name: workstream-build
description: Orchestrates planner → coder → reviewer → documenter → human approve for net-new work
tools: []
---

# workstream-build

Prose describing the pipeline, steps, hard rules, and handoff payload schema.

---

The handoff payload

Every workstream passes a JSON payload between agents. The handoff skill validates it at each agent boundary before the next agent is invoked.

Required fields in every payload:

Field	Type	Notes
workstream	string	build, review, refactor, test, document, investigate, operate
task_description	string	Non-empty
files_changed	array	May be empty; strings
cycle_count	integer	>= 0; handoff halts at >= 3

If cycle_count reaches 3, the handoff skill halts and escalates to the human. The coder ↔ reviewer loop is capped at 2 cycles by all workstream skills.

---

Available skills

Nine skills are instantiated in D:\git\platform\.claude\skills\. They are also the template source for per-repo workstream pipeline setup — copy from templates/claude/skills/.

workstream-build

Command: /build
Chain: planner (conditional) → coder → reviewer → documenter → human approve

Invoke the planner if the task touches more than 3 files, exceeds 1 hour, or introduces a new module or public API. Otherwise skip it.

The cross-family reviewer requirement applies: the reviewer must run on a different model family than the coder. If both are Anthropic models, the reviewer agent acknowledges this and documents the limitation; findings are not suppressed.

verdict=block from the reviewer stops the chain. verdict=request_changes returns to the coder (max 2 cycles).

---

workstream-review

Command: /review
Chain: reviewer only (advisory — no human approve step)

Standalone review of an existing diff or PR. Constructs a minimal handoff payload from the diff if none exists. Findings are returned to the human; the human decides next steps.

---

workstream-refactor

Command: /refactor
Chain: coder → reviewer → documenter (conditional) → human approve

Hard rule: no behavioral changes. If the reviewer returns verdict=block with a BEHAVIORAL CHANGE prefix, the chain stops and the work must restart as /build.

The documenter only runs if a public API signature changed.

---

workstream-test

Command: /test
Chain: test-writer → reviewer → human approve

Hard rule: no production code changes. After the test-writer returns, files_changed is scanned for non-test paths. If any are found, the chain halts immediately.

If the test task description does not specify what to cover, the command asks for clarification before invoking the skill.

---

workstream-document

Command: /document
Chain: documenter → self-review → human approve

Hard rule: documentation files only. The documenter may only touch *.md, *.rst, docstrings, and JSDoc/TSDoc comments. Source logic changes block the chain.

The self-reviewer uses the same model family as the documenter (this is a quality/accuracy check, not an independence check).

---

workstream-investigate

Command: /investigate
Chain: investigator → human review (no code changes, no human approve)

Hard rule: read-only. The investigator may not write, edit, or delete any file. It produces structured findings: confirmed facts vs. hypotheses with confidence levels.

The chain ends at human review. If the human wants to act on the findings, they use /build, /refactor, or /test.

---

workstream-operate

Command: /operate
Chain: operator → security-reviewer (different model family) → documenter → human approve (REQUIRED)

Human approval is non-skippable. The human must type APPROVE verbatim. Any other response aborts the chain.

The security-reviewer must be from a different model family than the operator. This is an independence requirement, not a preference.

Every run appends a record to .claude/logs/operate.jsonl. The documenter is responsible for this. Logging cannot be skipped.

Destructive actions (delete, drop, terminate, revoke) must be listed in destructive_actions in the handoff payload and individually acknowledged by the human at the approval step.

---

handoff

Not invoked directly — called by workstream skills at every agent boundary.

Validates that the handoff payload is well-formed JSON, that all required fields are present, that cycle_count < 3, and that verdict=block includes a verdict_reason. Returns the payload unchanged on pass; lists all validation errors on fail.

---

route-decision

Command: /route
Chain: router agent → dispatch to matched workstream skill

Classifies an incoming task into one of the seven workstreams and dispatches automatically. The human can override the classification.

If confidence=low or ambiguities is non-empty, the command surfaces the ambiguities and asks for clarification before dispatching.

---

Cross-family review — what it means

The cross-family requirement in workstream-build, workstream-refactor, workstream-review, and workstream-operate means the reviewer or security-reviewer must be from a different model family than the agent that produced the code or plan.

In the HCS estate, all agents are Anthropic models. The workstream skill documents this limitation in the reviewer's model_family_note output field but does not suppress findings. A future enhancement could route review to a non-Anthropic model via Azure AI Foundry.

---

Per-repo deployment

To deploy the workstream pipeline in a product repo:

1. Copy templates/claude/skills/ to <repo>/.claude/skills/.
2. Copy templates/claude/commands/ to <repo>/.claude/commands/.
3. Copy the 9 agents from templates/claude/agents/ to <repo>/.claude/agents/, prefixed with the repo's short name (e.g., turner-coder.md).
4. Add the operate.jsonl stub: <repo>/.claude/logs/operate.jsonl (empty file).
5. Wire hooks and settings.json from templates/claude/hooks/ and templates/claude/settings.json.template.

See Repo settings for the full per-repo structure.