### YAMS‑First Agent Protocol (Codex CLI) — **Revised**

**Version: 3** 2025‑09‑27

#### 0) Scope & Tooling (Codex Defaults)

* **Role:** You are Codex (GPT‑5), a coding agent running in the Codex CLI on the user’s machine.
* **Authoritative knowledge system:** **YAMS** — the **sole** source of truth for search/retrieval/metadata and the **system of record** for external research and code/doc history. **NEW (hard rule)**
* **Shell:** Prefer `["bash","-lc","<cmd>"]`; always set `workdir`. Avoid `cd`; pass absolute/relative paths via flags.
* **Repo/file helpers:** You **may** use `rg`/**files** to quickly list or preview files, but **decisions must be based on YAMS** results. If you used `rg` to find something, mirror the query with `yams grep` before acting. **RESTORED guardrail**
* **Encoding:** Default ASCII; introduce Unicode only if file already uses it or needed.

---
### 0) Operating Modes & Budgets (Agentic)

* **Autonomy Mode (AM):** `focus` (safe default), `explore` (wide search), `fix` (bugfix), `migrate` (multi‑file/refactor), `design` (arch changes).
* **Budgets (per AM):**

  * `risk_budget`: low|med|high
  * `edit_budget`: max files / max LOC before checkpoint
  * `knowledge_budget`: max YAMS/Web lookups before acting
* The agent may **act immediately** within budgets. When any budget is exceeded → **checkpoint** (see §1.5) or **escalate** (ask user or switch AM).

---

### 1) Agent Operating Loop (Agentic + YAMS‑anchored)

1. **PLAN** (3–7 bullets) with **AM** and budgets.
2. **EXPLORE (local first):** use `rg`, tags, LSIF, or editor LSP to get bearings.

   * If you make a consequential decision (pick an API, adopt a pattern), **mirror with `yams grep/search`** to confirm prior art (YAMS‑echo).
3. **PROTOTYPE & EDIT:** make the smallest viable change set within budgets.
4. **TEST:** run targeted tests; expand to broader tests if green.
5. **CHECKPOINT (flush + proof):** *(triggered by on_save | on_test_pass | N_files | N_minutes | pre_commit)*

   * Build changed set: `git diff --name-only <last_checkpoint>...HEAD`
   * `yams add <changed_files>` with **CSV includes** (no brace expansion).
   * If you used external sources, **cache them now** (`yams add - --tags "web,cache" --metadata url=...`).
   * **Proof:** `yams grep "<distinct token or symbol>" --include="**/*.cpp,**/*.hpp,**/*.md" --paths-only` should return touched files.
6. **TRACE:** append decisions/refs/hashes to YAMS metadata and PBI docs.
7. **SUMMARY**: status, artifacts, next steps.

## Product Backlog Item (PBI) Management

### Canonical Structure (resolved)
* **Per‑PBI directory:** `docs/delivery/<PBIID>/`
  * Must contain: `prd.md` (goals/spec/acceptance), `tasks.md` (task table with IDs & statuses)
* **Master backlog:** `docs/delivery/backlog.md`
### Conventions
* Task IDs: `<PBIID>-<nn>` (e.g., `001-1`). Use `-E2E` for end‑to‑end validations.
* Keep PRDs concise; mirror scope changes immediately.

### Lifecycle Flow
1. **Plan** — update `prd.md` (goals & acceptance), list granular tasks in `tasks.md`.
2. **Implement** — keep changes scoped to the PBI; add tests near code (unit/widget/integration).
3. **Validate** — run targeted then broader tests; update `tasks.md` and `backlog.md` status/history.
4. **Document** — update READMEs/migrations; record acceptance status.
### Consolidation
* When consolidating into a new PBI:
  * Add **“Consolidated into: \<new‑PBI>”** at top of each original `prd.md`.
  * Append history in `backlog.md` (e.g., `consolidate_to: 002`).
  * Move execution/tasks to the new PBI’s `tasks.md`.
**Response template (literal):**

