The composer pipeline

Composer drives a task end to end. It picks the next ready task off the critical path, runs it through a per-task workflow, surfaces the review verdict, propagates the result through the graph, and loops until the queue is empty or you stop it.

The orchestrator is glue. It owns only the interactive seams: pick the task, resolve gates, run the merge gate, propagate. The heavy lifting runs inside a background workflow, off the orchestrator's context, that dispatches each phase to a fresh agent with its own tool set. Orchestration stays cheap because a growing transcript never sits in the main loop while phases run.

Commands

• /piyaz:composer runs backlog mode: the orchestrator picks the highest-value ready task each iteration and keeps going.
• /piyaz:composer <taskRef> runs single-task mode, for example /piyaz:composer ZIN-42. Same pipeline, one task, then exit.
• /piyaz:composer rework <taskRef|pr-url> runs rework mode: it takes the change requests you left on a GitHub PR and rounds them back through the fix loop. See Rework mode.

Once per session, before the first task, composer asks for a merge policy (see The merge gate). That single choice is the only thing it confirms up front.

For example, compose a single task, then round any review changes you left on its PR back through the fix loop:

/piyaz:composer MET-1

/piyaz:composer rework MET-1

The per-task workflow

Each iteration runs its task through one background workflow. The workflow runs the phases in order and returns a single structured result; the orchestrator waits without spending context tokens while it works.

research → plan → implement → CI gate → review → [fix loop ≤2 rotations]

Research

The researcher reads the target task, maps it to the codebase (files to touch, patterns to reuse, tests that cover them), checks current library docs against the project's pinned versions, audits the project's conventions (commit format, test/lint/typecheck commands, PR template), and reasons about security, performance, reliability, and observability.

It writes refinements directly back to the task: a sharper description, binary acceptance criteria, missing tags, an accurate estimate. It returns a research brief but never writes status, implementationPlan, executionRecord, or files. Substantive scope rewrites are proposed, not applied; the orchestrator gates those with you before the planner runs.

Plan

The planner reads the refined task and the brief, then writes the unabridged implementationPlan: goal, files to modify, build sequence, edge cases, verification commands, acceptance-criteria mapping. It is the only phase that writes the draft → planned transition, and it writes it in the same call as the plan. It edits no code.

Implement

The implementer reads the plan from piyaz_context depth='agent', claims the task (planned → in_progress), implements on a feature branch, runs the project's tests, typecheck, and lint until green, and opens a PR using the project's template with the [<taskRef>] bracket form. It then marks the task in_review with the full Completion Protocol payload (executionRecord, decisions, files, evaluated acceptance criteria). It does not write done.

CI gate

A cheap watcher waits on the PR's checks (gh pr checks) and reports the result (green, red, pending, or none) to the workflow. The review reads that state, and the merge gate later requires it to be green.

Review

The reviewer reads piyaz_context depth='review', which renders the plan alongside the execution record, surfaces the PR link, and computes plan-vs-files drift. It returns a structured verdict (approve, request-changes, or block) with file-cited reasoning across five lenses: security, performance, reliability, observability, and codebase standards. Review is read-only over Piyaz; the verdict travels in the return message, not in any task field.

Fix loop

When the review returns request-changes, the workflow does not stop and wait. It sends the blocking findings back to the implementer, which addresses exactly those findings, re-runs verification, and re-marks the task in_review; the reviewer then re-checks. This rotates at most twice. If findings still stand after the budget, or the verdict is block, the workflow surfaces the result as escalated and leaves the response to you. See Human on the loop.

The merge gate

After the workflow returns, composer surfaces the verdict and runs the merge gate under the policy you chose at the start of the session:

• never (default): composer does not merge. You own the merge and the in_review → done transition, exactly as before this feature existed.
• ask-each: composer asks before merging each PR. On yes, it merges; on no, it leaves the PR for you.
• auto-on-approve: composer merges without asking.

The gate fires only when the verdict is approve and CI is green; a request-changes, block, escalated, red, or pending result is never merged. When the gate does merge (gh pr merge --squash --delete-branch), composer writes the task done. That is the single status transition the orchestrator ever writes, and only a merge policy you set authorizes it. A failed merge (conflict, protected branch, merge queue) is not a task failure: composer reports it and leaves the task at in_review for you.

Rework mode

The backend has no GitHub webhooks, so rework is pull-based: you invoke it when review feedback exists on a PR. /piyaz:composer rework <taskRef|pr-url> resolves the task and its PR, re-verifies your change requests against the current branch head, and runs the fix loop on them with a fresh two-rotation budget. It finishes like any iteration: surface the verdict, run the merge gate, propagate.

Why a fresh context per phase

Each phase is a separate dispatched agent with its own clean context window and only the tools its phase needs. The researcher cannot edit code; the reviewer cannot write to Piyaz. Running the sequence inside the workflow, rather than in the orchestrator's main loop, applies the same context discipline the task graph uses at the project level to a single task:

• Dispatch payloads stay small because the task row is the source of truth. The researcher's refinements and the planner's plan land on the task, and the implementer reads both from it. Nothing is re-passed between phases.
• The orchestrator's context does not grow with every phase, so a long backlog run stays cheap and survives compaction.

Where the human gate sits

Under the default never policy, composer never flips a task to done. The implementer's terminal write is in_review, and after you approve and merge the PR you move the task in_review → done yourself. Under ask-each or auto-on-approve, composer does that merge and writes done for you, but only on an approve verdict with green CI, and only because you authorized that policy. Either way the review verdict is never a silent retry signal: the workflow's bounded fix loop handles request-changes inside the budget, and anything left over is surfaced to you.