workflowworkflowtrueorfalse

handoff

Records done / not done / decisions / files / risks / next 3 actions so work survives a role switch or a pause.

looks for

end of a session with work unfinished
a role switch inside a work order
QA failed and goes back to the implementer
an API or data contract changed under other agents

outputs

→ a handoff entry appended to the work order's Handoff log
→ or a standalone file in {{HANDOFFS_DIR}}

drawing flowchart…

flow.mmd

SKILL.md

Handoff

A handoff is written for someone with no memory of this session. Exact paths, exact commands, exact decisions.

Where to write

Preferred: append under ## Handoff log in the active work order.
Cross-cutting: {{HANDOFFS_DIR}}/HO-YYYYMMDD-short-slug.md.

Template

### HO — YYYY-MM-DD HH:mm

- **From:** <role>
- **To:** <role>
- **WO:** WO-YYYYMMDD-short-slug
- **State:** in_progress | blocked | in_review

#### Done
- ...

#### Not done
- ...

#### Decisions locked
- (do not revisit without a new WO)

#### Files touched
- `path/to/file` — what changed

#### Risks / watch-outs
- ...

#### Next 3 actions
1. ...
2. ...
3. ...

#### Commands already run
    <command>   # PASS / FAIL / PENDING (why)

Rules

Concrete beats complete: a path and a command beat a paragraph.
Link docs; do not paste specs.
Say if design review already happened (saves a round-trip).
A check you could not run is PENDING, never green.
Never put secrets, tokens or customer data in a handoff.

Customize for your project

{{HANDOFFS_DIR}}, e.g. docs/handoffs/.
Your timezone convention for the timestamp.

pairs with

workflowtrueorfalse
work-order
Turns an ask into a scoped work order file with acceptance criteria, story points and verify commands.
- a task accepted with no written scope
- "add X" requests that touch several files or modules
- scope creep mid-task
Claude · Codex · ChatGPT
ruletrueorfalse
agent-team
Routes each ask to one owning role, then enforces work order → specialist → verify → handoff.
- a new task with no clear owner
- work that touches more than one module or repo
- who should do this?
Claude · Codex · ChatGPT
personatrueorfalse
qa-verifier
Runs the real checks, records an honest PASS/FAIL/PENDING report in the work order, and never fakes green.
- implementation finished
- a request to close a work order or merge
- is it green?
Claude · Codex · ChatGPT

Template

### HO — YYYY-MM-DD HH:mm - **From:** <role> - **To:** <role> - **WO:** WO-YYYYMMDD-short-slug - **State:** in_progress | blocked | in_review #### Done - ... #### Not done - ... #### Decisions locked - (do not revisit without a new WO) #### Files touched - `path/to/file` — what changed #### Risks / watch-outs - ... #### Next 3 actions 1. ... 2. ... 3. ... #### Commands already run <command> # PASS / FAIL / PENDING (why)

pairs with

workflowtrueorfalse

work-order

Turns an ask into a scoped work order file with acceptance criteria, story points and verify commands.

a task accepted with no written scope
"add X" requests that touch several files or modules
scope creep mid-task

Claude · Codex · ChatGPT

ruletrueorfalse

agent-team

Routes each ask to one owning role, then enforces work order → specialist → verify → handoff.

a new task with no clear owner
work that touches more than one module or repo
who should do this?

Claude · Codex · ChatGPT

personatrueorfalse

qa-verifier

Runs the real checks, records an honest PASS/FAIL/PENDING report in the work order, and never fakes green.

implementation finished
a request to close a work order or merge
is it green?

Claude · Codex · ChatGPT