Lifecycle Workflows

Lifecycle workflows are the high-level flows that create or improve a repo wiki. Build creates the first wiki, ingest folds selected source material into pages, and garden improves the existing wiki graph and content [@build-workflow] [@ingest-workflow] [@garden-workflow]. These three are the page-writing operation family described by Lifecycle operation.

The workflows prepare operation-specific context, but they do not each own harness execution, run completion, index refresh, or final validation. They delegate that common path to Operation runner [@operation-runner]. This keeps build, ingest, and garden different in purpose while sharing one run-execution path.

Build#

Build is the initialization workflow. At queue time, it prepares a repository target, rejects an existing almanac/, registers the repository, initializes a minimal wiki, and records a queued build run [@build-workflow]. Harness readiness is checked later by the worker through the shared operation path, not before the initial wiki scaffold is written.

When the worker executes the queued run, build calls the shared operation runner. Its task payload includes repository paths, the almanac root, topics.yaml, manual documents, optional guidance, and source-control policy [@build-workflow]. The stable instructions come from the packaged build agent described in Agents and manuals. Build is therefore both setup and the first agent-authored wiki pass.

Ingest#

Ingest is the source-material workflow. It starts an INGEST run for a selected repository, resolves the requested inputs into source briefs, loads runtime snapshots for those sources, records those preparation steps, and renders the ingest prompt [@ingest-workflow]. Resolution and runtime-inspection failures are durably categorized as source_preparation, distinct from failures after the harness starts. See Source resolution and runtime for how selected source material becomes those briefs and snapshots.

The source runtime layer is important because ingest should give the agent concrete material, not just file names or user prose. The workflow also passes the almanac root as an ignored directory when inspecting source runtime, so the existing wiki is not accidentally treated as input material for the ingest source set [@ingest-workflow].

Garden#

Garden is the maintenance workflow for an existing wiki. Before calling the operation runner, it reads the current index summary and health report, records that it prepared garden context, and renders a prompt with the current wiki state [@garden-workflow].

Garden does not resolve external source material. Its job is to improve structure and quality from the wiki's own graph: weak pages, stale health findings, missing links, weak topics, and similar maintenance work.

Sync Is Not An Operation#

SyncWorkflow evaluates local transcript candidates and uses SyncIngestQueue to queue ingest runs; it does not render a writing prompt or call the harness itself [@sync-workflow]. See Lifecycle operation for why sync is a scanner and trigger rather than a fourth page-writing operation, and Run queue and sync for the queue boundary and the worker that drains it.

Shared Contract#

All page-writing workflows end at the operation runner. The runner marks the run running, invokes the harness, records transcript events, validates harness success, refreshes the index, validates the wiki, and only then marks the run done [@operation-runner]. Workflows name their own preparation phases; the runner names the shared execution phases and remains the single failure writer.

When changing a workflow, preserve that division. Workflow services should decide what context and prompt the agent receives. Shared run state, harness recording, indexing, and final validation belong in the operation path.