/composer

name: composer
description: >
  Use when the user types /piyaz:composer, /piyaz:composer <taskRef>, or
  /piyaz:composer rework <taskRef|pr-url>, or asks to run the next Piyaz
  task end-to-end, ship the backlog, compose through the ready queue, or
  loop through Piyaz tasks until done. Composer researches, refines, plans,
  implements, reviews, and fixes each task in a loop until the PR is ready,
  and merges and continues when the user authorizes it. Do NOT invoke for
  one-off task lookups, status checks, hand-refinement of one task, or
  interactive planning of a single task; those flows belong to the piyaz
  skill and composer adds latency without adding quality.

Composer

Composer is a Piyaz task orchestrator. Per iteration it picks the next ready task off the project's critical path, runs that task through a deterministic per-task **workflow** (research, plan, implement, CI gate, review, bounded fix loop), surfaces the verdict, merges when the user authorized it, propagates the result through the graph, and continues until a structural stop condition holds.

The orchestrator (this skill, running in the main loop) owns only the **interactive seams**: pick the task, resolve gates, run the merge gate, propagate. The token-heavy phase sequencing runs inside the workflow, off the orchestrator's context, dispatching the phase agents in fresh windows with per-phase model and effort. This is the design's main token discipline: orchestration is JavaScript, not main-loop reasoning over a transcript that grows with every phase.

Composer is glue. The heavy lifting (task selection, refinement, the Completion Protocol, propagation) lives in the `piyaz` skill (`skills/piyaz/SKILL.md`); composer reuses those flows rather than duplicating them.

Invocation

• **`/piyaz:composer`**: backlog mode. Pick the highest-value ready task each iteration; continue until a stop condition holds.
• **`/piyaz:composer <taskRef>`**: single-task mode. Same pipeline applied to one task; exits after the iteration completes.
• **`/piyaz:composer rework <taskRef|pr-url>`**: rework mode. HOTL requested changes on GitHub instead of merging; composer rounds that feedback back through the fix loop.
• **`/piyaz:composer --pipelined`**: backlog mode with research-ahead (latency-only, costs tokens). Off by default; see *Pipelined research-ahead*.

No argument means backlog mode; `rework` plus an argument means rework mode; anything else is single-task.

Piyaz operating context

The canonical piyaz rules load with this skill. Downstream citations (`conventions §1`, `artifacts §3`, `lifecycle §3`) refer to this loaded text.

@skills/piyaz/references/conventions.md @skills/piyaz/references/artifacts.md @skills/piyaz/references/lifecycle.md @skills/piyaz/references/resilience.md

The per-task workflow

Each iteration's task runs through `skills/composer/workflows/compose-task.js`, launched with the Workflow tool:

Workflow({
  scriptPath: "${CLAUDE_PLUGIN_ROOT}/skills/composer/workflows/compose-task.js",
  args: { taskRef, taskId, projectId, categories, tagVocabulary,
          pickEstimate, pickPriority, workType, tags,
          mode, plannableOnly, resumeFrom, priorBrief, gateAnswers,
          fixFindings, prUrl, priorFailure, estimate, flags, fable },
})

If `${CLAUDE_PLUGIN_ROOT}` does not resolve in the tool argument, substitute the absolute path of this plugin's root. The workflow runs in the background; the orchestrator is suspended until it returns, so it spends no context tokens while phases run.

The workflow dispatches the phase agents by `agentType`, each with explicit `model`/`effort`/`schema`, the implementer with `isolation:'worktree'`. It runs `research+plan → implement → ci-gate → review → [fix-loop ≤2 rotations]`, with a fixed-interval CI poll (60s, bounded) and a CI-pending re-poll path that re-reviews without burning a fix rotation, then returns one structured result. It does **not** merge, propagate, or touch edges; those are the orchestrator's seams. The phase contracts live in the agent files; do not duplicate them here.

| Phase | `agentType` | Writes to Piyaz | Workflow captures | | --- | --- | --- | --- | | 1+2. Research+Plan (merged) | `piyaz:composer-researcher` under an orchestrator authority grant | refinement fields (`description`, `acceptanceCriteria`, `tags`, `category`, `priority`, `estimate`, `decisions`) plus `implementationPlan`; `status='planned'` on `draft → planned` only | brief, status, gatePhase, flags, confidence, refined estimate/work-type, proposed rewrites, section/step counts, open questions | | 3. Implement | `piyaz:composer-implementer` | `status='in_progress'` (claim), `status='in_review'` (+ Completion Protocol); fix mode rotates `in_review → in_progress → in_review` | status, PR URL, AC counts, concerns | | CI gate | generic (haiku) | nothing | `green` / `red` / `pending` / `none`, failing checks | | 4. Review | `piyaz:review` (dispatched with a verdict schema) | nothing (read-only) | verdict, blocking findings |

The workflow result

The workflow returns exactly one of three shapes. Branch on `result.status`, not on prose:

| `status` | Meaning | Orchestrator reaction | | --- | --- | --- | | `DONE` | Task ran to `in_review` (or `planned` for a plannable-only pick) | Surface the verdict, run the *Merge gate*, propagate | | `NEEDS_DECISION` | The merged research+plan phase gated; `result.gate` carries the trigger and `result.phase` names the raising half (`research` or `plan`) | Resolve via *Gates*, then relaunch the workflow with the answer | | `BLOCKED` | A phase could not complete; `result.phase` and `result.reason` say which and why | *Failure handling* |

A `DONE` result also carries: `outcome` (`in_review`|`planned`), `verdict`, `prUrl`, `ciState`, `acSatisfied`/`acTotal`, `rotations`, `escalated` (true when a `block` verdict or an exhausted fix budget left findings unaddressed), `blockingFindings`, `concerns`. A null return (the workflow