reddb-io-red-skills-dev

---

RedSkills is reddb.io's plugin suite for serious code-agent workflows. It started as a reddb.io adaptation of mattpocock/skills: small SKILL.md files that teach agents concrete behaviors. RedSkills keeps that core and adds the pieces teams need when agents are doing real engineering work: issue automation, isolated worktrees, AFK execution, governed Memory, Brain, MCP servers, release bundles, status signals, and guardrails.

Attribution is preserved in NOTICE.

Install

Universal Installer

Recommended for normal installs and upgrades:

curl -fsSL https://raw.githubusercontent.com/reddb-io/red-skills/v2/scripts/install.sh | bash

The installer resolves the latest GitHub Release, stores it under ~/.red-skills/versions/<tag>, updates ~/.red-skills/current, detects which supported CLIs are present (claude, codex, opencode, pi), then installs the right surface for each host:

Host	What the installer does
Claude Code	Registers the RedSkills marketplace and installs dev, memory, and brain.
Codex CLI	Registers the RedSkills marketplace and installs dev, memory, and brain.
OpenCode	Generates and installs OpenCode plugin modules, skills, MCP config, provider config, and TUI attention config.
Pi	Registers one Pi package per plugin via pi install, exposes the same skill buckets through the standard agent skills protocol.

OpenCode installs use the published opencode-host.bundle.min.mjs asset when available, so normal installs need node but do not need a local workspace build. If that asset is unavailable for a pinned older release, the installer falls back to building from source with pnpm.

Useful options:

# inspect without writing
curl -fsSL https://raw.githubusercontent.com/reddb-io/red-skills/v2/scripts/install.sh | bash -s -- --dry-run

# install only one host
curl -fsSL https://raw.githubusercontent.com/reddb-io/red-skills/v2/scripts/install.sh | bash -s -- --only opencode
curl -fsSL https://raw.githubusercontent.com/reddb-io/red-skills/v2/scripts/install.sh | bash -s -- --only pi

# pin a release
curl -fsSL https://raw.githubusercontent.com/reddb-io/red-skills/v2/scripts/install.sh | bash -s -- --version v2.6.0

# force plugin reinstall where the host supports removal
curl -fsSL https://raw.githubusercontent.com/reddb-io/red-skills/v2/scripts/install.sh | bash -s -- --force

# uninstall from every detected host
curl -fsSL https://raw.githubusercontent.com/reddb-io/red-skills/v2/scripts/install.sh | bash -s -- --uninstall

# uninstall and remove the ~/.red-skills release cache
curl -fsSL https://raw.githubusercontent.com/reddb-io/red-skills/v2/scripts/install.sh | bash -s -- --uninstall --purge

After installing, restart any already-open CLI sessions so they reload plugin manifests. Then run /red-setup in a project from Claude Code or OpenCode, or $dev:red-setup in Codex when the client exposes namespace-qualified skills.

Manual: Claude Code

/plugin marketplace add reddb-io/red-skills
/plugin install dev@red-skills
/plugin install memory@red-skills
/plugin install brain@red-skills

Common dev commands become native slash commands:

/red-setup
/triage
/afk --once
/go "one concrete demand"
/dashboard

Memory and Brain skills are plugin skills:

$init
$store Decision: cache TTL is 300 seconds because upstream rate limits.
$recall cache TTL
$capture Remember this project decision...
$think What do we know about the billing migration?

Upgrade or remove:

/plugin marketplace update red-skills
/plugin uninstall brain@red-skills
/plugin uninstall memory@red-skills
/plugin uninstall dev@red-skills
/plugin marketplace remove red-skills

Manual: Codex CLI

codex plugin marketplace add reddb-io/red-skills
codex plugin marketplace upgrade red-skills
codex plugin add dev@red-skills
codex plugin add memory@red-skills
codex plugin add brain@red-skills
codex plugin marketplace remove red-skills

Codex invokes skills with $<skill>. Some clients expose plugin skills with the plugin namespace; use that form when it appears in the skills list:

