Workflow Server

Artifact and workspace isolation

Orchestration metadata and your actual code never mix. Domain work happens under the workspace root (feature worktrees); plans, state, traces, and review documents live under the engineering root in a per-session planning folder. Each side stays clean, diffable, and independently version-controlled.

Canonical source: docs/artifact-management-model.md. Storage layouts: docs/engineering-storage.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 …/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. Domain work stays in target_path under the workspace root; planning artifacts live under the engineering root (artifacts/planning/<slug>/ for an engineering-branch checkout, or .engineering/artifacts/planning/<slug>/ in legacy single-root mode).

The planning folder

Each session establishes one planning folder under the engineering root 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. Defaults: <engineering>/artifacts/planning/<slug>/ (repo layout) or <workspace>/.engineering/artifacts/planning/<slug>/ (legacy).

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

Engineering content is version-controlled independently of product history. Common layouts (see engineering storage patterns): same-repo orphan branch, shared engineering monorepo (external remote + project-named branches), or in-tree .engineering/. When the orchestrator commits artifacts it works inside the engineering checkout first — stage, commit, push — then updates any app-repo submodule gitlink. Engineering metadata never pollutes product commits under the workspace root.