SPECWORKS FACTORY — Field Guide

01 — Scope

What this is, and what it isn't

Before you walk the floor, know what the factory covers — and where it deliberately stops.

It is

An operating system for an agent fleet — roles, write lanes and handoff protocol in one AGENT.md
A spec-driven production line: PRD → SCOPE → SPEC → EVAL gates before any code is cut
A traceability spine from requirement to shipped release note, all in files you can grep
Framework-agnostic — plain markdown, git branches and shell scripts; any agent runtime can operate it
Reproducible starters: workspaces/_templates/, five job playbooks, ingest hooks

It is not

A tabular dataset — the viewer shows nothing because the content is the file tree itself; you clone it, you don't load it
A codebase or framework — there is no runtime to install; the factory is the convention
A replacement for your VCS or CI — it orchestrates around them, using their primitives
Free-form chat with agents — every delegation is a task file with one owner and an acceptance check
Optional ceremony — under-specified orders are rejected at intake; the factory does not guess the bill of materials

02 — The floor

One directory, six departments

Every path below is a department on the factory floor. Hover the tree; each department is explained beside it.

specworks/

├─ AGENT.md · fleet constitution + FACTORY PROTOCOL

├─ orders/ORD-<n>-<name>/ · PRD + SCOPE + SPEC + EVAL + qc/ + ship/

├─ stations/STATIONS.md · live branch / worktree index

├─ tasks/pending/ · done/ · ALL job files T-<n>-j<k>-…

├─ knowledge/ · shared truth: INDEX · _provisional · _graveyard

├─ workspaces/agents/<name>/ · per-agent drafts, isolated

│ └─ _templates/ · order + task + verdict starters

├─ skills/ · job playbooks J-0…J-4, refresh-index

├─ scripts/ · hooks/ · deterministic ingest + event triggers

├─ DECISIONS.md · append-only factory-wide decisions

├─ ACTIVITY.md · append-only, attributed @agent/human

└─ logs/ · per-session, per-agent summaries

Orders orders/
The order book. No order enters the floor without its four documents — the intake gate (J-0) rejects the rest.
Tasks tasks/
The bus. Every handoff is a file in pending/, closed into done/ with a filled RESULT block — never a chat message.
Knowledge knowledge/
The only place truth lives. Every fact cites a source; uncertainty is parked in _provisional.md; wrong facts move to _graveyard.md — nothing is deleted.
Ledgers DECISIONS · ACTIVITY · logs
Append-only paper trail. Every change is named by the @agent that made it.
Skills skills/
Six deterministic playbooks — J-0 intake, J-1 station, J-2 assembly, J-3 QC, J-4 shipping, plus weekly index refresh — any agent can execute.

04 — Traceability spine

Every shipped line answers six questions

Follow any feature from why to what-we-learned without leaving the repo.

PRD FR-3why — the requirement

SPEC task T-042what to build

station commitwhat was built

QC verdicthow it was verified

RELEASE-NOTESwhat shipped

DECISIONS.mdwhat we learned

The QC loop

Three verdicts, three loops, then a human

QC is always a different agent than assembly. The builder never ships its own work.

SHIP

File a J-4 task with evidence: test summary, screenshots, log tail. The order moves to shipping.

FEEDBACK

A feedback task to the builder: exact error, log line, screenshot, target task id, what "passing" looks like. "Doesn't look right" is not feedback. Loop count +1.

ESCALATE

Three failed loops, or a factory defect — broken isolation, ambiguous spec, insufficient eval — goes to a human with the full loop history.

loops-to-ship

The factory's health metric, tracked per order in ACTIVITY.md. Rising loops mean fix the SPECS, not the builders — a factory change is itself ORD-class work with its own spec and QC.

05 — The fleet

Five agents, one constitution, hard write lanes

Stay in your lane: need a file outside it? Write a task to the agent who owns it. No agent touches another's workspace — ever.

@orchestrator

Coordinates: dispatches tasks, serializes conflicts, escalates, pens DECISIONS. Runs intake (J-0) and shipping (J-4).

writes → tasks/ ACTIVITY logs/ stations/

@builder

Assembly line: one task per iteration on the station, strictly inside the task's writes list. Runs J-1 + J-2.

writes → station branch only · tasks/

@auditor

Quality control: boots it, fits it, stresses it. Runs J-3 and the weekly auditor pass (J-5). Proposes via tasks — never edits station source.

writes → orders/<o>/qc/ _graveyard/ tasks/

@indexer

Mapmaker: regenerates knowledge/INDEX.md from the actual tree after any knowledge change.

writes → knowledge/INDEX.md only

@monitor

Sentry: tracks SLOs, drift and loops-to-ship; degrades to human-in-the-loop on breach; files incident tasks.

writes → alerts · task files

@human

Agents too: @<person> in ACTIVITY.md. Hold review gates and the DECISIONS pen for anything consequential.

holds → review gates · DECISIONS pen

06 — Conventions

Named things, findable things

Every entity has one filename pattern and one home. If you can name it, you can grep it.

Entity	Pattern	Where
Order	`ORD-<n>-<name>`	`orders/`
Station	`station/<order-id>-<short>`	branch / worktree + `STATIONS.md`
Job / task	`T-<n>-j<k>-<from>-to-<to>-<topic>`	`tasks/pending/` → `done/`
QC verdict	`QC-<n>-<verdict>` · immutable	`orders/ORD-n/qc/`
Decision	`D-<n>`, supersedes-chaining	`DECISIONS.md` (append-only)
Activity	`date time — @actor — action`	`ACTIVITY.md` (append-only)
Session log	`YYYY-MM-DD-<agent>-<topic>.md`	`logs/`

Ground rules

Six rules that make it work

Sources or it didn't happen — no source → _provisional.md, never knowledge/
Nothing is deleted, only moved — wrong knowledge goes to _graveyard.md
QC ≠ assembly — the builder never ships its own work

One order = one station = one J-0…J-4 chain — no shared stations
No order without the full triad + EVAL — the intake gate rejects guesses
Workspaces are earned out of, not into — draft in yours, promote through review

Specs are not documents.
They are the production line.