Filling Crew roles
Filling Crew Roles
Status: Canonical guide, non-normative. It explains how people, agents, or a mix of the two fill the Crew roles in any project that adopts Builder Garage. It adds nothing. The canonical skills, the responsibility floor, and the project's governance govern (Builder Garage: GOVERNANCE.md). Where this guide and one of them differ, the source governs, and the difference is a defect in this guide.
Who can fill a role
Any person, agent, or tool can fill a Technician role or a workflow position, as long as it meets that role's contract. The contract includes the role's durable record (F9). A person who fills a role writes the same record an agent would, with the same marker and the same garage-evidence block (Review evidence). No separate format exists for people.
Agent #1 and Agent #2 are workflow positions, not kinds of agent. The skills address "the agent", but a person can fill either position.
Filling a Technician role is not exercising a human authority. Accepting a change or its product intent stays with the configured human authorities (E8). Independent review and human acceptance are distinct gates (F11, F12).
Roles and where they stop
Each entry gives what the role answers, where its responsibility ends, and the record it leaves. Follow the links for the procedure.
Technicians
discoveryanswers: what does the existing system actually do?- Ends when the discovery report is durably recorded and verified. It changes nothing, and it does not authorize implementation.
- Record: the discovery report on the originating issue, or on a durable artifact linked from it. See engineering-discovery-workflow: Durable discovery documentation.
readinessanswers: is this change understood well enough to implement?- Ends at one decision,
READYorNOT READY. AREADYreport becomes context for the implementer, and it waives no later gate. See implementation-readiness-workflow: Readiness decision and Handoff to implementation. - Record: when recorded, the readiness report on the governing issue. See Readiness output.
- Ends at one decision,
planneranswers: how should approved work be framed and entered into the backlog?- Ends when the authorized issue is created and read back. The issue starts nothing, and the planner makes no product, workflow, or acceptance decision. See issue-authoring-workflow: Executing role.
- Record: the issue itself, ending with its authoring record. See Authoring record. The other Technicians author their own follow-ups in the same way, under each skill's "Issue authoring" section.
implementeranswers for implementation, correction, and integration-PR finalization. It fills Agent #1 today.- Ends at every handoff to Agent #2, or at a material blocker. The work stays uncommitted until Agent #2 approves it, or, under commit-stage review, is pushed to a branch that is not proposed. See application-implementation-workflow: Role separation and Phase 4.
- Record:
[AGENT #1 — IMPLEMENTATION]and[AGENT #1 — CORRECTION], each with an evidence block. See Durable workflow-state comments. On the pull request, it also records an equivalence record for each pushed head. See integration-pr-review: Artifact equivalence and Durable PR workflow state.
revieweranswers: was the artifact independently shown to be correct? It fills Agent #2 today.- Ends at its verified disposition,
APPROVEDorCHANGES REQUIRED. It never corrects the artifact. It also stops, without a verdict, when valid Agent #1 completion evidence is missing. See independent-implementation-review: Prerequisite and Invocation boundary. - Record:
[AGENT #2 — INDEPENDENT REVIEW]with an evidence block. It is posted on the originating issue, where it is authoritative, or on the pull request for a triggered PR review, where it is supplemental. See Review record.
- Ends at its verified disposition,
Workflow positions
- Agent #1 implements and corrects, then hands the artifact to Agent #2 and stops. It writes only Agent #1 markers (F4). See application-implementation-workflow: Executing agent identity.
- Agent #2 reviews the complete artifact independently, records its disposition, and stops. It writes only the Agent #2 marker. See independent-implementation-review: Executing agent identity.
discovery, readiness, and planner hold no workflow position.
Review evidence: Where each record lives lists every record type, where it is posted, and what it links to.
Separate execution contexts
The same execution context never both implements and independently reviews the same artifact (F1, F2). Each invocation holds one role and stops at its handoff (F3). In practice, separate execution contexts can be:
- two sessions of one tool, where the review session does not carry the implementation session's conversation;
- two different tools;
- two people.
Separation is a recorded assertion. No tool certifies it, and Garage never claims to (F2, Review evidence: What can be checked). garage status reports it as asserted (README: Workflow status).
Contributor-held separation
One operator, a person, may run the implementer and the reviewer as two separate invocations in separate execution contexts, and post both records.
It stays consistent with the floor when:
- F1. The implementing context never reviews. The operator starts the reviewer in a new context that has not seen the implementation conversation, and the reviewer inspects the artifact itself, not Agent #1's summary.
- F2. The two contexts are separate. They may use the same tool or model. The review record asserts the separation, and no tool checks it.
- F3. Each invocation stops at its handoff. The implementer stops at
READY FOR AGENT #2 REVIEW. The operator then starts the reviewer. The implementer does not continue into review.
Both records may be posted from the same GitHub account. That is expected, and it is why role and separation are recorded as assertions (Review evidence: What does not change).
Collaboration patterns
These are illustrations. Each follows the same skills and leaves the same records.
One person with two agent sessions
The person runs Agent #1 in one session and Agent #2 in another, as in Contributor-held separation. Each session is invoked with its own skill, and each posts its own record. The person decides when to start the next session. No session waits for, or starts, another one.
A person implementing, an agent reviewing
The person fills Agent #1 by hand. They implement, run the validation, compute the artifact identity with the reference procedure, and post [AGENT #1 — IMPLEMENTATION] with its evidence block. They then start an agent as Agent #2, under independent-implementation-review, in the same workspace, so it can recompute the identity from the uncommitted working tree. The agent's record is the review. The person does not edit or replace it.
One person implementing, another person reviewing
On the default working-tree path, this works only when the reviewer can reach the implementer's uncommitted working tree, for example in the same workspace or environment. The implementation record identifies a working-tree artifact. Agent #2 confirms it by recomputing the identity at the same stage before reviewing (Prerequisite, check 5). A working-tree artifact is checkable only by someone who holds that working tree (Review evidence: What can be checked).
When the reviewer cannot reach that working tree, the implementer uses commit-stage review, when the issue or the person running the implementation asks for it. The implementer commits and pushes the change to a branch without opening a pull request, and records it at stage: commit. The reviewer fetches that commit, recomputes its identity, and reviews it (#99 decision).
garage status counts a workflow record only when its author is an owner, member, or collaborator of the repository, and reports the others as ignored (README: Workflow status).
Worked example
An illustration of one issue, #N, from implementation through review to the pull request, on the default working-tree path. One operator runs every Technician step in a new session of the same coding agent. The tool is an example only. Any person, agent, or tool could fill each step.
| Step | Role and position | Invocation (example) | Record left | Where |
|---|---|---|---|---|
| 1 | implementer, Agent #1 |
Implement #N using application-implementation-workflow |
[AGENT #1 — IMPLEMENTATION], status ready-for-review, stage: working-tree |
Issue #N |
| 2 | reviewer, Agent #2 |
Review #N using indep-review |
[AGENT #2 — INDEPENDENT REVIEW], verdict changes-required |
Issue #N |
| 3 | implementer, Agent #1 |
Correct #N using application-implementation-workflow |
[AGENT #1 — CORRECTION], status ready-for-re-review |
Issue #N |
| 4 | reviewer, Agent #2 |
Re-review #N using indep-review |
[AGENT #2 — INDEPENDENT REVIEW], verdict approved |
Issue #N |
| 5 | implementer, Agent #1 |
Open the PR for #N using pr-review |
[AGENT #1 — IMPLEMENTATION] equivalence record for the pushed head, equivalent_to the step 4 approval |
The pull request |
| 6 | Change acceptor and product-intent acceptor (people) | — | Acceptance, as the project's governance records it | The pull request |
- The implementer works in the issue branch, leaves the change uncommitted, records its identity, and stops (Mandatory hold point).
- A new session reviews. It first recomputes the
changesetand confirms that it matches step 1. It finds a blocker, recordsCHANGES REQUIRED, and stops. - A new implementer session corrects the change, records the new identity, and stops.
- A new reviewer session reviews the complete corrected artifact, not only the correction (F6). It approves and stops.
- A new implementer session confirms that the working tree still has the approved
changeset. It commits exactly that change, pushes it, opens the pull request against the integration branch (E1), and records equivalence. No PR-review trigger applies, so no PR review follows (integration-pr-review: PR-review triggers). - The configured human authorities accept the change and its product intent. The pull request merges after its remaining gates pass.
Builder Garage example: the integration branch is main, a maintainer approves the pull request, and the Workflow Owner accepts product intent (CONTRIBUTING: How a substantive change proceeds).
What this guide does not change
This guide adds no role, gate, ceremony, record, or authority. It does not assign, invoke, or schedule anyone. New Technicians are added only through a framework change (Crew).
