Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 3 additions & 3 deletions .agents/methodology.md
Original file line number Diff line number Diff line change
Expand Up @@ -90,7 +90,7 @@ is that the expensive-to-reverse decisions are made, not that it is small.
**Program design** — the target shape inside the agreed architecture: files,
seam signatures, test order — is deliberately NOT written with the spec.
Designing slice 6's files before slices 1–3 have taught anything produces
stale guesses. The Crewmate writes it at the plan step, with the real code
stale guesses. The Mason writes it at the plan step, with the real code
in view, and **persists it in the work document** before any code; the
Architect reads and approves it there. Three reasons to persist it:

Expand All @@ -105,15 +105,15 @@ Architect reads and approves it there. Three reasons to persist it:

The delegation boundary is the **system design**: above it the *what* —
architecture, scope, seams — settled in the spec; below it the *how*,
designed and typed by the session that implements. A Crewmate asked to
designed and typed by the session that implements. A Mason asked to
"figure out" something the *what* left open is a specification failure, and
it goes back to the spec. An open *how* is not a hole: it is what the plan
step is for.

Once the plan is approved it is a complete brief, which is what makes a
Typist possible: a cheaper model types a settled plan, and the frontier
tier is kept for judgement — the spec, the plan, the review. So the
Crewmate hands the typing to a Typist by default. A Crewmate that types its
Mason hands the typing to a Typist by default. A Mason that types its
own plan pays the frontier price for typing: on 2026-11-03 one of chisel's
own tasks ran 383 calls, all at the frontier tier, none of them a Typist's.
The brief is **artifacts
Expand Down
8 changes: 4 additions & 4 deletions .agents/reference.md
Original file line number Diff line number Diff line change
Expand Up @@ -12,7 +12,7 @@ for every session are `.agents/discipline.md`.
|---|---|
| **Task** | The unit of work. Its spec document lives in the task workspace declared in `.agents/project.md` (default `/project-management/tasks/`), named `<time-id>-<intention>.spec.md`, whatever tracker also carries it; once planned it has a matching `<time-id>-<intention>.work.md` beside it. |
| **Spec document** | The review surface and the requirement: intent, acceptance criteria, seams, system design, decisions, testing strategy, slices, deliverables, references, pre-plan Notes and retrospective. It carries the task's status line and the reading gradient's two 🧑 zones. |
| **Work document** | The Crewmate's companion file, created at the plan step beside the spec document. It carries the program design and its approval line, the worklog, the implementation checkboxes, Notes & Snippets and the review findings. No zone marker. |
| **Work document** | The Mason's companion file, created at the plan step beside the spec document. It carries the program design and its approval line, the worklog, the implementation checkboxes, Notes & Snippets and the review findings. No zone marker. |
| **Slice** | A child task produced by cutting a large task: a tracer-bullet vertical cut through every layer, demoable on its own, sized for one fresh context window. Lives as `tasks/<time-id>-<feature>/<NN>-<slug>.spec.md`. A small task IS its own single slice. |
| **Seam** | The public boundary where a feature is tested — named in the spec BEFORE implementation. Tests live at seams, never against internals. Fewer is better (ideal: one). |
| **Reading gradient** | The ordering of the spec document by review criticality: 🧑 REVIEW CAREFULLY (short, decision-rich) → 🧑 REVIEW IF RELEVANT. Detail is never cut, it is ordered. |
Expand All @@ -22,7 +22,7 @@ for every session are `.agents/discipline.md`.
| **Expand–contract** | The sequencing for wide mechanical refactors (rename a column, retype a shared symbol): add the new form beside the old → migrate call sites in batches → delete the old form. The exception to vertical slicing. |
| **One-shot** | Work done without a task artifact. The discipline still applies; only the file bookkeeping is skipped. |

The roles — Architect, Crewmate, Typist, reviewers — are defined in "The
The roles — Architect, Mason, Typist, reviewers — are defined in "The
roles" of `.agents/workflow.md`.

We do NOT use the word "ticket" for local work. It is reserved for items in an
Expand All @@ -36,7 +36,7 @@ decision tickets and resolves them one at a time).
A 🧑 zone belongs to whoever **approved** it. The human approves a spec that
carries decisions the task did not state; the Architect approves one written
from a clear task, and then the zones carry the task's own decisions, which
are the human's. The work document has no zone: it belongs to the Crewmate
are the human's. The work document has no zone: it belongs to the Mason
that wrote it. A 🧑 zone is never overridden silently — a conflict with one
is surfaced, never edited sideways.

Expand All @@ -47,7 +47,7 @@ the work — how much judgement it needs.

