Workflow Server

Artifact and workspace isolation

Orchestration metadata and your actual code never mix. Domain work happens strictly inside your codebase; plans, state, traces, and review documents live in a per-session planning folder under .engineering/. Each side stays clean, diffable, and independently version-controlled.

Canonical source: docs/artifact_management_model.md.

The two directory scopes Two side-by-side scopes. The target path is the user's codebase, where code, tests, and builds happen. The engineering directory is the orchestration workspace; its planning folder for the session contains the progress README, the session state pair, the trace, and prefixed artifacts. The activity worker writes domain work to the codebase and planning artifacts to the planning folder. target_path — your codebase src/, tests/, build config … all domain execution: writing code, running tests, refactoring, building committed to your product history .engineering/artifacts/planning/<slug>/ README.md — progress tracker session.json — server-managed state .session-token — HMAC seal workflow-trace.json — semantic log 02-design-philosophy.md, 05-… — artifacts version-controlled on the engineering branch agents write domain work only to the left scope and planning artifacts only to the right scope — never across
The two directory scopes. Everything an activity worker does to your product happens in target_path; everything about how the workflow got there — plans, state, traces, reviews — lands in the session's planning folder under .engineering/.

The planning folder

Each session establishes one planning folder that acts as its isolated "brain": README.md as the central progress tracker, the server-managed session.json + .session-token state pair (see state management), and workflow-trace.json holding the semantic log of what the agents did.

Progress tracking is mandatory. Before a worker may report an activity complete, its finalize protocol requires updating the planning folder's README — checking off progress-table items and keeping the artifact list accurate — so a human can always read the README and know exactly where the workflow stands without parsing logs.

Predictable artifact naming

Every activity carries an artifactPrefix, inferred by the server from the activity's filename (02-design-philosophy.yaml → 02). Workers prepend it to artifacts they produce — design-philosophy.md becomes 02-design-philosophy.md — so a planning folder sorts into workflow order and artifacts never clash. The activity's artifacts array itself is a server-computed contract, synthesized by get_activity from the outputs of the techniques its steps bind; activities do not author the list.

Git and submodule protocol

The .engineering tree typically lives as a Git submodule or orphan-branch worktree, so orchestration state is version-controlled independently of your product history. When the orchestrator commits artifacts it works inside the submodule first — stage, commit, push — then commits the updated submodule reference in the parent repository. Engineering metadata never pollutes product commits.