C64-dev/newLang/planning/agent-workflow.md

---

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

---
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.