---
type: agent-workflow
source-path: project collaboration requirements
ingested-at: 2026-11-07
---

# Agent Workflow

This process lets multiple agents contribute without treating chat history as
the project database.

## 1. Global Implementation Gate

The user requested approval before coding. Until the user explicitly approves
implementation, agents may improve specifications, investigate read-only facts,
or propose decisions, but must not add compiler/runtime implementation.

After approval, dependency-free stories may move from `planned` to `ready`.

## 2. Before Claiming Work

1. Read `../AGENTS.md` and the documents it routes to.
2. Run `git status --short` and preserve unrelated changes.
3. Read all files in `planning/claims/`.
4. Select one story whose dependencies are complete.
5. Confirm its expected file area does not overlap an active claim.
6. Create a claim file named exactly `<story-id>.md`.

Do not edit a shared central status table merely to claim a story. Separate
claim files reduce merge conflicts.

## 3. Claim Template

```markdown
---
story: E00-S00
owner: agent-name-or-session
status: in-progress
started: YYYY-MM-DD
depends-on: []
---

# E00-S00 Claim

## Intended change

One paragraph describing the bounded result.

## File area

- Exact files or directories expected to change

## Acceptance evidence

- [ ] Criterion copied from the backlog

## Coordination notes

- Known overlaps, messages sent, or assumptions

## Work log

- Commands and important findings

## Completion

- Tests run:
- Results:
- Files changed:
- Remaining risks:
```

Valid claim statuses are `in-progress`, `blocked`, `review`, and `done`.
Agents must not mark a claim `done` when required verification is unavailable.

## 4. Story Execution

- Work only on the claimed behavior.
- Use `apply_patch` for hand-authored file edits.
- Keep generated files under `build/`.
- Add a failing test or fixture before, or in the same change as, behavior when
  practical.
- Prefer explicit error returns and bounded tables over implicit assumptions.
- Record discovered platform facts in the relevant document with evidence.
- If implementation conflicts with the spec, stop and open a decision; do not
  quietly make the implementation the new specification.

## 5. Blocking and Handoff

A blocked claim must state:

- the exact failed acceptance criterion;
- evidence already collected;
- the smallest decision or external fact needed;
- safe work that remains possible without that decision.

For a handoff, leave the claim in `in-progress` or `blocked`, summarize the
current state, and list the next command or file to inspect. Do not create
ambiguous half-completed status.

## 6. Review

A reviewer should verify:

- the story did not expand scope;
- all acceptance criteria have direct evidence;
- source and generated artifacts are distinguishable;
- MMU/KERNAL behavior was tested in `x128` when relevant;
- no writable reference/editor image was modified;
- error paths and capacity boundaries were exercised;
- docs and stable diagnostic IDs remain synchronized.

When review passes, update the claim to `done` with the evidence. The backlog
itself remains a stable specification of work rather than a frequently edited
task board.

## 7. Decisions and ADR-Like Records

Small implementation choices can be recorded in a claim. A choice requires an
entry in `docs/decisions.md` when it changes:

- user-visible syntax or semantics;
- compiler/runtime ABI;
- object or interface layout;
- source, PRG, ERR, or MAP formats;
- memory ownership;
- supported hardware or editor workflow;
- version 1 scope.

Use a new `Dxxx` identifier. Mark it `Proposed` until the user approves a
visible or scope-changing decision.

## 8. Parallel Work Guidance

Safe early parallel lanes after implementation approval include:

- E01 platform probes, provided each uses separate PRG/linker targets;
- E02 diagnostic catalog and lexer fixtures;
- E06 host-side disk-copy scripts using disposable images;
- E07 test harness scaffolding that does not invent runtime addresses.

Do not parallelize two agents into the same assembly module or linker config.
The class ABI and interface ABI must be frozen before multiple backend agents
depend on them.