Skip to content

Workflow Overview

Jump to bottom
ClarusIubar edited this page Jul 2, 2026 · 7 revisions

Workflow Overview

Agent Bootstrap is a governance layer for coding agents. It is meant to make implementation work traceable, bounded, and reviewable instead of relying on conversation memory alone.

The Problem It Solves

Without a task gate, an agent can start editing from an ambiguous request, mix unrelated work, forget validation requirements, or claim completion without durable evidence.

This preview demonstrates a stricter workflow:

flowchart TD
    A["User request"] --> B["Parent issue defines roadmap context"]
    B --> C["Child issue defines executable scope"]
    C --> D["Checklist, validation plan, and architecture boundary"]
    D --> E["context start hydrates task"]
    E --> F{"Edit gate open?"}
    F -- "No" --> G["Stop and repair issue/checklist/context"]
    F -- "Yes" --> H["Implement only scoped changes"]
    H --> I["Run validation and sensitive-surface checks"]
    I --> J["Commit and push"]
    J --> K["Read back GitHub state and CI"]
    K --> L["Record completion evidence"]
    L --> M["Finish or hand off remaining blockers"]
Loading

Step-By-Step Flow

1. Materialize The Task

The agent does not treat a chat instruction as enough authority for durable edits. A parent issue owns the roadmap context, and a child issue owns one executable unit of work.

The child issue should state:

  • scope
  • out-of-scope boundaries
  • public behavior or expected outcome
  • interface or data flow
  • failure modes
  • validation commands
  • architecture boundary
  • completion evidence

2. Hydrate The Context

The agent runs a source-of-truth start command against the child issue. The expected result is:

Status: task-hydrated
Edit gate: implementation-ready

If that result is not present, the agent stops and repairs the issue, branch, checklist, or workspace binding before editing.

3. Keep Edits Inside Scope

Once the gate is open, changes must map to the hydrated child checklist. Adjacent cleanup, unrelated refactors, and private state movement are out of scope unless the issue explicitly includes them.

For the v0.3.0-preview.1 preview release, the scoped work is:

  • anchor the snapshot to agent_bootstrap@v1.4.0-rc.1
  • anchor the runtime boundary to agent-governance-runtime@v0.1.1
  • refresh only allowlisted public-safe code, policy, skill, and shim surfaces
  • remove private operational traces and private runner workflow traces
  • prepare README, changelog, docs, public tests, Mermaid Wiki diagrams, and release notes
  • validate locally with tests and sensitive-string scans
  • push clean preview commits to the public preview repo
  • verify GitHub Actions readback
  • publish and verify the v0.3.0-preview.1 GitHub Release

4. Validate Before Completion

Validation has two parts:

  • local checks, such as python -m pytest, whitespace checks, and sensitive-string scans
  • remote readback, such as GitHub repository metadata, branch SHA, and Actions status

This keeps "it looked done locally" separate from "GitHub has the expected state."

5. Record Evidence

The agent records evidence in the child issue instead of relying on memory. Evidence should include:

  • what changed
  • which validation commands ran
  • commit SHA
  • remote branch readback
  • CI status
  • any known finish blockers or non-goals

6. Finish Or Leave A Clear Handoff

If all governance finish gates pass, the task can be closed. If an environment-specific gate blocks closure, the agent records the blocker and leaves a clear handoff instead of pretending the task is fully closed.

In this preview, the repository, wiki Mermaid diagrams, CI readback, and release readback are treated as separate completion evidence surfaces.

Diagram Versus Context Graph

The Mermaid flowchart above is the human-readable control flow. It is useful for orientation, but it is not itself a context substrate.

For context injection and recovery, the same workflow can be represented as explainable graph nodes: task, issue, checklist, validation command, changed file, commit, CI readback, and completion evidence. See Context Injection And Graphify for the node comparison and the current preview readback.

Clone this wiki locally