$dev:red-setup
$dev:triage
$dev:afk --once
$dev:retake #123
$memory:init
$memory:recall cache TTL
$brain:capture Save this project note...

Codex currently supports built-in footer items through tui.status_line, not a command-backed statusline. Use $dev:afk monitor when the client exposes namespace-qualified skills, or $afk monitor when it exposes unqualified skill names.

Codex Manifest Maintenance

Codex manifests are generated artifacts. Do not hand-edit .agents/plugins/marketplace.json or plugins/*/.codex-plugin/plugin.json. Change the Claude-side marketplace/plugin manifests or plugin tree, then run:

pnpm codex:manifests

CI runs pnpm codex:manifests:check and fails when committed Codex manifests drift from the generator output.

Pi Manifest Maintenance

Pi ships two generated artifacts that must stay in sync with the Claude-side plugin tree:

• plugins/<name>/package.json — the local-path install surface (ADR 0075-era shape; consumed by pi install <path>).
• packaging/pi/<name>/package.json plus packaging/pi/<name>/skills/ — the npm publish surface (ADR 0110; consumed by pi install npm:@reddb-io/red-skills-<plugin>).

Both are generated. Do not hand-edit either. Change the Claude-side plugin manifest or the plugin tree, then run:

pnpm pi:manifests        # regenerates plugins/<name>/package.json
pnpm pi:packages:build   # stages packaging/pi/<name>/ from plugins/<name>/

CI runs both pnpm pi:manifests:check and pnpm pi:packages:check and fails when either committed artifact drifts. The release pipeline runs the build step before publishing, so a manual regeneration is only required when working on Pi support itself.

Manual: OpenCode

OpenCode support is generated from the same plugin source tree as Claude Code and Codex. The installer writes skills, plugin modules, MCP config, provider config, and TUI attention config for OpenCode. The universal installer above is preferred for normal user-scoped installs; use the direct script when developing or when installing/removing a checkout in a specific project.

git clone git@github.com:reddb-io/red-skills.git ~/code/red-skills
cd ~/code/red-skills

# user-scoped install into ~/.config/opencode
scripts/install-opencode.sh --global

# user-scoped uninstall from ~/.config/opencode
scripts/install-opencode.sh --uninstall --global

# project-local install into the current repo
scripts/install-opencode.sh

# project-local uninstall from the current repo
scripts/install-opencode.sh --uninstall

# inspect without writing
scripts/install-opencode.sh /path/to/project --dry-run

Then run OpenCode in any configured project:

opencode .

Use /connect inside OpenCode or export one of OPENAI_API_KEY, MINIMAX_API_KEY, or OPENROUTER_API_KEY. Generated config never stores auth secrets. Details live in apps/opencode-host.

Manual: Pi

RedSkills ships one Pi package per published plugin on npm under the @reddb-io scope. The packages are generated from the same Claude-side manifests the other hosts consume, so the same skill buckets (engineering, knowledge, productivity, misc, core) Claude Code and Codex already expose are what Pi discovers.

The natural install is the same one-liner Pi documents for every npm package:

pi install npm:@reddb-io/red-skills-dev
pi install npm:@reddb-io/red-skills-memory
pi install npm:@reddb-io/red-skills-brain
# (optional) maintainer-only — gated by plugins.internal.enabled: true
pi install npm:@reddb-io/red-skills-internal

Updates follow the rest of the release train: pi update --all resolves the latest matching version from the npm registry and the new skills reload on the next session start.

For repo-scoped installs that ship with the project (so teammates pick up the same RedSkills surface on first launch), use the bundled installer:

# user-scoped install into ~/.pi/agent/settings.json (npm: surface)
scripts/install-pi.sh

# project-scoped install into <repo>/.pi/settings.json
scripts/install-pi.sh --project /path/to/your-project

# pin a specific published version (e.g. before a tagged release)
RED_SKILLS_PI_VERSION=2.75.2 scripts/install-pi.sh

# dev path: install from a local checkout (in-repo workflow)
scripts/install-pi.sh --source-dir /path/to/red-skills-checkout

# user-scoped uninstall
scripts/install-pi.sh --uninstall

# dry-run + inspect
scripts/install-pi.sh --project . --dry-run

scripts/install-pi.sh writes ~/.pi/agent/redskills-install-manifest.json (or <project>/.pi/redskills-install-manifest.json for --project) recording each npm: spec it registered, so a subsequent --uninstall cleanly tears down exactly that surface. The --source-dir form records local-path specs in the same manifest under a separate source discriminator.

Known limitations versus the other hosts:

• Pi does not run lifecycle hooks, so the Codex/Claude SessionStart/Stop hooks (the rsp interception bridge, red-fetch, command-guard, branch-lock, statusline wiring) are not active in Pi. Skills that depend on those hooks lose telemetry but stay navigable; AFK runners and navigator MCP servers are unaffected.
• Two plugins (memory and brain) ship a skill with the same name: view. Pi warns on duplicate skill names and keeps the first one registered, so install memory or brain last depending on which view you want as the primary entry point.
• Pi does not advertise the plugin display metadata Codex uses; the npm description field is the only user-visible summary in pi list.
• The internal package is gated by plugins.internal.enabled: true (ADR 0067) the same way the Claude and Codex marketplaces expose it. The npm package is public; the gate is what keeps it inactive in non-maintainer repos.

After installing, restart any open Pi session so the new skills reload. scripts/install-pi.sh --help documents the user/project scope split, the --source-dir dev path, and the --uninstall flow.

No Marketplace

Older agents, local hacking, or Gemini-style skill loading can install from a checkout:

npx skills@latest add reddb-io/red-skills

For local symlinks:

git clone git@github.com:reddb-io/red-skills.git ~/code/red-skills
cd ~/code/red-skills
./scripts/link-skills.sh

Marketplace installs auto-update. npx skills and manual symlinks do not.

Verify Runners

Before a release, or after upgrading Claude Code/Codex, run:

./scripts/doctor-runners.sh

It checks plugin metadata, shell syntax, runner flags used by /afk, Codex marketplace registration in a temporary home, and manual skill-link installs.

---

What Makes It Different

Issue to PR is the product. RedSkills treats GitHub Issues as the work queue, not a side note. /triage, /to-spec, /to-tickets, /afk, /go, /hitl, and /retake all speak the same issue-state vocabulary.

Agents work in disposable worktrees. AFK execution and interactive landing keep the primary checkout under human branch control. Work is prepared, validated, committed, pushed, reviewed, and merged through explicit gates.

Memory is evidence, not vibes. The Memory plugin stores decisions, root causes, validation records, reasoning attempts, supersession, freshness, and readiness signals so future agents can verify old claims before acting.

Brain is for human-facing knowledge. Brain captures project notes, personal facts, sources, questions, bookmarks, typed artifacts, and cited synthesis under .red/brain/*.

One source tree, several hosts. Claude Code, Codex, OpenCode, GitHub Actions, and MCP servers are generated from the same plugin definitions and runtime apps.

---

The Loop

Plan -> Spec -> sliced issues -> ready-for-agent -> isolated worktree
  -> validation -> PR -> review/checks -> merge -> Memory evidence

The issue lifecycle is intentionally boring:

needs-triage -> /triage -> ready-for-agent -> /afk -> PR/merge -> closed
                                |
                                +---- blocked/spec/validation/etc.
                                      -> ready-for-human -> /hitl or /retake

Important states:

State	Meaning
ready-for-agent	The only issue state AFK consumes.
running	Timeline state while a worker owns the issue. Live state is local.
ready-for-human	A human decision is needed before delegation is safe.
blocked:dependency	Waits on req:N labels and should not page a human.
blocked:validation / blocked:spec	Can be requeued only after retry guidance is already decided.

What Ships

Plugin	Job	Use it when
dev	Engineering workflow: issue triage, AFK execution, worktree safety, review-gated landing, process dashboards, runner policy, and codebase orientation.	You want an agent to plan, execute, review, or ship code work.
memory	Governed operational memory: decisions, validations, reasoning attempts, stale-claim checks, context packs, and skill telemetry evidence.	You want agents to stop repeating old mistakes after context resets.
brain	Project-local knowledge: typed artifacts, personal/project facts, sources, graph connections, search, cited answers, and dashboards.	You want durable knowledge the human may ask about later.

Maintainer-only plugin:

Plugin	Job	Use it when
internal	Maintainer-only skills for operating this repository. Installable through the normal marketplace flow, but active only when plugins.internal.enabled: true is present.	You maintain red-skills itself.

The short version:

• Dev moves work.
• Memory improves agent execution.
• Brain preserves human-facing knowledge.

Quick Start

1. Bootstrap A Repo

Run this inside a target repository:

/red-setup

It creates and wires the RedSkills operating surface:

• .red/config.yaml with explicit plugins.<name>.enabled: true flags.
• GitHub issue labels such as needs-triage, ready-for-agent, ready-for-human, running, blocked:*, blocked:dependency, and req:N.
• Domain docs under .red/CONTEXT-MAP.md, .red/contexts/*/CONTEXT.md, and ADRs under .red/adr/.
• AGENTS.md / CLAUDE.md blocks for agent skills and the development workflow.
• RedSkills workflows such as red-issues-needs-triage.yml.
• Optional statusline wiring and primary-checkout branch guardrails.

