Skip to content

Workflow — Documentation sync

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 documentation-sync · version 1 · Draft (Draft → InReview → Published → Deprecated, BC-04)
Coordinator documentation-sync-coordinator · family Documentation & Knowledge Management
Owner service WorkflowEngineService (BC-38) under Run Control (BC-03)
Starts on ChangeProposalMerged from PipelineExecutionService (event)
Steps 5 · gated 1 · agents 2
Budget per run 600000 tokens · cap 60.0 USD · 240 min
Descriptor workflow-definition-v1 · schema
Status target

Regenerates a product's documentation site from the model after a merged change, writes the narrative deltas, validates the build and proposes the documentation change set.

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(("ChangeProposalMerged"))
    regenerate_site["Regenerate the site"]
    write_deltas["Write the deltas"]
    validate_build[["tool: Validate the build"]]
    approve_proposal(["Approve the proposal"])
    propose_change_set[["tool: Propose the change set"]]
    start --> regenerate_site
    regenerate_site --> write_deltas
    write_deltas --> validate_build
    validate_build --> approve_proposal
    approve_proposal --> propose_change_set
    done(("WorkflowRunCompleted"))
    propose_change_set --> done
    class approve_proposal 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 Regenerate the site
regenerate-site		 agent documentation-site-generator none sandbox — exponential ×2 PT30M — Regenerates catalogs, references and diagrams from the model in the sandbox.
2 Write the deltas
write-deltas		 agent documentation-writer none sandbox regenerate-site exponential ×2 PT30M — Updates the narrative pages the change affects, with citations to the change set.
3 Validate the build
validate-build		 tool build-and-test none sandbox write-deltas fixed ×2 PT15M — Builds the site strictly in the sandbox; broken links or diagrams return to the writer.
4 Approve the proposal
approve-proposal		 human engine approval shared-write validate-build none P7D — Approval of the documentation change set when the project policy requires it.
5 Propose the change set
propose-change-set		 tool propose-change-set none shared-write approve-proposal fixed ×1 PT30M withdraw the proposal Opens the documentation pull request.

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 generated-outputs change-set-v1
in documentation-blueprint blueprint-documentation-v1
out documentation-change-proposal pull-request-proposal-v1

Starts on ChangeProposalMerged; emits ChangeProposalOpened, 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-08 Validated artifacts with lineageXL: XL-10 Controlled repository changeFUX: FUX-12 Documented viewsADRs: ADR-0014, ADR-0024 · ADR index

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