Skip to content

Workflow — Project bootstrap

Generated from the architecture model

This page is rendered from model/**/*.yaml by tools/docs_model during mkdocs build. Edit the YAML, not this page; hand-written design lives on the linked service, platform and plane pages.
Workflow id project-bootstrap · version 1 · Draft (Draft → InReview → Published → Deprecated, BC-04)
Coordinator project-bootstrap-orchestrator · family Project Initialization & Session Management
Owner service WorkflowEngineService (BC-38) under Run Control (BC-03)
Starts on ProjectCreated from ProjectService (event)
Steps 5 · gated 1 · agents 1
Budget per run 600000 tokens · cap 60.0 USD · 240 min
Descriptor workflow-definition-v1 · schema
Status target

Creates the system-of-record project, repositories, pipelines and boards for a new Factory project through connectors, under one shared-write approval, and records the trace scaffolding.

Authored design, Draft (D54, D57)

These definitions were authored on 2026-10-14 from the coordinator cards as design assumptions. None is published, evaluated or has run; agents are named by id as design bindings, not as tested integrations.

Definition

flowchart TD
    start(("ProjectCreated"))
    plan_bootstrap["Plan the bootstrap"]
    scaffold_resources["Scaffold in the sandbox"]
    approve_shared_write(["Approve the shared write"])
    apply_bootstrap[["tool: Apply through the connector"]]
    record_trace["Verify and record"]
    start --> plan_bootstrap
    plan_bootstrap --> scaffold_resources
    scaffold_resources --> approve_shared_write
    approve_shared_write --> apply_bootstrap
    apply_bootstrap --> record_trace
    done(("WorkflowRunCompleted"))
    record_trace --> done
    class approve_shared_write gated
    classDef gated stroke:#B45309,stroke-width:2px
Hold "Alt" / "Option" to enable pan & zoom

Shapes: rectangle = agent attempt · double rectangle = tool call · stadium = human decision · diamond = condition evaluated by the engine · parallelogram = fan-out or join · circle = timer · cylinder = sub-workflow · flag = compensation. A thick amber border marks a gated step.

Steps

# Step Kind Runs Gate Class Depends on Retry Timeout Compensation What it does
1 Plan the bootstrap
plan-bootstrap		 agent devops-engineer none read — exponential ×2 PT30M — Derives the repositories, pipeline definitions and boards the project needs from its edition and the connection's capabilities; the plan is an artifact with lineage.
2 Scaffold in the sandbox
scaffold-resources		 agent devops-engineer none sandbox plan-bootstrap exponential ×2 PT30M — Generates repository layouts, pipeline files and board templates in the run's isolated workspace from the plan.
3 Approve the shared write
approve-shared-write		 human engine approval shared-write scaffold-resources none P7D — Approval of the exact change set that will create repositories, pipelines and boards in the system of record.
4 Apply through the connector
apply-bootstrap		 tool propose-change-set none shared-write approve-shared-write fixed ×1 PT30M withdraw the proposal and record the partial creation as a finding Opens the change proposal and creates the resources through the registered connector with the lease-bound credential.
5 Verify and record
record-trace		 agent devops-engineer none read apply-bootstrap exponential ×2 PT30M — Verifies the created resources against the plan and records the trace scaffolding and receipts as artifacts.

Gates and approvals

  • shared-write: the change proposal in the system of record, bound to the exact change-set version (D21); skipped when the project policy allows autonomous proposals Compensation steps run in reverse order of the succeeded steps on failure after the last checkpoint; a step without a compensation leaves its sandbox output in place and the run ends Failed with the evidence (ADR-0014, recovery not replay).

Inputs, outputs and events

Direction Name Descriptor
in project execution-scope-v1
in system-of-record-connection artifact-v1
out bootstrap-change-proposal pull-request-proposal-v1
out trace-scaffolding artifact-v1

Starts on ProjectCreated; emits ChangeProposalOpened, ArtifactStored, WorkflowRunCompleted, plus the engine's WorkflowRunStarted, StepReady, StepRunStateChanged and WorkflowRunCompleted / WorkflowRunFailed and Run Control's run and attempt events (ADR-0014).

Decisions and traceability

FR: FR-05 Governed tool boundary · FR-06 Exact-version approvals · FR-08 Validated artifacts with lineageXL: XL-01 Project onboarding with rights · XL-10 Controlled repository changeFUX: FUX-05 Exact-version human decisionsADRs: ADR-0014, ADR-0024 · ADR index

Definition authored 2026-10-14 from the coordinator card project-bootstrap-orchestrator (D54); Draft until an evaluation gate (ADR-0021) and a review publish it as a BC-04 asset release.