Artifact [321e31f8fe]

Artifact 321e31f8fe0f207cbe8651d51d3e12485a0b23903ebbc0187a47f8a1a77c6dd8:

• File docs/agents/domain.md — part of check-in [f894e896c1] at 2026-05-04 16:50:06 on branch trunk — chore(agents): scaffold ## Agent skills section + docs/agents/ (#107)

  Adds the per-repo configuration that the engineering skills (triage, to-issues, to-prd, diagnose, tdd, improve-codebase-architecture) assume:

  - Issue tracker mapping → docs/agents/issue-tracker.md (GitHub via gh CLI) - Triage label vocabulary → docs/agents/triage-labels.md (canonical names; needs-triage, needs-info, ready-for-agent, ready-for-human, wontfix) - Domain doc layout → docs/agents/domain.md (single-context; ADRs live in docs/architecture/, no CONTEXT.md so skills fall back to CLAUDE.md + MEMORY.md)

  CLAUDE.md gets an ## Agent skills block pointing at the three docs.

  The four missing triage labels (needs-triage, needs-info, ready-for-agent, ready-for-human) were created on the GitHub repo at the same time. (user: [email protected], size: 2700) [annotate] [blame] [check-ins using]

# Domain Docs

How the engineering skills should consume this repo's domain documentation when exploring the codebase.

## Layout

Single-context repo. ADRs (architectural decision records) live in `docs/architecture/` rather than `docs/adr/`:

```
/
├── CLAUDE.md                      ← project instructions
├── MEMORY.md                      ← cross-session project memory
├── docs/
│   ├── architecture/              ← condensed ADRs (read these first)
│   │   ├── core-library.md
│   │   ├── sync-protocol.md
│   │   ├── agent-deployment.md
│   │   ├── checkout-merge.md
│   │   ├── repo-operations.md
│   │   ├── testing-strategy.md
│   │   ├── notify-messaging.md
│   │   └── wasm-targets.md
│   └── superpowers/specs/         ← design specs for in-flight features
└── src/
```

There is no `CONTEXT.md` glossary yet. The closest equivalents are `CLAUDE.md` (architecture overview, conventions) and `MEMORY.md` (decisions, in-flight projects, user preferences). When a skill asks for `CONTEXT.md`, fall back to those.

## Before exploring, read these

- **`CLAUDE.md`** at the repo root — architecture, conventions, build/test commands.
- **`MEMORY.md`** at the repo root — recent decisions and project state.
- **`docs/architecture/*.md`** — read the ADR(s) covering the area you're about to work in.
- **`docs/superpowers/specs/`** — design specs for in-flight features.

If a relevant ADR doesn't exist, **proceed silently**. Don't flag its absence; don't suggest creating one upfront.

## Use the project's vocabulary

When naming domain concepts (in issue titles, refactor proposals, hypotheses, test names), use the terms defined in `CLAUDE.md` and the ADRs. Don't drift to synonyms.

Examples of canonical terms:
- "leaf agent" not "node" or "client daemon"
- "bridge" not "gateway" or "proxy" (specifically: NATS↔HTTP/xfer translator)
- "xfer cards" not "sync messages"
- "libfossil" — the external Go module (`github.com/danmestas/libfossil`)
- "notify" — the bidirectional messaging subsystem, distinct from "sync"
- "DST" — deterministic simulation testing (in `dst/`)
- "BUGGIFY" — the FoundationDB-style fault-injection pattern

If the concept you need isn't established yet, that's a signal — either you're inventing language the project doesn't use (reconsider) or there's a real gap (flag it).

## Flag ADR conflicts

If your output contradicts an existing ADR in `docs/architecture/`, surface it explicitly rather than silently overriding:

> _Contradicts `docs/architecture/sync-protocol.md` — but worth reopening because…_