@reddb-io/red-skills-dev 2.75.2

package/skills/engineering/red-setup/REFERENCE.md

@@ -0,0 +1,35 @@
+# Setup RedSkills Reference
+
+# Setup RedSkills
+
+**Scaffold the per-repo configuration that the engineering skills assume — this skill is the only thing authorized to create `.red/`.** NEVER create `.red/` outside this skill — plugins stay fully inert in any directory whose `.red/config.yaml` is missing or lacks an explicit `plugins.<name>.enabled: true`.
+
+Scaffold includes:
+
+- **Plugin activation** — the per-directory gate (ADR 0067): which RedSkills plugins (`dev`, `memory`, `brain`) are allowed to run here.
+- **Issue tracker** — GitHub Issues (the only supported option, reddb.io policy)
+- **Triage labels** — the strings used for the canonical triage roles and label families
+- **Domain docs** — where `.red/CONTEXT.md` and ADRs live, and the consumer rules for reading them
+- **Workflows** — GitHub Actions shipped by RedSkills (installed under the `rs-*` prefix), e.g. auto-label fresh issues with `needs-triage` so nothing slips past `/triage` and `/afk`
+- **Token efficiency** — provision the repo-owned `rsp` opt-in (`rsp.enabled: true`) so supported noisy commands can use wrapper summaries, reversible elision handles, and hook rewrites without a third-party proxy
+- **Runtime launcher** — optionally install a host-level `red-skills-dev` shim so Claude Code, Codex, and opencode can invoke the same dev runtime without relying on CLI-specific plugin-root env vars
+- **Required host binaries** — install pinned `tq` (`TQ_VERSION=v0.3.0`) through the toon repo installer and record `host_binaries.tq.version` so `/red-doctor` can enforce the no-jq-fallback TOON/TOONL contract
+- **Command guards** — configure the repo-owned `.red/config.yaml` policy that the globally-installed Claude Code, Codex, and opencode hook proxies enforce
+- **Development workflow** — teach agents the `.red/tmp` worktree rules, preserve the primary checkout for the human, and route one-off concrete work through `/go` (ADR 0081)
+
+This is a prompt-driven skill, not a deterministic script. Explore, present what you found, confirm with the user, then write.
+
+## Explore Checklist
+
+### Explore
+
+Look at the current repo to understand its starting state. Read whatever exists; don't assume:
+
+- `git remote -v` and `.git/config` — is this a GitHub repo? Which one?
+- `AGENTS.md` and `CLAUDE.md` at the repo root — does either exist? Is there already an `## Agent skills` section in either?
+- `.red/CONTEXT.md` and `.red/CONTEXT-MAP.md` at the repo root
+- `.red/adr/` — the single root ADR sequence (there are no nested `.red/` subtrees)
+- `.red/agents/` — does this skill's prior output already exist?
+- `.red/config.yaml` — does it exist? Which plugins are already enabled (`plugins.<name>.enabled: true`)? Is the canonical `plugins.dev.lock.primary-branch` flag already set? Is `command_guard` already configured, and under which scopes (`global`, `main`, `worktree`, or legacy `deny`)?
+- `tq --version` and `.red/config.yaml` `host_binaries.tq.version` — is the required host binary present and pinned to `0.3.0`?
+- `AGENTS.md` and `CLAUDE.md` — does either already have a `## Development workflow` section?

package/skills/engineering/red-setup/SKILL.md

