# Agents — REBNO

Orientation for agents (Claude Code, GSD subagents, external CLIs) working anywhere under `.planning/`.

`CLAUDE.md` at the repo root is the source of truth. This file mirrors the rules that affect work *inside* `.planning/` so agents that load `.planning/` first don't miss them.

---

## Tagging contract (traceable-reqs)

Every plan that ships an artifact for a requirement embeds a tag in that artifact:

| Stage  | Where                                     | Tag                       |
|--------|-------------------------------------------|---------------------------|
| `doc`  | Markdown (prose, ADRs, runbooks, plans)   | `[doc->REQ-CDOC-01]`      |
| `impl` | TS / Rust / C / C++ / Python comments     | `// [impl->REQ-SRV-03]`   |
| `unit` | Unit-test comments                        | `// [unit->REQ-SRV-03]`   |
| `int`  | Integration / E2E test comments           | `// [int->REQ-CLI-08]`    |

Manifest: `traceable-reqs.toml` at repo root — authoritative for the 61 v1 IDs.

ID mapping: human prose uses `EXT-01`, `SRV-03`, `CLI-08`. Tags use canonical `REQ-EXT-01`, `REQ-SRV-03`, `REQ-CLI-08`. Same requirement, two surface forms.

Rules:

- Tags live in comments for source code; Markdown scans every line.
- Multiple tags per line allowed and counted independently.
- A tag for an ID not in the manifest is an `undeclared_id`.
- A bracketed token containing the literal arrow (hyphen-greater-than) that isn't exactly `[stage→REQ-ID]` is a `parse_error`. No spaces inside the brackets.
- Default `required_stages = ["doc"]`. Phase plans tighten `impl`/`unit` per req at plan time.

Verify:

```bash
pnpm trace:check
pnpm trace:check:json     # for agent / CI consumption
traceable-reqs trace REQ-SRV-03
```

---

## Where to put tags inside `.planning/`

- **PLAN.md / phase plan files** — add `[doc→REQ-…]` next to the section that addresses the requirement, or in a "Requirements addressed" footer block. Plans are doc-stage evidence.
- **VERIFICATION.md** — same convention; the verification of a `doc` requirement is itself doc-stage evidence (one file can carry multiple stages for different reqs).
- **REQUIREMENTS.md** — keeps the human prefix form. Do not double-tag here; the manifest itself is the declaration.
- **ROADMAP.md** — keeps the human prefix form. Optional `[doc→REQ-…]` per phase row when the row is the canonical narrative entry.

---

## When you (the agent) plan or execute a phase

1. Read the phase row in `ROADMAP.md` to learn which requirements the phase covers.
2. For each requirement, decide which stages this phase will produce evidence for. Tag every produced artifact.
3. Before declaring the phase done, run `pnpm trace:check`. Treat any `missing_stage` finding for **this phase's reqs** as a verification failure.
4. Findings that belong to *future* phases are expected — the default `required_stages = ["doc"]` keeps the noise floor low. Don't suppress them by tightening unrelated reqs.

---

## Adding a requirement mid-flight

1. Append the human row to `REQUIREMENTS.md`.
2. Mirror to `traceable-reqs.toml` as `REQ-<PREFIX>-<NUM>`.
3. Update `ROADMAP.md` phase mapping.
4. Run `pnpm trace:check` to confirm the manifest parses.
5. Commit the four files together so the manifest never drifts from the human prose.