Worker artifacts by flow
High-level contract for what a worker must write under {{TASK_DIR}}/artifacts/ before ./mark complete --mark-last. This is the same finish shape in Farmslot-dispatched runs and standalone agentic skills (with one exception noted below).
For the short worker checklist, see Finish a worker run. For signal schema and freshness rules, see Worker signal protocol.
Every terminal run
| Artifact | Required | Purpose |
|---|---|---|
artifacts/learnings.md | Contribution flows (unless ./mark --skip-learnings); reviewer flows (self-review, self-review-fix) require their feedback/report artifact instead | Process meta for retrospective and improvement — one bullet per recurring failure; - None if none |
| Flow outcome file | Yes (see table below) | What happened: fix summary, review, PR body, merge notes, or no-change investigation |
SIGNAL.json | Yes | Written only by ./mark — never hand-edited |
CHECKLIST.md / TASK.md | Yes | Every box [x] when using --mark-last; the file named by checklist-target.json is the one counted (see Task directory contract) |
Outcome file by flow
PR-producing flows use pr-description.md as the single outcome artifact (internal operator summary + publishable PR body). Do not also write report.md for dev/fix-bug.
| Flow | Outcome artifact | Notes |
|---|---|---|
| dev | artifacts/pr-description.md | Gateway publishes this after the publication gate. Include summary, test plan, evidence placeholders, validation recipe block. |
| fix-bug | artifacts/pr-description.md | Same — root cause, fix, validation, repo template sections. |
| review-pr | artifacts/review.md | Primary review output. Also artifacts/line-comments.json (may be []). |
| pr-complete | artifacts/comments-report.md | Comment triage + fixes; interactive handoff may omit worker terminal signal. |
| update-branch | artifacts/report.md | Conflicts resolved, validation, risk notes. |
| no-change (contribution flows) | artifacts/no-change-report.md | Use ./mark no-change --reason "…" --mark-last. Exception: self-review no-change requires review-feedback.md instead. |
| ci-fix, validate-dep, self-review-fix | artifacts/report.md | Secondary/utility flows — no PR package. |
Standalone recipe skills (no Farmslot dispatch)
Recipe-authoring skills such as recipe-dev and recipe-fix-ticket, run from your own skills repository checkout, typically do not open a PR automatically. They use:
artifacts/learnings.md— alwaysartifacts/pr-description.md— the same outcome file a Farmslot-dispatched run writes: PR body in the repository PR-template shape plus the proof summary. Your skills repository's PR-evidence step packages it (evidence images, artifact index) when you decide to open a PR.
The same task directory is therefore publishable from either surface without renaming anything.
Recipe runs (conditional)
When artifacts/recipe.json exists, also write:
| Artifact | When |
|---|---|
artifacts/evidence-manifest.json | Visual evidence for PR embed |
artifacts/recipe-quality.json | Project/template expects quality gate; generate with farmslot-agent recipe-quality build |
./mark complete and check-task-artifact-contract.mjs enforce these when the recipe file is present.
How enforcement works
Template / skill checklist
↓
Worker writes artifacts/
↓
./mark complete --mark-last ← canonical script: @farmslot/agent-runtime
↓
SIGNAL.json (terminal)
↓
Farmslot: monitor + publication gate reads pr-description / review / …
Built-in defaults live in worker-terminal-contract.cjs. Farmslot farms may override per flow in project.json -> worker_terminal; dispatched runs also get inputs/worker-terminal-contract.json.
Related
- Finish a worker run — three-step worker checklist
- ADR-045: Worker terminal contract — project.json overrides
- Recipe skills adoption kit — standalone skills path