| Tier | What it is for | Roles |
|---|---|---|
| **frontier** | Thinking and reviewing — where a wrong judgement is expensive and caught late | Architect, Crewmate, reviewers |
| **frontier** | Thinking and reviewing — where a wrong judgement is expensive and caught late | Architect, Mason, reviewers |
| **mid** | Ordinary work that needs competence but not judgement | The Typist, by default |
| **cheap** | Typing a mechanical plan: every change named down to its file and place, nothing left to choose | The Typist, when the plan is mechanical |

Expand Down
2 changes: 1 addition & 1 deletion .agents/skills/chisel-beads/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -28,7 +28,7 @@ bd list --status draft # any other status is a filter
```sh
bd create "<the task's title>" --type task --priority <0-4> \
--spec-id "<path to the spec document, from the repo root>" \
--actor <architect|crewmate|typist> --silent
--actor <architect|mason|typist> --silent
```

`--spec-id` is the whole link; the work document's path follows from it.
Expand Down
2 changes: 1 addition & 1 deletion .agents/skills/retro/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -104,7 +104,7 @@ discussed:
### Implementation vs review

All work goes through two stages: implementation and review. The
implementation session (the Crewmate writing its program design at the plan
implementation session (the Mason writing its program design at the plan
step, then typing it) carries the most context pressure — exploration, writing
code, debugging failures. The review sub-agents carry the least —
it receives a diff, no exploration needed. This is why coding standards
Expand Down
4 changes: 2 additions & 2 deletions .agents/skills/slice-task/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -89,7 +89,7 @@ where `<time-id>` comes from `scripts/task-id.sh` and `<NN>` numbers the
slices from `01` in dependency order (blockers first). The parent spec
document (if one exists) stays in place and links to the slice folder.

No work document is created here. The Crewmate that implements a slice creates
No work document is created here. The Mason that implements a slice creates
the matching `<NN>-<slug>.work.md` beside it at its `plan` step, from the work
template declared in §A · Task workspace of `.agents/project.md`.

Expand Down Expand Up @@ -122,7 +122,7 @@ user's perspective — not a layer-by-layer implementation list.
## Notes

_A question or a blocker met before the plan — only what is written into
this document before its work document exists. Not the Crewmate's working
this document before its work document exists. Not the Mason's working
space: its notes, snippets and worklog live in the work document._

</slice-template>
Expand Down
45 changes: 24 additions & 21 deletions .agents/workflow.md
Original file line number Diff line number Diff line change
Expand Up @@ -18,9 +18,9 @@ or a script.

| Role | Who plays it | What it does |
|---|---|---|
| **Architect** | The agent a human, or an orchestrator, talks to. This is its default role. | Reads the task, writes or sharpens the spec, launches a Crewmate and talks with it, reads and corrects the plan, rules on what the Crewmate reports, brings the key questions to the human. |
| **Crewmate** | A sub-agent launched by the Architect. | Writes the plan in the work document and stops for the Architect's reading. Then launches a Typist to code it, runs `code-review`, and closes the task. |
| **Typist** | A sub-agent launched by the Crewmate once the plan is approved. | Types code from the approved plan and decides nothing, at a cheaper tier than the Crewmate's (`.agents/reference.md`, "Model tiers"). |
| **Architect** | The agent a human, or an orchestrator, talks to. This is its default role. | Reads the task, writes or sharpens the spec, launches a Mason and talks with it, reads and corrects the plan, rules on what the Mason reports, brings the key questions to the human. |
| **Mason** | A sub-agent launched by the Architect. | Writes the plan in the work document and stops for the Architect's reading. Then launches a Typist to code it, runs `code-review`, and closes the task. |
| **Typist** | A sub-agent launched by the Mason once the plan is approved. | Types code from the approved plan and decides nothing, at a cheaper tier than the Mason's (`.agents/reference.md`, "Model tiers"). |
| **Reviewers** | Sub-agents launched by the `code-review` skill. | Read the diff with no context from the session that wrote it. |

**The human** owns the intent and the decisions that shape the task. The
Expand All @@ -29,7 +29,7 @@ made goes back to the human, with the question stated.

The Architect's thread can be one long thread that compacts and serves as
the entry point to a project, or one thread per piece of work. In a long
thread the Architect can run several Crewmates, one per task or slice.
thread the Architect can run several Masons, one per task or slice.

## The steps

Expand All @@ -52,22 +52,22 @@ The human approves the spec when it carries decisions the task did not
state; otherwise the Architect moves it to `ready` itself. Commit the spec.
Status: `draft`, then `ready`.

**3. Plan — Crewmate.** The Architect launches a Crewmate with the brief
below. The Crewmate reads the spec document and what it links to, creates
**3. Plan — Mason.** The Architect launches a Mason with the brief
below. The Mason reads the spec document and what it links to, creates
the work document beside it from the work template, and persists its
program design there: files, seam signatures, test order, the decisions the
spec left to the implementation. Then it stops and reports. No code before
the plan is approved. Status: `in-progress`, written by the Architect at
launch.

**4. Read the plan — Architect.** Read the spec and the work document,
nothing else. Correct the plan with the Crewmate, then approve it: the
nothing else. Correct the plan with the Mason, then approve it: the
approval is written on the work document's `**Plan:**` line, with who and
when. A plan that departs from a decision the human made goes to the human
first.

**5. Code — a Typist the Crewmate launches.** Once the plan is approved,
the Crewmate launches a Typist with the brief below. The Crewmate types
**5. Code — a Typist the Mason launches.** Once the plan is approved,
the Mason launches a Typist with the brief below. The Mason types
itself only a retouch of a few lines, or while the plan is not settled, and
writes which exception applies and why in the work document's worklog. The
Typist executes the approved plan in vertical steps, test-first at the
Expand All @@ -77,12 +77,12 @@ and commit at each green step. Run the gate commands declared in
`.agents/project.md`. Reality that contradicts the plan is fixed in the
plan, in writing; reality that contradicts the spec is reported.

**6. Review — Crewmate.** Run the `code-review` skill on the full diff of
**6. Review — Mason.** Run the `code-review` skill on the full diff of
the task. Its reviewers are fresh sub-agents that never saw the session
that wrote the code — never skip this step, even for a small retouch. Write
the findings in the work document; fix each one or answer it there.

**7. Close — Crewmate.** Tick the spec's acceptance criteria against
**7. Close — Mason.** Tick the spec's acceptance criteria against
reality. Promote evergreen material into the living docs declared in
`.agents/project.md`, the glossary and the ADRs among them. Archive the spec and work documents together. Add the
dated journal entry. Run the `retro` skill and put its proposals in the
Expand All @@ -102,8 +102,8 @@ explicit word on that very action is the only go.

| Who stops | For whom | When |
|---|---|---|
| Crewmate | Architect | After the plan; after the close, with its report; on a blocker it cannot rule on |
| Typist | Crewmate | After its part of the plan; on anything the plan does not answer |
| Mason | Architect | After the plan; after the close, with its report; on a blocker it cannot rule on |
| Typist | Mason | After its part of the plan; on anything the plan does not answer |
| Architect | Human | On an unclear intent; on a spec that carries decisions the task did not state; on a plan that departs from the human's decisions; on a blocker above what it owns |
| Architect | Human | Before a merge or a publish, unless the project lets the agent do it |

Expand All @@ -126,7 +126,7 @@ A task has one status. The thread doing a step writes the status it leaves.
|---|---|---|
| `draft` | The spec is being written, or waits for the human's approval | step 2 |
| `ready` | The spec is approved and nothing holds the task | step 2 |
| `in-progress` | A Crewmate is planning, coding, reviewing or closing it | step 3 |
| `in-progress` | A Mason is planning, coding, reviewing or closing it | step 3 |
| `done` | Criteria ticked, documents archived | step 7 |
| `blocked` | Held by a named dependency, written after the value | whoever meets the block |
| `deferred` | Postponed on purpose | the human |
Expand All @@ -143,21 +143,21 @@ Launch one only for a context that must stay clean, for work that runs in
parallel, or for a cheaper model. Each one costs tokens and a brief to
write. Three earn it:

- **The Crewmate** keeps the Architect's context clean for reading the plan
- **The Mason** keeps the Architect's context clean for reading the plan
and ruling on reports.
- **The Typist** types the approved plan on a cheaper tier than the
Crewmate's.
Mason's.
- **The reviewers** bring fresh eyes to the diff.

A brief is artifacts and paths, never the conversation: whatever the
sub-agent needs must already be in the repo. Reviewers are always fresh. A
Crewmate is reused within a live thread — the one that wrote the plan
Mason is reused within a live thread — the one that wrote the plan
launches its Typist and runs the review — and a resumed task starts fresh
from the spec and work documents.

## The Crewmate brief
## The Mason brief

What the Architect writes when it launches a Crewmate:
What the Architect writes when it launches a Mason:

- the spec document's path, and the work template's;
- the branch to work on, and how to commit (explicit paths, no push);
Expand All @@ -169,14 +169,17 @@ What the Architect writes when it launches a Crewmate:

## The Typist brief

What the Crewmate writes when it launches a Typist:
What the Mason writes when it launches a Typist:

- the approved work document's path, and the part of the plan to type;
- its tier: *cheap* when the plan is mechanical, *mid* otherwise
(`.agents/reference.md`, "Model tiers", which also resolves the model);
- the branch, the gate commands, the commit rule;
- type the plan and decide nothing: anything the plan does not answer is
reported, not guessed.
reported, not guessed;
- tick a box only for what really ran, on the real target; a dry run, or
a run on a copy or a test base, is written in the worklog and leaves
its box open.

## Blockers and questions

Expand Down
7 changes: 4 additions & 3 deletions AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -11,7 +11,8 @@ methodology it ships.
record (`project-management/review-360-decisions.md`), the doctrine — never
in an assistant's private memory: future agents are not necessarily the
same assistant (Owner ruling G17, 2026-09-02). Role reuse follows ruling
G16: reviewers fresh, the Crewmate reused within a live thread.
G16: reviewers fresh, the Mason (named the Crewmate in the record)
reused within a live thread.
- The canonical socle now lives in `socle/` (imported from the music-downloader
pilot at slice 01).

Expand All @@ -38,9 +39,9 @@ takes one task from its intent to its commit and pull request, in prose:
the roles, the steps, where the work stops, the tracker and the statuses.

- By default you are the **Architect**: you read the task, write or sharpen
the spec, launch a Crewmate, read its plan, and bring the key questions to
the spec, launch a Mason, read its plan, and bring the key questions to
the human.
- Launched as a **Crewmate** or a **Typist**, follow the brief you were
- Launched as a **Mason** or a **Typist**, follow the brief you were
given and the matching steps of `.agents/workflow.md`.
- Merging and publishing follow the merge and publish section of
`.agents/project.md`. By default they wait for the human's explicit word
Expand Down
12 changes: 6 additions & 6 deletions CHARTER.md
Original file line number Diff line number Diff line change
Expand Up @@ -22,7 +22,7 @@ has the task, it follows chisel's method to ship it.
scheduling tasks, deciding on its own which task runs next: that belongs to
the layer above. That layer can be a human, a harness, a long-lived
orchestrator thread, or a script. Inside a conversation, the Architect
running the Crewmates of the tasks it was given is part of processing
running the Masons of the tasks it was given is part of processing
tasks, not orchestration.

**The workflow is prose.** One page describes the steps of a task, who does
Expand Down Expand Up @@ -56,18 +56,18 @@ field facts behind this page are in the decisions record,

| Role | Who plays it | What it does |
|---|---|---|
| **Architect** | The agent the user, or an orchestrator, talks to: the project lead. This is its default role; nobody launches an Architect. | Scopes the task, asks the questions, clarifies the spec. Launches a Crewmate, talks with it, arbitrates, reads and corrects the plan. Brings the key questions up to the human. |
| **Crewmate** | A sub-agent launched by the Architect. | Writes the plan from the template, stops for the Architect's reading, then has a Typist code it. Runs the `code-review` skill and fixes what it finds. |
| **Typist** | A sub-agent launched by the Crewmate once the plan is approved. | Types code from the approved plan, decides nothing, on a cheaper model than the Architect and the Crewmate. The Crewmate types itself only a retouch of a few lines, or while the plan is not settled. |
| **Architect** | The agent the user, or an orchestrator, talks to: the project lead. This is its default role; nobody launches an Architect. | Scopes the task, asks the questions, clarifies the spec. Launches a Mason, talks with it, arbitrates, reads and corrects the plan. Brings the key questions up to the human. |
| **Mason** | A sub-agent launched by the Architect. | Writes the plan from the template, stops for the Architect's reading, then has a Typist code it. Runs the `code-review` skill and fixes what it finds. |
| **Typist** | A sub-agent launched by the Mason once the plan is approved. | Types code from the approved plan, decides nothing, on a cheaper model than the Architect and the Mason. The Mason types itself only a retouch of a few lines, or while the plan is not settled. |
| **Reviewers** | Sub-agents launched by the `code-review` skill. | Read the diff with no context from the coding session. |

**The Architect's thread** is best kept long: one thread that compacts and
serves as the entry point to a project, holding the context of several
tasks. The article above recommends the same shape for a main agent loop.
It can also be one thread per piece of work. In a long thread the Architect
runs several Crewmates, one per task or slice.
runs several Masons, one per task or slice.

**The fixes after a review belong to the Crewmate** that wrote the code,
**The fixes after a review belong to the Mason** that wrote the code,
not to the Architect.

**A role is a paragraph of the workflow, not a file.** The Architect writes
Expand Down
Loading
Loading