compose-workflow

<!-- story: e09s01 --> <!-- story: e45s27 --> <!-- story: e21s04 -->

Compose Workflow

HARD GATE — HARD GATE — Workflows are orchestration, not automation. Do NOT create workflows for tasks that should be single skills. Workflow complexity must be justified.

Process

1. Interview: goal, phases, which skills, gates between steps.
2. Write specs/workflows/<name>.yaml:
   • name, command, description, skills[], verify
   • Optional: args for skill-specific arguments
3. Register in state.yaml Active Decisions.
4. Optional: reference from orchestrate-project Ad-Hoc mode.

Prefer the YAML recipe format over the legacy specs/WORKFLOW-<name>.md markdown format. YAML recipes are command-mappable, machine-readable, and listed in the Standard Recipe Library.

Terminal-state taxonomy (e45s27)

Every workflow step and /loop tick MUST exit with exactly one terminal state:

State	Meaning	Next action
success	Step verify passed; artifacts written	Advance to next skill in recipe
no-op	Nothing to do (already green / already applied)	Skip step; advance
blocked	External gate (approval, red CI, missing dep)	diagnose-stall or escalate to user
exhausted	Max iterations/cycles reached (review cap, dispatch cycles)	Stop; human decision required

Record terminal state in specs/state.yaml handoff.last_terminal_state when a recipe step completes. /loop ticks that produce no progress for two consecutive wakes → invoke diagnose-stall.

Standard Recipe Library

Pre-built recipes in specs/workflows/ map agentic stack commands to skill chains. Reference them in AGENTS.md so /command directly invokes the matching recipe.

Command	Workflow	Skill chain
/check-stack	check-stack	survey-context → assess-impact → setup-environment
/ship	ship	audit-code → commit-message → release-branch
/tdd	tdd	develop-tdd → enforce-first
/code-review	code-review	audit-code → request-review → respond-review
/security	security	audit-code → request-review
/plan	plan	survey-context → research-first → plan-work
/build-fix	build-fix	investigate-bug → diagnose-root → develop-tdd → validate-fix
/e2e	e2e	smoke-test → verify-work

Add to AGENTS.md:

/check-stack = compose-workflow check-stack
/ship        = compose-workflow ship

Verify

→ verify: [ "$(ls specs/workflows/*.yaml 2>/dev/null | wc -l | tr -d ' ')" -ge 8 ]

See REFERENCE.md for template.

---

Workflow template

# WORKFLOW: <name>

**Trigger:** Use when ...

| Step | Skill | Output | verify |
|------|-------|--------|--------|
| 1 | survey-context | state.yaml handoff | ... |
| 2 | research-first | Prior Art in SCOPE_LATEST.yaml | ... |
| 3 | plan-work | epics/eNN-*.yaml tasks | ... |