Skip to content

Workflow Overview

Jump to bottom
ClarusIubar edited this page Jun 7, 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 this preview repository, the scoped work was:

  • select public-safe files from the source reference
  • remove private operational traces
  • prepare README, license, docs, tests, and wiki pages
  • validate locally and in GitHub Actions
  • push a clean initial commit to the private preview repo

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 and wiki were prepared and pushed. The repository remains private by design until the owner switches it to public.

Why This Is Useful For Reviewers

The workflow gives reviewers concrete things to inspect:

  • issue structure, not just prose
  • explicit edit authority
  • architecture boundary before implementation
  • scoped file changes
  • local validation
  • remote CI/readback
  • completion evidence

That is the main claim of the project: agent work should be auditable from durable artifacts, not reconstructed from a chat transcript.

Clone this wiki locally