@@ -0,0 +1,58 @@
+---
+name: red-setup
+description: >-
+  The one authorized creator of a repo's `.red/` directory and the only way to
+  enable RedSkills plugins (dev, memory, brain) in a project (ADR 0067).
+  RedSkills hooks are installed globally on every agent but stay fully inert in
+  any directory without a `.red/config.yaml` whose
+  `plugins.<name>.enabled: true` opts that plugin in. This skill prompts which
+  plugins to enable, creates `.red/`, writes the activation flags, and sets up
+  `## Agent skills`/`## Development workflow` blocks in AGENTS.md/CLAUDE.md plus
+  `.red/agents/`. Run to turn RedSkills on in a repo, to enable/disable a
+  plugin, before first use of `to-tickets`, `to-spec`, `triage`, `diagnose`,
+  `tdd`, `improve-codebase-architecture`, `zoom-out`, or `/go`, or if those
+  skills appear to be missing context.
+disable-model-invocation: true
+---
+
+# Setup RedSkills
+
+**Scaffold the per-repo configuration that the engineering skills assume — this skill is the only thing authorized to create `.red/`.** NEVER create `.red/` outside this skill — plugins stay fully inert in any directory whose `.red/config.yaml` is missing or lacks an explicit `plugins.<name>.enabled: true`.
+
+This is a prompt-driven skill, not a deterministic script. Explore, present what you found, confirm with the user, then write.
+
+<what-to-do>
+
+## Hot Path
+
+1. **Explore first.** Inspect the repo state listed in [REFERENCE.md](./REFERENCE.md#explore-checklist); do not assume prior RedSkills setup is absent or current.
+2. **Ask in sequence.** Walk the user through one setup section at a time. Keep the plugin-activation gate first, then continue through issue tracker, triage labels, domain docs, workflows, token efficiency, runtime launcher, required host binaries, statusline, config template, command guards, development workflow, and hook scripts. Use the exact section copy and choices in [INTERVIEW.md](./INTERVIEW.md).
+3. **Confirm before writing.** Show the draft agent-skills block, generated agent docs, development-workflow changes, and any accepted command-guard policy before editing. See [WRITE-CONTRACT.md](./WRITE-CONTRACT.md#confirm-and-edit).
+4. **Write under the no-clobber contract.** Never overwrite, rewrite, or reorder existing user-owned content except for the explicit surgical merges named in [WRITE-CONTRACT.md](./WRITE-CONTRACT.md#write). Use the existing-file selection rules, seed docs, workflow copy rules, plugin-activation merge, development-workflow injector, statusline wiring, and hook-script registration exactly as documented there.
+5. **Sweep existing issues only after setup.** If open issues exist, group label backfill candidates and ask for one batch approval before editing labels. See [ISSUE-SWEEP.md](./ISSUE-SWEEP.md).
+6. **Finish with the setup recap.** Tell the user which plugins are enabled here, remind them that other directories stay inert until setup runs there too, point memory/brain users at their next init step, and route one-off concrete work through `/go`, backlog work through `/afk`, and parked issues through `/retake`.
+
+## Hard Rules
+
+- **Only this skill may create `.red/`.** Creating `.red/` is authorized only by the plugin-activation decision; if the user enables no plugins, write nothing.
+- **Global hooks are inert by default.** A plugin block alone is not enough: each enabled plugin must have `plugins.<name>.enabled: true` in `.red/config.yaml` (ADR 0067).
+- **GitHub Issues only.** In reddb.io repos there is no local fallback and no supported alternate issue tracker. Stop if the repo has no GitHub remote.
+- **No clobbering.** Existing files are project state. Skip existing targets unless the referenced write contract explicitly names a surgical exception.
+- **Do not add generated setup files for the user.** In particular, do not `git add` `.red/config.yaml`, `.red/.gitignore`, or hook files written by this setup.
+- **Workflow install is opt-in by lane.** Install only the workflows the user picked; standalone copy-installables keep their `red-*` filename, while reusable callers use `rs-*`.
+- **Command guards are offer-only.** The built-in dev worktree invariant comes from `plugins.dev.enabled: true`; do not write example `command_guard` rules unless the user explicitly accepts them.
+- **ask-red maintenance rule.** Skill add, rename, removal, or flow changes require re-checking `../ask-red/SKILL.md` and updating its Coverage Inventory/routes. A progressive-disclosure-only extraction of this skill is not such a change; no router update is expected after re-checking.
+
+</what-to-do>
+
+<supporting-info>
+
+## Reference Map
+
+- [REFERENCE.md](./REFERENCE.md) — setup scope, scaffold list, and exploration checklist.
+- [INTERVIEW.md](./INTERVIEW.md) — the full section-by-section user interview, including plugin activation, workflows, token efficiency, runtime launcher, statusline, config template, command guards, development workflow, and hook-script offers.
+- [WRITE-CONTRACT.md](./WRITE-CONTRACT.md) — confirmation draft requirements, no-clobber rules, file-selection rules, seed-doc writes, workflow installation, config merges, statusline wiring, hook writes, and final recap text.
+- [ISSUE-SWEEP.md](./ISSUE-SWEEP.md) — open-issue label backfill mechanics.
+- Existing seed/reference files: [issue-tracker-github.md](./issue-tracker-github.md), [triage-labels.md](./triage-labels.md), [domain.md](./domain.md), [config-template.yaml](./config-template.yaml), [WORKFLOWS.md](./WORKFLOWS.md), and [scripts/install-runtime-shim.sh](./scripts/install-runtime-shim.sh).
+
+</supporting-info>

package/skills/engineering/red-setup/WORKFLOWS.md

@@ -0,0 +1,74 @@
+# RedSkills GitHub Actions workflows
+
+## Naming convention — three prefixes by role
+
+RedSkills workflows carry one of three filename prefixes, chosen by the file's
+**role**:
+
+- **`reusable-*` — reusable workflow (called by ref).** A `workflow_call`
+  workflow that lives in `reddb-io/red-skills` and adopters *invoke by reference*
+  (e.g. `uses: reddb-io/red-skills/.github/workflows/reusable-afk-attempt.yml@v1`).
+  It is **referenced, never copied** — its filename never changes.
+- **`rs-*` — caller of a reusable (an *instantiation*).** A thin workflow whose
+  job is to `uses:` a `reusable-*` with concrete triggers + inputs. This is what
+  an adopter installs to wire up a reusable lane — **one `rs-*` per reusable they
+  adopt** (today just `rs-afk-attempt.yml`; more as we extract more reusables).
+  `rs-` reads as "red-skills caller" — the namespace marker for a
+  red-skills-provided caller in a foreign repo.
+- **`red-*` — a standalone workflow authored by red-skills** (no `workflow_call`,
+  does not `uses:` a reusable). Most run only in `reddb-io/red-skills` (release,
+  upstream-watch, workspace CI). A few are *also* offered as verbatim
+  copy-installables (e.g. `red-issues-needs-triage.yml`) — those keep their
+  `red-*` name when copied into an adopter (filename unchanged, body verbatim).
+
+Classification is by **role**, decidable from a file's content: has
+`workflow_call:` → `reusable-*`; `uses:` a `reusable-*` → `rs-*`; otherwise →
+`red-*`. (`/red-doctor` audits this — see its naming-convention check.)
+
+Install mapping (body copied verbatim, including any
+`uses: …/reusable-afk-attempt.yml@v1` ref):
+
+| Role / source | Installed into adopter as |
+|---|---|
+| `reusable-afk-attempt.yml` (reusable — called by ref) | not copied; the **caller** is installed as `rs-afk-attempt.yml` |
+| `red-issues-needs-triage.yml` (standalone `red-*` copy-installable) | `red-issues-needs-triage.yml` (verbatim — name unchanged) |
+
+So `red-skills` itself, as an adopter of its own lane, carries a
+`rs-afk-attempt.yml` caller next to the `reusable-afk-attempt.yml`
+reusable.
+
+## Adopter-installable (offered by `/red-setup`)
+
+Section D is a **menu** — the user picks which workflows + configs. A reusable's
+**caller** installs as `rs-*`; a standalone copy-installable keeps its `red-*`
+name.
+
+| Source | Installed as | Default | Trigger | What it does |
+|---|---|---|---|---|
+| `red-issues-needs-triage.yml` | `red-issues-needs-triage.yml` (verbatim) | **install (yes)** | `issues: opened`/`reopened` | Auto-applies `needs-triage` to any fresh label-less issue, so reports never slip past `/triage` and never sit invisible to `/afk` (which only drains `ready-for-agent`). |
+| `reusable-afk-attempt.yml` (reusable, called by ref) | `rs-afk-attempt.yml` (the caller) | **opt-in (no)** | `issues: labeled`/`opened` (on `ready-for-agent`), `workflow_dispatch`, `workflow_call` | The **AFK Actions lane** — runs one `/afk` attempt per issue headless from Actions and opens a PR (no fleet, no admin-merge; human merges). Needs an OpenCode auth secret + a trust-gate allowlist. Full guide: [`../afk/actions-lane.md`](../afk/actions-lane.md). |
+
+The AFK lane has two shapes (both in `../afk/examples/`): the **turnkey caller**
+(`rs-afk-attempt.yml`, what `/red-setup` installs) and the
+**composable action** (`red-afk-attempt-action.yml`, for your own
+triggers/gate). It depends only on GitHub-official actions plus reddb-io's own
+composite action.
+
+## red-skills' own CI (`red-*`, NOT installed into adopter repos)
+
+These run in `reddb-io/red-skills` only. Listed so the catalogue is complete.
+
+| Workflow | Trigger | What it does |
+|---|---|---|
+| `red-release.yml` | push to `main` | Auto-release: conventional-commit version bump, build the per-plugin bundles, publish a GitHub Release with the assets. Defers while a `running` issue (an active fleet) exists. |
+| `red-memory-drift-guard.yml` | `pull_request` | Fails a PR that changes a watched memory surface (`.red/adr/**`, the glossary) without a `Memory-Ingested:`/`Memory-NoIngest:` audit marker. |
+| `red-memory-bench.yml` | `pull_request`, push to `main` | Memory deterministic-core regression gate. |
+| `red-memory-wiki-extract.yml` | PR merge | Extracts LLM-Wiki pages from the merged PR. |
+| `red-upstream-watch.yml` | schedule | Opens a tracking issue when `mattpocock/skills` advances past the recorded `.upstream` SHA. |
+
+## Conventions
+
+- **`reusable-*`** — reusable (`workflow_call`) workflows, referenced by `uses:`, never copied into an adopter.
+- **`rs-*`** — a caller that `uses:` a `reusable-*`. What an adopter installs to wire up a reusable lane (one `rs-*` per reusable). Body copied verbatim, including the `uses: …/reusable-afk-attempt.yml@v1` ref.
+- **`red-*`** — a standalone workflow authored by red-skills (no `workflow_call`, no `uses:` a reusable). Internal CI plus verbatim copy-installables (e.g. needs-triage) that keep the `red-*` name in the adopter.
+- red-skills self-hosts its own lane, so it carries a `rs-afk-attempt.yml` caller — the same `rs-*` an adopter installs.

package/skills/engineering/red-setup/WRITE-CONTRACT.md

@@ -0,0 +1,151 @@
+# Setup RedSkills Write Contract
+
+## Confirm and edit
+
+Show the user a draft of:
+
+- The `## Agent skills` block to add to whichever of `CLAUDE.md` / `AGENTS.md` is being edited (see step 4 for selection rules)
+- The contents of `.red/agents/issue-tracker.md`, `.red/agents/triage-labels.md`, `.red/agents/domain.md`
+- The Section H development-workflow changes: `plugins.dev.lock.primary-branch: true` plus the canonical `## Development workflow` block for `AGENTS.md` and `CLAUDE.md`
+- The Section E2 required-host-binary record: `host_binaries.tq.version: 0.3.0`
+- The Section G1 command-guard changes if the user accepted them: the exact `command_guard` block or scoped entries that will be written to `.red/config.yaml`
+
+Let them edit before writing.
+
+## Write
+
+**No-clobber rule (governs every write below).** Never overwrite, rewrite, or reorder content in a file this skill did not just create: if a target already exists, skip it, log a one-line notice, and move on — no second ask, and never `git add` on the user's behalf. Two surgical merges are the *only* exceptions, flagged at the steps that own them: updating `plugins.<name>.enabled` flags in an existing `.red/config.yaml`, and appending a missing `tmp/`, `state/`, or `researches/` line to an existing `.red/.gitignore`. (Copied workflow YAML is the one "ask, don't silently skip" case — diff and ask first.)
+
+**Config-key spelling rule.** Write `.red/config.yaml` keys only in the spellings that appear in [config-template.yaml](./config-template.yaml). Folded accessor names such as root-level `dev.*` or bare `afk.*` are display/reader vocabulary only; never write them as YAML keys because folding readers may honor them while exact-key readers ignore them, creating a split-brain config.
+
+**Pick the file to edit:**
+
+- If `CLAUDE.md` exists, edit it.
+- Else if `AGENTS.md` exists, edit it.
+- If neither exists, ask the user which one to create — don't pick for them.
+
+Never create `AGENTS.md` when `CLAUDE.md` already exists (or vice versa) — always edit the one that's already there.
+
+If an `## Agent skills` block already exists in the chosen file, update its contents in-place rather than appending a duplicate. Don't overwrite user edits to the surrounding sections.
+
+The block:
+
+```markdown
+## Agent skills
+
+### Issue tracker
+
+[one-line summary of where issues are tracked]. See `.red/agents/issue-tracker.md`.
+
+### Triage labels
+
+[one-line summary of the label vocabulary]. See `.red/agents/triage-labels.md`.
+
+### Domain docs
+
+[one-line summary of layout — "single-context" or "multi-context"]. See `.red/agents/domain.md`.
+```
+
+Then write the three docs files using the seed templates in this skill folder as a starting point:
+
+- [issue-tracker-github.md](./issue-tracker-github.md) — GitHub issue tracker (the only option)
+- [triage-labels.md](./triage-labels.md) — label mapping
+- [domain.md](./domain.md) — domain doc consumer rules + layout
+
+If the user accepted Section D, copy each standalone `red-*.yml` template the user picked from this skill folder's `workflows/` into `.github/workflows/` of the consumer repo **verbatim — keep the `red-*` filename, do not rename** (e.g. `workflows/red-issues-needs-triage.yml` → `.github/workflows/red-issues-needs-triage.yml`): standalone copy-installables keep their `red-*` prefix, only reusable **callers** get renamed to `rs-*` (AFK lane below). Don't overwrite an existing file — diff and ask first. Then ensure both `needs-triage` and `runner-error` labels exist via `gh label create` if missing (`gh label create runner-error --color B60205 --description "AFK supervisor circuit-tripped; runner was misconfigured"`).
+
+**If the user opted into the autonomous AFK execution lane** (Section D, default no), additionally:
+
+1. Copy [`../afk/examples/rs-afk-attempt.yml`](../afk/examples/rs-afk-attempt.yml) to `.github/workflows/rs-afk-attempt.yml` in the consumer repo (installed name is `rs-*`; the `uses:` ref inside still points at the `reusable-afk-attempt.yml` reusable — leave it). Don't overwrite an existing file — diff and ask first.
+2. Edit `allowlist_authors` and `allowlist_label_actors` to the maintainer login(s) the user named (the trust gate; keep it short on public repos).
+3. Apply the trigger choice from Section D: keep `workflow_dispatch` for a manual caller, the `issues: labeled` auto-trigger, or both. (The reusable's own `if:` gate auto-triggers on `ready-for-agent` even when only the dispatch caller exists.)
+4. Set the `model:` input to the slug the user picked (e.g. `minimax/MiniMax-M3`), or leave it empty to fall back to the repo's `.red/config.yaml` model config.
+5. Print the secret-setup guidance — the lane needs one OpenCode auth key; do **not** set it for them (secrets are the user's to provision): `gh secret set MINIMAX_API_KEY --repo OWNER/REPO` (or `OPENAI_API_KEY` / `OPENROUTER_API_KEY`; first set wins). **Public-repo gotcha:** if the repo is public, an *org* secret resolves empty unless its "Repository access" includes this repo — prefer a repo secret, or widen the org secret's access. Point them at [`../afk/actions-lane.md`](../afk/actions-lane.md#configuring-secrets-per-provider) for the per-provider table + auth precedence + the `model` slug.
+6. Note that the lane will not fire until both a secret is set (and reaching the repo) and an issue carries `ready-for-agent` from an allowlisted actor.
+
+Scaffold `.red/config.yaml` (Section G), writing the Section A0 activation flags
+and the `rsp` opt-in block:
+
+1. If `.red/config.yaml` already exists at the repo root, apply the **plugin-flags exception** to the no-clobber rule: surgically add/update the `plugins.<name>.enabled` flags to match the Section A0 choice (add a `plugins:` block or `plugins.<name>:` child if missing; set `enabled: true` for enabled plugins; remove the flag or set `false` for ones the user turned off), and surgically add/update the top-level `rsp:` block to `enabled: true`, `ttlDays: 7`, `ephemeralTtlHours: 6`, and `byteBudget: 67108864`; touch nothing else, and log `.red/config.yaml present - merged plugin activation flags and rsp defaults, left the rest as-is`.
+2. Otherwise, ensure `.red/` exists (this section is the authorized creator) and copy [config-template.yaml](./config-template.yaml) to `.red/config.yaml`, then surgically edit only the template-provided values that Section A0 selected. Do not compose the `plugins:` block from memory: start from the shipped template, preserve its key nesting, and only uncomment/flip the relevant `plugins.<name>.enabled` flags (the template ships with `plugins.dev.enabled: true` as the baseline and `memory`/`brain` commented — uncomment/flip per the choice). The `rsp` block ships enabled with default retention because the hook remains strictly per-repo opt-in: absent block or any value other than `enabled: true` is inert. The rest of the template is a fully-commented snapshot of every v1 knob the AFK config loader (`apps/dev/src/core/config.ts`) reads, so it stays a no-op until the user uncomments a line — including the commented `command_guard` and `afk.backpressure` blocks.
+3. **Provision the rsp elision store.** Run `rsp setup` from the repo root. This is the supported provisioning command: it writes the `rsp:` config block and points rsp at the shared repo-local RedDB store `.red/state/red-skills.rdb` (per ADR 0098). Elision records use the `rsp_elisions_v1` KV collection with storage-class accounting and a physical byte cap; legacy JSON files are only a fallback/migration path, not the normal setup target. `rsp setup` performs no memory-graph migration and does not create, move, or repoint `.red/memory/graph.rdb` or `plugins.memory.storePath`; memory and brain keep using RedDB through their own provisioning path.
+4. **Self-ignore `.red/`'s local state.** Whenever `.red/` exists (fresh scaffold or pre-existing), make the directory protect itself so `.red/tmp`, `.red/state`, and `.red/researches` never get committed regardless of the repo-root `.gitignore`. Write `.red/.gitignore` if it is **missing** with exactly:
+
+   ```gitignore
+   # Generated by /red-setup — local AFK/runtime state, never committed.
+   tmp/
+   state/
+   researches/
+   ```
+
+   If `.red/.gitignore` already **exists**, apply the **gitignore-append exception**: append whichever of the three patterns (`tmp/`, `state/`, `researches/`) is missing, and never rewrite or reorder existing lines. Keep tracked `.red` content (`config.yaml`, `contexts/`, `adr/`, `agents/`, `contracts/`, `hooks/`) committable — only local state and generated research reports are ignored. Do **not** `git add` `.red/.gitignore` (step 5 — the user controls when `.red/` lands in git).
+5. **Backpressure pre-fill offer (only on a fresh scaffold).** Read the repo-root (or primary package) `package.json`; if it declares `test` and/or `lint` scripts, surface them and ask whether to pre-fill `afk.backpressure` with the matching `npm run <script>` (or `pnpm run <script>`) lines, uncommented. On explicit yes, replace the commented `backpressure:` placeholder with the confirmed list; otherwise leave it commented. Skip silently when no such scripts exist. This step never runs when `.red/config.yaml` already existed (step 1 wins).
+6. **Command guard write (only when Section G1 was explicitly accepted).** Update `.red/config.yaml` with the confirmed `command_guard` policy. If the file is fresh, replace the commented placeholder with the confirmed block. If the file already existed, merge only the accepted `command_guard.global`, `command_guard.main`, and/or `command_guard.worktree` entries, appending without duplicates and preserving unrelated content. If a legacy `command_guard.deny` block exists, leave it intact unless the user explicitly approved migrating it to `global`.
+7. **Mandatory post-write config check.** Load the just-written `.red/config.yaml` through the real dev config loader before setup can finish. From a source checkout, run `pnpm --filter @reddb-io/dev dev red-doctor` from the target repo root; from an installed plugin, run `red-skills-dev red-doctor`. If the loader prints an off-contract-spelling warning such as root-level `dev.*` or bare `afk.*`, treat the check as red: fix `.red/config.yaml` back to the template spelling, re-run the same command, and only continue when the warning is gone.
+8. Do **not** `git add` or commit `.red/config.yaml` or `.red/.gitignore` — the user controls when they land in git.
+
+Install and record required host binaries (Section E2):
+
+1. Run the pinned toon installer exactly as documented:
+
+   ```bash
+   TQ_VERSION=v0.3.0 curl -fsSL https://raw.githubusercontent.com/reddb-io/toon/v0.3.0/install.sh | sh
+   ```
+
+2. Verify `tq --version` reports `0.3.0`. If it does not, stop and report the mismatch; do not offer a jq fallback.
+3. Ensure `.red/config.yaml` records the pin:
+
+   ```yaml
+   host_binaries:
+     tq:
+       version: 0.3.0
+   ```
+
+   If `.red/config.yaml` already exists, merge only that `host_binaries.tq.version` entry and preserve unrelated content.
+
+If the user accepted Section H, activate the development workflow:
+
+1. Invoke the shared injector rather than hand-editing the rules block. From a source checkout, run `pnpm --filter @reddb-io/dev dev inject-development-workflow --root <repo-root>`. From an installed plugin, run the bundled AFK entrypoint with `inject-development-workflow --root <repo-root>` (for example, `node ../afk/bin/afk.mjs inject-development-workflow --root <repo-root>` from this skill folder). The command writes both `AGENTS.md` and `CLAUDE.md`, creates `.red/config.yaml` if still missing, and sets `plugins.dev.lock.primary-branch: true`.
+2. If the command is unavailable, make the same changes manually: add or update the canonical `plugins:` → `dev:` → `lock:` block in `.red/config.yaml` so `primary-branch` is `true`, then upsert the canonical `## Development workflow` block in both `AGENTS.md` and `CLAUDE.md`. Never append a duplicate block; update the existing section in place. Leave any legacy top-level `dev.lock.*` keys untouched; `/red-doctor --fix` owns that migration.
+3. In the recap, explicitly point the user at `/go` for one-off concrete work, and at a normal PR for a hand-worked worktree branch that is already committed and pushed.
+
+If the user accepted Section F, wire the statusline:
+
+1. Check the opt-out: if `.red/config.yaml` exists and contains an `afk:` block with `statusline: false`, log `afk.statusline: false in .red/config.yaml — skipping statusline wiring` and skip the rest of this step.
+2. Check for an existing `statusLine` key in `.claude/settings.json`. If one is present, log `statusLine already configured in .claude/settings.json — leaving as-is` and skip the rest of this step.
+3. Otherwise, ensure `.claude/` exists and write/merge the `statusLine` block above into `.claude/settings.json`. Use `jq` for the merge when the file already has unrelated keys; create a fresh file containing only `statusLine` when missing.
+
+If the user confirmed any hook scripts from Section I:
+
+1. For each confirmed suggestion, ensure `.red/hooks/<point>/` exists (create the directory; `.red/` is already authorized by Section A0 — subdirectories under it are permitted).
+2. Write `.red/hooks/<point>/<name>` with the script content. Per the no-clobber rule, if the file already exists, skip it silently — log `.red/hooks/<point>/<name> already exists — not overwriting` and move on.
+3. Update `.red/config.yaml`: add the script path under the `afk.hooks.<point>:` list. Use the relative-to-root form `bash .red/hooks/<point>/<name>` as the command string. If the key already has entries, append without duplicating; if missing, add it. The `afk:` → `hooks:` → `<point>:` nesting matches the config-template structure.
+4. Do **not** `git add` any of the written files or the updated config.
+
+Script content for each signal type (all open with `#!/usr/bin/env bash` + `set -euo pipefail`):
+
+- `red-run-tests.sh` (`pre_merge`): `<pm> run test`
+- `red-typecheck.sh` (`pre_merge`): `<pm> run typecheck` (or `type-check` per the detected key)
+- `red-lint.sh` (`pre_merge`): `<pm> run lint`
+- `red-build.sh` (`pre_merge`): `<pm> run build`
+- `red-e2e.sh` (`post_merge`): `<pm> run e2e` (or `test:e2e` per the detected key)
+- `red-make-<target>.sh` (`pre_merge`): `make <target>`
+- `red-cargo-test.sh` (`pre_merge`): `cargo test`
+- `red-gradle-check.sh` (`pre_merge`): `./gradlew check`
+- `red-lint-staged.sh` (`pre_merge`): `npx lint-staged`
+- `red-pre-commit.sh` (`pre_merge`): `pre-commit run --all-files`
+- `red-slack-notify.sh` (`post_merge`):
+
+  ```bash
+  #!/usr/bin/env bash
+  set -euo pipefail
+  # Post-merge Slack notification. Set SLACK_WEBHOOK_URL before running /afk.
+  [ -z "${SLACK_WEBHOOK_URL:-}" ] && exit 0
+  curl -sf -X POST "$SLACK_WEBHOOK_URL" \
+    -H "Content-Type: application/json" \
+    -d "{\"text\":\"AFK merged issue #${RED_AFK_ISSUE:-?} on ${RED_AFK_REPO:-repo}\"}"
+  ```
+
+## Done
+
+Tell the user the setup is complete, which plugins are now enabled here (and that all other directories stay inert until they run this skill there too), and which engineering skills will now read from these files. If they enabled **memory** or **brain**, point them at the next step — `/memory:init` to pick a storage mode, or the brain setup — since enabling only authorizes the plugin to run; its own init configures it. Mention they can edit `.red/agents/*.md` directly later, and that one-off concrete work should be dispatched with `/go` (backlog via `/afk`, parked issues via `/retake`). Re-run this skill to enable or disable a plugin, switch issue trackers, or restart from scratch.

package/skills/engineering/red-setup/config-template.yaml

@@ -0,0 +1,174 @@
+# .red/config.yaml — per-project plugin settings (consumed by /afk and friends)
+# Uncomment any line to override the default.
+
+# Plugin activation gate (ADR 0067). RedSkills hooks are installed globally on
+# every agent but stay fully inert in any directory whose `.red/config.yaml`
+# does NOT set `plugins.<name>.enabled: true`. /red-setup writes this
+# block; it is the only authorized creator of `.red/`. Strict opt-in: a block
+# without `enabled: true` is OFF.
+plugins:
+  dev:
+    enabled: true                 # the engineering stack (/afk, /triage, /retake, …)
+  #   trunk: main                 # canonical location: plugins.dev.trunk.
+  #                               # The Trunk (ADR 0083): the focal branch agent work
+  #                               # bases on and lands to when no lock/pin names one
+  #                               # (precedence lock > pin > trunk). Always consumed
+  #                               # as fresh-fetched origin/<trunk>, never the local
+  #                               # branch. Set e.g. develop or workspace/<user>.
+  #   lock:
+  #     primary-branch: true      # branch-lock compatibility/base-pinning flag
+  #                               # (Section H of /red-setup sets this)
+  #     branch: my-branch         # static base lock: AFK bases/merges here (ADR 0031);
+  #                               # the runtime /branch-lock overrides it per session
+  #   triage:
+  #     external_pr_surface:
+  #       enabled: false          # default OFF. When true, /triage may list/read
+  #                               # external PRs as request data. It still treats
+  #                               # PR bodies/diffs as untrusted and never checks
+  #                               # out, builds, tests, or executes PR code.
+  # memory:
+  #   enabled: true               # then run /memory:init to pick a storage mode
+  # brain:
+  #   enabled: true               # the agentic command-center context
+
+# rsp hook activation and retention (ADR 0095 amended by ADR 0098). /red-setup
+# provisions `.red/state/red-skills.rdb`; the hook remains inert unless this
+# explicit flag is true.
+rsp:
+  enabled: true
+  ttlDays: 7
+  ephemeralTtlHours: 6
+  byteBudget: 67108864            # 64 MiB
+
+# Required host binaries (ADR 0097). /red-setup installs these through their
+# checksum-verified upstream installers and records the exact pin here so
+# /red-doctor can red-flag absence or version drift. tq is required for
+# TOON/TOONL inspection; there is no jq fallback lane.
+host_binaries:
+  tq:
+    version: 0.3.0
+
+# Built-in dev shell guard: once plugins.dev.enabled is true, agent-created
+# worktrees must live under a registered .red/tmp/ lane, and branch-changing
+# commands in the primary checkout are blocked. Create task branches with:
+#   git worktree add .red/tmp/worktrees/manual/<slug> -b <branch> origin/main
+#
+# Command guard policy. The installed Claude Code, Codex, and opencode hooks are
+# thin proxies: they read this repo-owned policy at runtime and stay inert unless
+# plugins.dev.enabled is true. These rules are additional to the built-in
+# registered .red/tmp worktree boundary above. Uncomment only rules this repo actually wants.
+# command_guard:
+#   global:                       # applies in main sessions and runtime worktrees
+#     - "rm -Rf /*"
+#     - "git stash"
+#   main:                         # primary interactive session scope, not branch name
+#     - "git rebase"
+#     - "git checkout -b"
+#   worktree:                     # /afk and /go worktrees under .red/tmp/
+#     - "git clean"
+
+# afk:
+#   default_runner: claude        # fallback runner when no explicit signal
+#   worktree_launches_pull_request: true   # landing MODE, decoupled from the lock
+#                                 # (ADR 0030 amended, #842). true (default) → land
+#                                 # via an admin-merged PR into the resolved base;
+#                                 # false → direct merge into that base (offline,
+#                                 # no PR). The branch-lock only resolves the target
+#                                 # base (lock > pin > main, ADR 0031), NOT the mode.
+#                                 # How a PR merges stays governed by `afk.merge.*`.
+#                                 # NOTE: default true means a locked repo now gets
+#                                 # an admin-PR to the lock branch; set false to keep
+#                                 # the old offline/direct-promotion flow.
+#   models:                       # per-runner AFK tier table (ADR 0049)
+#     claude:
+#       validate:
+#         model: claude-haiku-4-5
+#         effort: low
+#       simple:
+#         model: claude-sonnet-4-6
+#         effort: high
+#       complex:
+#         model: claude-opus-4-8
+#         effort: medium
+#       think:                    # default until the AFK classifier lands
+#         model: claude-opus-4-8
+#         effort: high
+#     codex:
+#       validate:
+#         model: gpt-5.5
+#         effort: low
+#       simple:
+#         model: gpt-5.5
+#         effort: high
+#       complex:
+#         model: gpt-5.5
+#         effort: medium
+#       think:
+#         model: gpt-5.5
+#         effort: high
+#     opencode:                   # ADR 0059 — endpoint-agnostic; slug = <provider>/<model>
+#       base:                     # auto-populates EVERY tier of this runner. Set the model
+#         model: minimax/MiniMax-M3   # once to point the whole runner at one provider/model;
+#         effort: medium          # `base.effort` is optional (omit it to keep per-tier defaults).
+#       think:                    # specialize a single tier — overrides `base` for that tier only
+#         model: minimax/MiniMax-M3
+#   fleet:
+#     target: 2                   # default supervisor worker target
+#   release:                      # bundle release channel (ADR 0058)
+#     channel: canary             # `stable` (default = today's version-pinned
+#                                 # release) or `canary` (npm dist-tag pointer to
+#                                 # an already-published stable package version).
+#                                 # The launcher reads this or the
+#                                 # `RED_SKILLS_CHANNEL` env var (env wins); absent
+#                                 # config keeps tracking stable. Canary promotion
+#                                 # moves the npm dist-tag (scripts/afk-promote-channel.sh),
+#                                 # gated on the proof-by-drain telemetry.
+#   backpressure:                 # extra merge gates run on every successful
+#     - npm run test              # iteration (DONE + salvaged no-sentinel), after
+#     - npm run lint              # the built-in feedback gate. Any non-zero exit
+#                                 # blocks the merge and parks to ready-for-human,
+#                                 # exactly like a feedback failure. Optional;
+#                                 # absent/empty = no-op. (#430 / PRD #429)
+#   output_shaping:
+#     terse_steering: false       # default OFF. When true, even-numbered issues
+#                                 # get a phrasing-only terse steering block;
+#                                 # odd-numbered issues are the holdout. The arm
+#                                 # is stamped next to heartbeat output-token
+#                                 # counters and reported by `afk-output-shaping`.
+#   test:
+#     quarantine:                 # config-declared flaky-test quarantine lane (issue #1035).
+#                                 # Each entry excludes a known-flaky test file from the
+#                                 # scoped gate run and emits a visible "quarantined" sidecar
+#                                 # record — exclusions are NEVER silent (repo norm). An entry
+#                                 # without an issue ref fails the gate loudly. /red-doctor warns
+#                                 # when a referenced issue is closed (managed debt, not
+#                                 # permanent forgetting).
+#                                 # Pattern is a repo-relative file path passed to vitest
+#                                 # --exclude (relative to the scope dir at run time).
+#                                 # Named entries e0, e1, e2 … are read in order until the
+#                                 # first gap.
+#       e0:
+#         pattern: apps/dev/tests/supervisor.test.ts
+#         issue: "https://github.com/reddb-io/red-skills/issues/1063"
+#         since: "2026-07-02"
+#         reason: "OOM under AFK fleet=2 concurrent load (exit 137 / SIGKILL)"
+#       e1:
+#         pattern: apps/brain/tests/dashboard.test.ts
+#         issue: "https://github.com/reddb-io/red-skills/issues/1064"
+#         since: "2026-07-02"
+#         reason: "tsx spawn timeout under concurrent AFK load (40 s ceiling)"
+#   hooks:
+#     defaults:
+#       cargo: true               # ship cargo isolation on Rust projects
+#       gradle: true              # ship gradle isolation when GRADLE_USER_HOME_BASE is set
+#   trust-gate:                   # "executable issue" trust gate (#621, ADR 0085)
+#     allowlist: alice,bob        # comma/space-separated GitHub logins. An issue is
+#                                 # executable only when its AUTHOR is in this list AND
+#                                 # `ready-for-agent` was applied by a listed actor
+#                                 # (read from the issue timeline, not the label set).
+#                                 # ABSENT/empty (the default) → PERMISSIVE: the gate
+#                                 # never fires and every ready-for-agent issue is
+#                                 # claimable, exactly as today. Setting it switches the
+#                                 # repo to STRICT mode; a ready-for-agent applied by a
+#                                 # non-listed actor is skipped at claim and may be
+#                                 # stripped by a sweep with an audit comment.

package/skills/engineering/red-setup/domain.md

@@ -0,0 +1,52 @@
+# Domain Docs
+
+How the engineering skills should consume this repo's domain documentation when exploring the codebase.
+
+## Before exploring, read these
+
+- **`.red/CONTEXT.md`** at the repo root, or
+- **`.red/CONTEXT-MAP.md`** at the repo root if it exists — it points at one `.red/contexts/<name>/CONTEXT.md` per context. Read each one relevant to the topic.
+- **`.red/adr/`** — read ADRs that touch the area you're about to work in. ADRs live in this single root sequence, even in multi-context repos.
+
+If any of these files don't exist, **proceed silently**. Don't flag their absence; don't suggest creating them upfront. The producer skill (`/start`) creates them lazily when terms or decisions actually get resolved.
+
+## File structure
+
+Single-context repo (most repos):
+
+```
+/
+├── .red/
+│   ├── CONTEXT.md
+│   └── adr/
+│       ├── 0001-event-sourced-orders.md
+│       └── 0002-postgres-for-write-model.md
+└── src/
+```
+
+Multi-context repo (presence of `.red/CONTEXT-MAP.md` at the root) — everything stays under the single root `.red/`:
+
+```
+/
+├── .red/
+│   ├── CONTEXT-MAP.md                 ← lists the contexts and how they relate
+│   ├── contexts/
+│   │   ├── ordering/CONTEXT.md
+│   │   └── billing/CONTEXT.md
+│   └── adr/                           ← single root ADR sequence (all contexts)
+└── src/
+    ├── ordering/
+    └── billing/
+```
+
+## Use the glossary's vocabulary
+
+When your output names a domain concept (in an issue title, a refactor proposal, a hypothesis, a test name), use the term as defined in `.red/CONTEXT.md`. Don't drift to synonyms the glossary explicitly avoids.
+
+If the concept you need isn't in the glossary yet, that's a signal — either you're inventing language the project doesn't use (reconsider) or there's a real gap (note it for `/start`).
+
+## Flag ADR conflicts
+
+If your output contradicts an existing ADR, surface it explicitly rather than silently overriding:
+
+> _Contradicts ADR-0007 (event-sourced orders) — but worth reopening because…_