DOX: declare `roam/` as the ADADR control plane and align RAGE with the canonical skills #17

New issue

Open

opened 2026-08-24 00:45:33 +00:00 by lost-rob0t · 0 comments

lost-rob0t commented

2026-08-24 00:45:33 +00:00

(Migrated from github.com)

Problem

The repository root AGENTS.md currently does not define a durable ADADR control-plane location. The canonical adadr skill requires workers to discover a repository-defined location/workflow and explicitly says not to invent research/, design/, adadr/, or approval directories. The canonical rage skill now delegates architecture reasoning to ADADR while RAGE owns queue selection, run identity, TDD, exact-head verification, PR handling, merge gates, and backlog continuation.

Several existing a0-symbolics issues (#1, #2, #3, #5) still use the older prompt-local RAGE = Review -> Analyze -> Generate -> Execute definition. That is now stale relative to the canonical skills repo.

The canonical RAGE helper also has a separate durable run-evidence convention: branch rage/<issue>-<slug> and default run log rage/<issue>-<slug>.org.

Required repository contract

Update the root project instructions so future workers can resolve the ADADR discovery gate without asking again:

ADADR control plane: roam/
- research / Analyze evidence
- design records
- adversarial-review evidence
- decision / human approval state
- architecture revisions and supersession records
roam/ is only the canonical placement of ADADR control-plane artifacts. Do not reinterpret it as the RAGE run-log directory.
RAGE run evidence remains separate: rage/<issue>-<slug>.org on branch rage/<issue>-<slug> unless a more specific repository contract intentionally overrides the canonical helper.
RAGE must load/follow the canonical adadr skill for architecture reasoning.
In ADADR mode: research -> explicit research approval -> design -> explicit design approval -> implementation.
In Auto-RAGE mode: RAGE performs the full ADADR Analyze -> Design -> Adversarial review -> Decision -> Realize loop and records the decision before implementation.
Repository instructions and current evidence remain authoritative; neither skill may silently invent another control plane.

Existing backlog reconciliation

Review #1, #2, #3 and especially #5 and remove/supersede the obsolete local definition of RAGE as a four-word architecture loop. Preserve useful backlog requirements, but make their workflow terminology point at the canonical rage + adadr skills instead of maintaining a second incompatible definition.

Acceptance

Root AGENTS.md explicitly declares roam/ as the repository's ADADR control plane.
Root AGENTS.md explicitly keeps RAGE run logs/evidence under rage/ per the canonical RAGE helper.
No repository instruction invents an adadr/, research/, or design/ tree as a second control plane.
#1/#2/#3/#5 no longer teach a conflicting RAGE meaning.
Human approval semantics in ADADR mode remain explicit and cannot be inferred from CI/merge/model confidence.
Auto-RAGE remains an explicit durable mode, not something a worker silently selects.
The wording is concise project policy; detailed loop semantics remain owned by the canonical skills repo.

## Problem The repository root `AGENTS.md` currently does not define a durable ADADR control-plane location. The canonical `adadr` skill requires workers to discover a repository-defined location/workflow and explicitly says not to invent `research/`, `design/`, `adadr/`, or approval directories. The canonical `rage` skill now delegates architecture reasoning to ADADR while RAGE owns queue selection, run identity, TDD, exact-head verification, PR handling, merge gates, and backlog continuation. Several existing a0-symbolics issues (#1, #2, #3, #5) still use the older prompt-local `RAGE = Review -> Analyze -> Generate -> Execute` definition. That is now stale relative to the canonical skills repo. The canonical RAGE helper also has a separate durable run-evidence convention: branch `rage/<issue>-<slug>` and default run log `rage/<issue>-<slug>.org`. ## Required repository contract Update the root project instructions so future workers can resolve the ADADR discovery gate without asking again: - **ADADR control plane:** `roam/` - research / Analyze evidence - design records - adversarial-review evidence - decision / human approval state - architecture revisions and supersession records - `roam/` is only the canonical placement of ADADR control-plane artifacts. Do not reinterpret it as the RAGE run-log directory. - **RAGE run evidence remains separate:** `rage/<issue>-<slug>.org` on branch `rage/<issue>-<slug>` unless a more specific repository contract intentionally overrides the canonical helper. - RAGE must load/follow the canonical `adadr` skill for architecture reasoning. - In ADADR mode: `research -> explicit research approval -> design -> explicit design approval -> implementation`. - In Auto-RAGE mode: RAGE performs the full ADADR Analyze -> Design -> Adversarial review -> Decision -> Realize loop and records the decision before implementation. - Repository instructions and current evidence remain authoritative; neither skill may silently invent another control plane. ## Existing backlog reconciliation Review #1, #2, #3 and especially #5 and remove/supersede the obsolete local definition of RAGE as a four-word architecture loop. Preserve useful backlog requirements, but make their workflow terminology point at the canonical `rage` + `adadr` skills instead of maintaining a second incompatible definition. ## Acceptance - [ ] Root `AGENTS.md` explicitly declares `roam/` as the repository's ADADR control plane. - [ ] Root `AGENTS.md` explicitly keeps RAGE run logs/evidence under `rage/` per the canonical RAGE helper. - [ ] No repository instruction invents an `adadr/`, `research/`, or `design/` tree as a second control plane. - [ ] #1/#2/#3/#5 no longer teach a conflicting RAGE meaning. - [ ] Human approval semantics in ADADR mode remain explicit and cannot be inferred from CI/merge/model confidence. - [ ] Auto-RAGE remains an explicit durable mode, not something a worker silently selects. - [ ] The wording is concise project policy; detailed loop semantics remain owned by the canonical skills repo.