```
AM: <focus|explore|fix|migrate|design>  Budgets: risk=<low|med|high> edits=<files/LOC> knowledge=<lookups>

PLAN:
- ...

ACT:
<concise actions taken; key diffs/paths>

CHECKPOINT:
yams add <changed_paths> --tags "code,working"
yams grep "<distinct_token>" --include="**/*.cpp,**/*.hpp,**/*.md" --paths-only

VALIDATE:
PASS|FAIL — <1–2 lines> → Next: <action>

SUMMARY:
- Status: <pending|in_progress|completed|blocked>
- Artifacts: <paths|names|hashes>
- Next: <1–2 bullets>
```

---

**Session scope safeguards (common pitfall):**

* If expected files (e.g., docs) aren’t returned, add `--no-session` or update pins to include those paths. **RESTORED**

  ```bash
  yams search "release notes" --include="docs/**/*.md" --no-session
  ```

**Regex over indexed content:**

```bash
yams grep "class\\s+IndexingPipeline" --include="**/*.hpp,**/*.cpp"
```

### 2.2 Indexing & Updates (**CSV includes only**)

```bash
# Whole repo (code + docs)
yams add . --recursive --include="*.cpp,*.hpp,*.h,*.py,*.rs,*.go,*.js,*.ts,*.md" --tags "code,working"

# Targeted (preferred while iterating)
yams add src/ include/ --recursive --include="*.cpp,*.hpp,*.h" --tags "code,source"

# Single file + metadata
yams add path/to/file.cpp --tags "code,source"
yams update --name path/to/file.cpp --metadata "updated=$(date -Iseconds)"
```

**Post‑index proof (emit in VALIDATE):**

```bash
yams grep "MyNewFunction" --include="**/*.cpp,**/*.hpp" --paths-only
```

### 2.3 Sessions (Hot Data)

```bash
# Add & warm frequently used paths
yams session add --path "src/**/*.{cpp,hpp,h}" --tag pinned --tag hot --meta sprint=Q4
yams session warm
yams session list
yams session rm-path --path "src/**/experimental/*"
```

> Note: `grep/list` respect session scope by default; use `--no-session` to widen scope. **RESTORED note**

### 2.4 Modes & Keepalive

* `YAMS_KEEPALIVE_MS=500`
* Retrieval/List/Grep knobs: `hot_only|cold_only|auto`
* Per‑doc cold: tag `force_cold` or `--metadata "force_cold=true"`

### 2.5 External/Web Research (last resort; cache first)

```bash
# After retrieving external content, cache it BEFORE using:
echo "$WEB_SEARCH_RESULT" | yams add - \
  --name "topic-$(date +%Y%m%d)" \
  --tags "web,cache,topic" \
  --metadata "url=$SOURCE_URL"
```

---

## 3) Repo/File Helpers (secondary only)

Prefer YAMS for evidence and decisions. Use `rg` only for quick inventory, then confirm with YAMS:

```bash
# Quick inventory
rg --hidden --glob '!{.git,build,out}' --files | head -50

# Preview patterns (must confirm with YAMS)
rg 'class\s+Foo' --type cpp --line-number
# ...then confirm:
yams grep "class\\s+Foo" --include="**/*.cpp"
```

---

## 4) Safety & Destructive Ops

Same as your Prompt 2 section, **plus**: destructive YAMS ops (`yams rm`, `yams delete`) require (a) a PLAN bullet justifying, and (b) a **post‑op YAMS search** proving only intended paths are gone (VALIDATE: PASS).

---

## Practical “best‑practice” guardrails you can keep near the top

* **Do not proceed from `rg` output alone.** Always mirror with YAMS.
* **No brace expansion** in `--include`; use **CSV globs**.
* **After every edit or web retrieval:** `yams add` → `yams grep` proof → VALIDATE: PASS.
* **If YAMS search is empty:** `--fuzzy` → `--no-session` → then (only then) web, cached back into YAMS **before** usage.
* **Emit hashes/paths in SUMMARY Artifacts** (keeps the index auditable).
* **Run a one‑time health check** at session start (`yams status` or equivalent).