Re-run /red-setup when adoption drifts. Run /red-doctor to inspect drift and operational probes without changing anything, or /red-doctor --fix for the approved, per-finding gated repair path.

2. Move Work Through Issues

/start                  # sharpen a plan against domain language and ADRs
/wayfinder              # map work too large for one agent session
/to-spec                 # publish the plan as a Spec issue
/to-tickets <spec>        # cut vertical implementation slices
/triage                 # make an issue delegable
/afk                    # drain ready-for-agent work in isolated worktrees

Shortcuts:

• Already have a delegable issue? Use /afk --issues N.
• Already have a spec? Use /to-tickets or /triage.
• Hit a bug? Use /report-bug, then /triage.
• Something is urgent? Label the issue priority:urgent; the /afk queue promotes it ahead of every --spec / --issues filter.

3. Use Memory And Brain Deliberately

$init                 # Memory setup: markdown-only or graph
$store Decision: ...
$recall topic
$capture Long-lived project or personal context...
$search topic
$think question

Use Memory for operational evidence that helps future agents act. Use Brain for knowledge the human wants preserved, searched, and cited later.

Host Support

Host	Surface	Notes
Claude Code	Marketplace plugins, slash commands, skills, hooks, MCP servers	Primary interactive host.
Codex CLI	Marketplace plugins, $skill invocation, MCP servers, footer integration	Namespace-qualified skill names may appear depending on client version.
OpenCode	Generated .opencode/skills, plugin modules, MCP config, provider config, TUI attention config	Installed through scripts/install-opencode.sh.
Pi	One npm-published package per plugin (@reddb-io/red-skills-<plugin> on npm, staged under packaging/pi/<name>/) carrying the shared skill buckets	Installed through pi install npm:@reddb-io/red-skills-<plugin>, or via scripts/install-pi.sh for repo-scoped installs and the --source-dir dev path.
GitHub Actions	Reusable AFK attempt workflow and composable action	Runs one AFK attempt per issue in adopter repos.

Plugin Boundaries

Dev

dev owns the engineering workflow: issue pipeline, AFK runtime, interactive landing, process visibility, setup/adoption checks, codebase orientation, and the navigator MCP server.

Core responsibilities:

• Bootstrap RedSkills with red-setup.
• Maintain issue state with triage, to-spec, and to-tickets.
• Execute delegable work with afk, or dispatch one concrete demand with go.
• Land a hand-worked branch with retake (the retired ship migrated there — ADR 0081).
• Resolve human gates with hitl or safe retries with retake.

Dev guard rails:

• When plugins.dev.enabled: true, the dev PreToolUse proxy enforces the worktree boundary for agent shell commands: git worktree add must target a registered lane under .red/tmp/, and branch-moving commands in the primary checkout (git switch, git checkout <branch>, git checkout -b, git switch -c, gh pr checkout) are blocked. Create branches through git worktree add .red/tmp/worktrees/manual/<slug> -b <branch> ... instead.
• plugins.dev.lock.primary-branch remains the explicit branch-lock workflow flag that setup writes for compatibility and base-pinning integrations.
• The dev shell-command guard is controlled by command_guard in .red/config.yaml. It runs from the agent PreToolUse hook, stays inert unless plugins.dev.enabled: true, and blocks matching shell commands before execution. These repo-defined rules are additional to the built-in .red/tmp worktree boundary above. global rules apply everywhere, main rules apply in the primary session scope (not specifically the Git branch named main), and worktree rules apply in /afk and /go worktrees under .red/tmp/. Deny rules support regex:<pattern>, prefix:<literal>, suffix:<literal>, exact:<literal>, and glob:<pattern>. Bare entries with *, ?, or [ are Bash globs; other bare entries match the exact command, a command prefix, or a command suffix at a shell-command boundary. command_guard.deny remains a legacy alias for command_guard.global.

Example policy, not a default:

command_guard:
  global:
    - "rm -Rf /*"
    - "git stash"
    - sudo
    - 'regex:(^|[;&|[:space:]])curl[[:space:]].*\|[[:space:]]*sh'
  main:
    - "git rebase"
    - "git checkout -b"
  worktree:
    - "git clean"

plugins:
  dev:
    enabled: true

Memory

memory is governed operational memory for code agents. It stores work evidence that can make future agents safer and faster: decisions, root causes, validation evidence, reasoning attempts, stale-claim checks, readiness, handoffs, and skill telemetry evidence.

Memory modes:

Mode	Storage	Best for
markdown-only	Plain notes under .red/memory/notes/.	Low-risk rollout with explicit store/recall only.
graph	Project-local RedDB store at .red/memory/graph.rdb.	Governed recall, provenance, supersession, readiness, context packs, Workbench, MCP/HTTP, and Skill telemetry.

Memory is not the Personal-fact store. Personal facts belong in Brain, not Memory. Broad human-facing project knowledge belongs in Brain too.

Start with plugins/memory/README.md.

Brain

brain is a project-local knowledge repository under .red/brain/*. It stores typed artifacts and graph connections for later search and cited synthesis.

Use Brain for:

• Personal facts, durable preferences, identity context, and relationship notes.
• Project notes, decisions, ideas, questions, sources, bookmarks, and meeting residue.
• brain think cited answers with confidence and missing-evidence signals.
• brain dashboard local summaries and KPI-style views.
• Optional outbound channel actions through the Brain channel bridge.

Start with plugins/brain/README.md.

GitHub Actions Lane

The AFK Actions lane runs one AFK attempt per issue from GitHub Actions. It is for adopter repos that want cloud execution without a local fleet.

Layer	Artifact	Job
Trigger + policy	reusable-afk-attempt.yml	workflow_call, manual dispatch, and trust gate.
Execution	.github/actions/afk-attempt	Sets up Node, runner CLI, auth env, and invokes the AFK launcher.
Runtime distribution	afk.mjs + the @reddb-io/red-skills npm package	Resolves the versioned dev bundle matching the checked-out red-skills ref via npm (ADR 0091), cache-first.

Adoption paths:

• Turnkey caller: install or copy an rs-afk-attempt.yml caller that wires issue/manual triggers to reddb-io/red-skills/.github/workflows/reusable-afk-attempt.yml@v2.
• Composable action: use reddb-io/red-skills/.github/actions/afk-attempt@v2 from your own workflow.

Pin @v2 to track the latest compatible v2 release. Pin a SHA when the caller needs a fully immutable action/runtime pair.

Workflow naming convention:

Prefix	Meaning
reusable-*	Reusable workflow_call workflow referenced by uses:; never copied into adopters.
rs-*	A caller that instantiates a reusable-* workflow with concrete triggers/inputs.
red-*	Standalone RedSkills workflow; internal CI or verbatim copy-installable.

Full guide: AFK Actions lane.

Repo Layout

Path	Purpose
plugins/dev	Plugin definition, skills, hooks, scripts, MCP config, and docs for engineering workflow.
plugins/memory	Plugin definition and skills for governed operational memory. Runtime source lives in apps/memory.
plugins/brain	Plugin definition and skills for Brain. Runtime source lives in apps/brain.
plugins/internal	Maintainer-only plugin definition and skills for operating this repository.
apps/dev	AFK, landing, dashboard, triage, runner, release/channel, and workflow runtime code.
apps/memory	Memory CLI, graph operations, Workbench, MCP/HTTP surfaces, evals, and diagnostics.
apps/brain	Brain CLI, store, MCP server, dashboard, channel bridge, and artifact logic.
apps/code-nav	LSP-backed MCP server used by the dev plugin.
apps/opencode-host	Adapter that emits OpenCode config, skills, hooks, MCP passthrough, and statusline/toast integration.
apps/red-browser	Browser CLI: opens a local annotation bridge for HTML artifacts, long-polls human feedback, and enforces the layout-audit gate.
packages/shared	Shared runtime helpers for plugin gates, bundle fetching, args, logging, and channels.
packages/browser-bridge	Local CLI-to-browser annotation bridge: injects an annotation SDK into HTML artifacts and long-polls for human feedback and layout-audit results.
packages/cdp-driver	CDP-based live-app driver for red-browser: connects to Chrome via DevTools Protocol, captures a11y-tree snapshots, and streams console/network events.
packages/build-info	Shared runtime build metadata helpers consumed by bundled apps.
packages/red-castle	AFK execution substrate (vendored submodule, @reddb-io/red-castle): sandcastle fork that owns per-attempt worktree isolation, agent spawning, and signal detection.
packaging/npm	The publishable @reddb-io/red-skills npm package (outside the pnpm workspace): built plugin bundles plus the three red-skills-* bin shims. The v2 client transport (ADR 0091).
.red	RedSkills' own project configuration: context map, glossaries, ADRs, issue-tracker docs, and agent rules.
.github/workflows	Release, CI, upstream watch, issue automation, PR review, and reusable AFK attempt workflows.

Installed plugin trees are definitions and launchers. Runtime bundles are built from apps/* and shipped inside the @reddb-io/red-skills npm package (ADR 0091) — one tarball carrying the dev, memory, and brain JS bundles plus the red-skills-dev / red-skills-memory / red-skills-brain bin shims. Session-start launchers resolve the version-pinned package via npm (npx -y @reddb-io/red-skills@<pin> semantics), cache-first, and integrity is npm's own tarball shasum — no GitHub-release download and no client-side signature step. The Memory/Brain native red engine binary is the one per-platform artifact that cannot ride in the tarball; those plugins resolve it separately at runtime.

Configuration

Per-repo RedSkills config lives in .red/config.yaml. The canonical written form is namespaced under plugins.<name>.*.

Minimal dev activation:

plugins:
  dev:
    enabled: true
    lock:
      primary-branch: true

Example runner/model config:

plugins:
  dev:
    enabled: true
    afk:
      models:
        opencode:
          think:
            model: minimax/MiniMax-M3

Model defaults and escalation rules are documented in model-tier-policy. The runtime source of truth is CONFIG_DEFAULTS in apps/dev/src/core/config.ts.

Operator-declared pre-merge checks (backpressure):

plugins:
  dev:
    afk:
      backpressure:
        - pnpm lint
        - cargo fmt --check

afk.backpressure is an ordered list of shell commands run in the worker-branch worktree after the implicit feedback gate (test/typecheck/lint/build) passes on the DONE path. Any non-zero command blocks the merge and parks the issue exactly like a feedback failure. When the list is non-empty, every executed check — pass and fail alike — is also rendered as a single aggregated, non-blocking COMMENT PR review, so the PR carries a legible evidence ledger without adding a new gate.

House rules:

• Labels are kebab-case or prefix:value: needs-triage, ready-for-agent, ready-for-human, priority:urgent, blocked:dependency, spec:42.
• RedSkills-managed workflows use role prefixes: red-*, reusable-*, or rs-*.
• Issues and Specs live on GitHub Issues.
• Project artifacts live under .red/.
• Use SSH git remotes for AFK-managed repositories.
• Do task work in isolated worktrees; the primary checkout's branch is for the human to control.

Skill Map

This is a map, not a replacement for the skill files. Open the linked SKILL.md before using a skill in a new context.

Area	Skills
Dev setup and issue flow	ask-red, red-setup, red-doctor, start, wayfinder, to-spec, to-tickets, triage, report-bug
Dev execution and landing	afk, go, manager, implement, tdd, verify, ground-truth, diagnose, hitl, retake, resolving-merge-conflicts
Dev operations and understanding	dashboard, audit-skills, daily-review, red-gains, context, zoom-out, improve-codebase-architecture, review-adrs, model-tier-policy, red-statusline, prototype, code-review, curate
Dev knowledge, productivity, and utilities	research, reflect, ff, handoff, write-a-skill, branch-lock, git-guardrails-claude-code, migrate-to-shoehorn, setup-pre-commit
Memory	init, store, recall, ingest, extract, context-status, skills-status, health, improve-skills, doctor, export, view, wiki-init, wiki
Brain	capture, search, think, status, view
MCP servers	castle, navigator, memory-mcp, brain

Development In This Repo

Install dependencies:

pnpm install

Common checks:

pnpm build
pnpm typecheck
pnpm test
pnpm bundle
./scripts/doctor-runners.sh

The workspace is managed by turbo and pnpm-workspace.yaml. Root scripts intentionally cover the runtime apps and shared packages while excluding unrelated heavy packages where needed.

Releasing

Releases run on changesets in two halves (ADR 0121). Nothing pushes a commit to main — the version bump is a reviewed PR like any other.

1. Land your change with a changeset. Run pnpm changeset, pick patch/minor/major, describe the change in one consumer-facing line, and commit the generated file under .changeset/. A change that ships without one accumulates no bump and never releases.
2. red-release.yml maintains the Version Packages PR. On every push to main it collects the pending changesets and opens/updates a chore(release): version packages PR. That PR runs pnpm release:version — changeset version plus scripts/sync-version.mjs, the single writer (ADR 0040) that carries the version into the root package.json, the Claude and Codex plugin manifests, and the Pi manifests. pnpm version:sync:check fails CI if any of them drifts.
3. Merging that PR cuts the tag. main now has no pending changesets and a version no tag points at, so red-release.yml tags vX.Y.Z.
4. red-publish.yml publishes the tag. It builds the bundles, stages them into the @reddb-io/red-skills npm package, runs the real packaged client against the packed tarball as a producer/consumer contract check, npm publishes, smokes the published package from the registry, cuts the GitHub Release with the assets, and moves the matching major tag such as v2 so reusable workflows pinned to @v2 keep advancing.

The publish job runs in the GitHub environment named red-release. Repository settings must keep that environment protected with required reviewers, because approval is the gate before the job publishes release assets or moves the major tag. Once an approved reviewer approves the environment deployment, the publish continues without any extra manual step.

Publishing defers while any open issue carries the running label (an /afk fleet is mid-iteration); an hourly schedule retries the newest tag that has no GitHub Release yet, and every stage is idempotent so the retry resumes rather than conflicts.

License

Apache-2.0. See LICENSE. See NOTICE for upstream MIT attribution and bundled runtime notices.