--- slug: "reddb-io-red-skills-dev" source_type: "readme" source_url: "https://cdn.jsdelivr.net/gh/reddb-io/red-skills@main/README.md" repo: "https://github.com/reddb-io/red-skills" source_file: "README.md" branch: "main" ---
RedSkills - agent workflow, governed Memory, and Brain knowledge for serious engineering agents

npm version CI License Plugins

The operating system for agentic engineering work.
RedSkills turns GitHub issues into reviewed PRs, remembers the operational evidence that prevents repeated mistakes, and gives every repo a local knowledge surface for Claude Code, Codex, OpenCode, Pi, and GitHub Actions.
--- RedSkills is reddb.io's plugin suite for serious code-agent workflows. It started as a reddb.io adaptation of [`mattpocock/skills`](https://github.com/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](https://github.com/reddb-io/red-skills/tree/HEAD/NOTICE). ## Install ### Universal Installer Recommended for normal installs and upgrades: ```bash 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/`, 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: ```bash # 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 ```text /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: ```text /red-setup /triage /afk --once /go "one concrete demand" /dashboard ``` Memory and Brain skills are plugin skills: ```text $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: ```text /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 ```bash 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 `$`. Some clients expose plugin skills with the plugin namespace; use that form when it appears in the skills list: ```text $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: ```bash 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//package.json` — the local-path install surface (ADR 0075-era shape; consumed by `pi install `). - `packaging/pi//package.json` plus `packaging/pi//skills/` — the npm publish surface (ADR 0110; consumed by `pi install npm:@reddb-io/red-skills-`). Both are generated. Do not hand-edit either. Change the Claude-side plugin manifest or the plugin tree, then run: ```bash pnpm pi:manifests # regenerates plugins//package.json pnpm pi:packages:build # stages packaging/pi// from plugins// ``` 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. ```bash 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: ```bash 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](https://github.com/reddb-io/red-skills/blob/HEAD/apps/opencode-host/README.md). ### 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: ```bash 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: ```bash # user-scoped install into ~/.pi/agent/settings.json (npm: surface) scripts/install-pi.sh # project-scoped install into /.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 `/.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: ```bash npx skills@latest add reddb-io/red-skills ``` For local symlinks: ```bash 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: ```bash ./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 ```text Plan -> Spec -> sliced issues -> ready-for-agent -> isolated worktree -> validation -> PR -> review/checks -> merge -> Memory evidence ``` The issue lifecycle is intentionally boring: ```text 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`](https://github.com/reddb-io/red-skills/blob/HEAD/plugins/dev/.claude-plugin/plugin.json) | 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`](https://github.com/reddb-io/red-skills/blob/HEAD/plugins/memory/README.md) | 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`](https://github.com/reddb-io/red-skills/blob/HEAD/plugins/brain/README.md) | 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`](https://github.com/reddb-io/red-skills/blob/HEAD/plugins/internal/README.md) | 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: ```text /red-setup ``` It creates and wires the RedSkills operating surface: - `.red/config.yaml` with explicit `plugins..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 ```text /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 # 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 ```text $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-` on npm, staged under `packaging/pi//`) carrying the shared skill buckets | Installed through `pi install npm:@reddb-io/red-skills-`, 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 plugin - issue pipeline, AFK runtime, landing, and codebase orientation `dev` owns the engineering workflow: issue pipeline, AFK runtime, interactive landing, process visibility, setup/adoption checks, codebase orientation, and the [`navigator` MCP server](https://github.com/reddb-io/red-skills/blob/HEAD/apps/code-nav/README.md). Core responsibilities: - Bootstrap RedSkills with [`red-setup`](https://github.com/reddb-io/red-skills/blob/HEAD/plugins/dev/skills/engineering/red-setup/SKILL.md). - Maintain issue state with [`triage`](https://github.com/reddb-io/red-skills/blob/HEAD/plugins/dev/skills/engineering/triage/SKILL.md), [`to-spec`](https://github.com/reddb-io/red-skills/blob/HEAD/plugins/dev/skills/engineering/to-spec/SKILL.md), and [`to-tickets`](https://github.com/reddb-io/red-skills/blob/HEAD/plugins/dev/skills/engineering/to-tickets/SKILL.md). - Execute delegable work with [`afk`](https://github.com/reddb-io/red-skills/blob/HEAD/plugins/dev/skills/engineering/afk/SKILL.md), or dispatch one concrete demand with [`go`](https://github.com/reddb-io/red-skills/blob/HEAD/plugins/dev/skills/engineering/go/SKILL.md). - Land a hand-worked branch with [`retake`](https://github.com/reddb-io/red-skills/blob/HEAD/plugins/dev/skills/engineering/retake/SKILL.md) (the retired `ship` migrated there — ADR 0081). - Resolve human gates with [`hitl`](https://github.com/reddb-io/red-skills/blob/HEAD/plugins/dev/skills/engineering/hitl/SKILL.md) or safe retries with [`retake`](https://github.com/reddb-io/red-skills/blob/HEAD/plugins/dev/skills/engineering/retake/SKILL.md). 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 `, `git checkout -b`, `git switch -c`, `gh pr checkout`) are blocked. Create branches through `git worktree add .red/tmp/worktrees/manual/ -b ...` 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:`, `prefix:`, `suffix:`, `exact:`, and `glob:`. 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: ```yaml 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 plugin - governed evidence that makes the next agent safer and faster `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](https://github.com/reddb-io/red-skills/blob/HEAD/plugins/memory/README.md). ### Brain brain plugin - project-local knowledge, cited synthesis, and a local dashboard `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](https://github.com/reddb-io/red-skills/blob/HEAD/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`](https://github.com/reddb-io/red-skills/blob/HEAD/.github/workflows/reusable-afk-attempt.yml) | `workflow_call`, manual dispatch, and trust gate. | | Execution | [`.github/actions/afk-attempt`](https://github.com/reddb-io/red-skills/blob/HEAD/.github/actions/afk-attempt/action.yml) | 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](https://github.com/reddb-io/red-skills/blob/HEAD/plugins/dev/skills/engineering/afk/actions-lane.md). ## Repo Layout | Path | Purpose | | --- | --- | | [`plugins/dev`](https://github.com/reddb-io/red-skills/tree/HEAD/plugins/dev) | Plugin definition, skills, hooks, scripts, MCP config, and docs for engineering workflow. | | [`plugins/memory`](https://github.com/reddb-io/red-skills/tree/HEAD/plugins/memory) | Plugin definition and skills for governed operational memory. Runtime source lives in `apps/memory`. | | [`plugins/brain`](https://github.com/reddb-io/red-skills/tree/HEAD/plugins/brain) | Plugin definition and skills for Brain. Runtime source lives in `apps/brain`. | | [`plugins/internal`](https://github.com/reddb-io/red-skills/tree/HEAD/plugins/internal) | Maintainer-only plugin definition and skills for operating this repository. | | [`apps/dev`](https://github.com/reddb-io/red-skills/tree/HEAD/apps/dev) | AFK, landing, dashboard, triage, runner, release/channel, and workflow runtime code. | | [`apps/memory`](https://github.com/reddb-io/red-skills/tree/HEAD/apps/memory) | Memory CLI, graph operations, Workbench, MCP/HTTP surfaces, evals, and diagnostics. | | [`apps/brain`](https://github.com/reddb-io/red-skills/tree/HEAD/apps/brain) | Brain CLI, store, MCP server, dashboard, channel bridge, and artifact logic. | | [`apps/code-nav`](https://github.com/reddb-io/red-skills/tree/HEAD/apps/code-nav) | LSP-backed MCP server used by the `dev` plugin. | | [`apps/opencode-host`](https://github.com/reddb-io/red-skills/tree/HEAD/apps/opencode-host) | Adapter that emits OpenCode config, skills, hooks, MCP passthrough, and statusline/toast integration. | | [`apps/red-browser`](https://github.com/reddb-io/red-skills/tree/HEAD/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`](https://github.com/reddb-io/red-skills/tree/HEAD/packages/shared) | Shared runtime helpers for plugin gates, bundle fetching, args, logging, and channels. | | [`packages/browser-bridge`](https://github.com/reddb-io/red-skills/tree/HEAD/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`](https://github.com/reddb-io/red-skills/tree/HEAD/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`](https://github.com/reddb-io/red-skills/tree/HEAD/packages/build-info) | Shared runtime build metadata helpers consumed by bundled apps. | | [`packages/red-castle`](https://github.com/reddb-io/red-skills/tree/HEAD/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`](https://github.com/reddb-io/red-skills/tree/HEAD/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`](https://github.com/reddb-io/red-skills/blob/HEAD/.red) | RedSkills' own project configuration: context map, glossaries, ADRs, issue-tracker docs, and agent rules. | | [`.github/workflows`](https://github.com/reddb-io/red-skills/tree/HEAD/.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`](https://github.com/reddb-io/red-skills/tree/HEAD/packaging/npm) 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@` 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..*`. Minimal `dev` activation: ```yaml plugins: dev: enabled: true lock: primary-branch: true ``` Example runner/model config: ```yaml plugins: dev: enabled: true afk: models: opencode: think: model: minimax/MiniMax-M3 ``` Model defaults and escalation rules are documented in [`model-tier-policy`](https://github.com/reddb-io/red-skills/blob/HEAD/plugins/dev/skills/engineering/model-tier-policy/SKILL.md). The runtime source of truth is `CONFIG_DEFAULTS` in [`apps/dev/src/core/config.ts`](https://github.com/reddb-io/red-skills/blob/HEAD/apps/dev/src/core/config.ts). Operator-declared pre-merge checks (backpressure): ```yaml 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`](https://github.com/reddb-io/red-skills/blob/HEAD/plugins/dev/skills/engineering/ask-red/SKILL.md), [`red-setup`](https://github.com/reddb-io/red-skills/blob/HEAD/plugins/dev/skills/engineering/red-setup/SKILL.md), [`red-doctor`](https://github.com/reddb-io/red-skills/blob/HEAD/plugins/dev/skills/engineering/red-doctor/SKILL.md), [`start`](https://github.com/reddb-io/red-skills/blob/HEAD/plugins/dev/skills/engineering/start/SKILL.md), [`wayfinder`](https://github.com/reddb-io/red-skills/blob/HEAD/plugins/dev/skills/engineering/wayfinder/SKILL.md), [`to-spec`](https://github.com/reddb-io/red-skills/blob/HEAD/plugins/dev/skills/engineering/to-spec/SKILL.md), [`to-tickets`](https://github.com/reddb-io/red-skills/blob/HEAD/plugins/dev/skills/engineering/to-tickets/SKILL.md), [`triage`](https://github.com/reddb-io/red-skills/blob/HEAD/plugins/dev/skills/engineering/triage/SKILL.md), [`report-bug`](https://github.com/reddb-io/red-skills/blob/HEAD/plugins/dev/skills/engineering/report-bug/SKILL.md) | | Dev execution and landing | [`afk`](https://github.com/reddb-io/red-skills/blob/HEAD/plugins/dev/skills/engineering/afk/SKILL.md), [`go`](https://github.com/reddb-io/red-skills/blob/HEAD/plugins/dev/skills/engineering/go/SKILL.md), [`manager`](https://github.com/reddb-io/red-skills/blob/HEAD/plugins/dev/skills/engineering/manager/SKILL.md), [`implement`](https://github.com/reddb-io/red-skills/blob/HEAD/plugins/dev/skills/engineering/implement/SKILL.md), [`tdd`](https://github.com/reddb-io/red-skills/blob/HEAD/plugins/dev/skills/engineering/tdd/SKILL.md), [`verify`](https://github.com/reddb-io/red-skills/blob/HEAD/plugins/dev/skills/engineering/verify/SKILL.md), [`ground-truth`](https://github.com/reddb-io/red-skills/blob/HEAD/plugins/dev/skills/engineering/ground-truth/SKILL.md), [`diagnose`](https://github.com/reddb-io/red-skills/blob/HEAD/plugins/dev/skills/engineering/diagnose/SKILL.md), [`hitl`](https://github.com/reddb-io/red-skills/blob/HEAD/plugins/dev/skills/engineering/hitl/SKILL.md), [`retake`](https://github.com/reddb-io/red-skills/blob/HEAD/plugins/dev/skills/engineering/retake/SKILL.md), [`resolving-merge-conflicts`](https://github.com/reddb-io/red-skills/blob/HEAD/plugins/dev/skills/engineering/resolving-merge-conflicts/SKILL.md) | | Dev operations and understanding | [`dashboard`](https://github.com/reddb-io/red-skills/blob/HEAD/plugins/dev/skills/engineering/dashboard/SKILL.md), [`audit-skills`](https://github.com/reddb-io/red-skills/blob/HEAD/plugins/dev/skills/engineering/audit-skills/SKILL.md), [`daily-review`](https://github.com/reddb-io/red-skills/blob/HEAD/plugins/dev/skills/engineering/daily-review/SKILL.md), [`red-gains`](https://github.com/reddb-io/red-skills/blob/HEAD/plugins/dev/skills/engineering/red-gains/SKILL.md), [`context`](https://github.com/reddb-io/red-skills/blob/HEAD/plugins/dev/skills/engineering/context/SKILL.md), [`zoom-out`](https://github.com/reddb-io/red-skills/blob/HEAD/plugins/dev/skills/engineering/zoom-out/SKILL.md), [`improve-codebase-architecture`](https://github.com/reddb-io/red-skills/blob/HEAD/plugins/dev/skills/engineering/improve-codebase-architecture/SKILL.md), [`review-adrs`](https://github.com/reddb-io/red-skills/blob/HEAD/plugins/dev/skills/engineering/review-adrs/SKILL.md), [`model-tier-policy`](https://github.com/reddb-io/red-skills/blob/HEAD/plugins/dev/skills/engineering/model-tier-policy/SKILL.md), [`red-statusline`](https://github.com/reddb-io/red-skills/blob/HEAD/plugins/dev/skills/engineering/red-statusline/SKILL.md), [`prototype`](https://github.com/reddb-io/red-skills/blob/HEAD/plugins/dev/skills/engineering/prototype/SKILL.md), [`code-review`](https://github.com/reddb-io/red-skills/blob/HEAD/plugins/dev/skills/engineering/code-review/SKILL.md), [`curate`](https://github.com/reddb-io/red-skills/blob/HEAD/plugins/dev/skills/engineering/curate/SKILL.md) | | Dev knowledge, productivity, and utilities | [`research`](https://github.com/reddb-io/red-skills/blob/HEAD/plugins/dev/skills/knowledge/research/SKILL.md), [`reflect`](https://github.com/reddb-io/red-skills/blob/HEAD/plugins/dev/skills/productivity/reflect/SKILL.md), [`ff`](https://github.com/reddb-io/red-skills/blob/HEAD/plugins/dev/skills/productivity/ff/SKILL.md), [`handoff`](https://github.com/reddb-io/red-skills/blob/HEAD/plugins/dev/skills/productivity/handoff/SKILL.md), [`write-a-skill`](https://github.com/reddb-io/red-skills/blob/HEAD/plugins/dev/skills/productivity/write-a-skill/SKILL.md), [`branch-lock`](https://github.com/reddb-io/red-skills/blob/HEAD/plugins/dev/skills/misc/branch-lock/SKILL.md), [`git-guardrails-claude-code`](https://github.com/reddb-io/red-skills/blob/HEAD/plugins/dev/skills/misc/git-guardrails-claude-code/SKILL.md), [`migrate-to-shoehorn`](https://github.com/reddb-io/red-skills/blob/HEAD/plugins/dev/skills/misc/migrate-to-shoehorn/SKILL.md), [`setup-pre-commit`](https://github.com/reddb-io/red-skills/blob/HEAD/plugins/dev/skills/misc/setup-pre-commit/SKILL.md) | | Memory | [`init`](https://github.com/reddb-io/red-skills/blob/HEAD/plugins/memory/skills/core/init/SKILL.md), [`store`](https://github.com/reddb-io/red-skills/blob/HEAD/plugins/memory/skills/core/store/SKILL.md), [`recall`](https://github.com/reddb-io/red-skills/blob/HEAD/plugins/memory/skills/core/recall/SKILL.md), [`ingest`](https://github.com/reddb-io/red-skills/blob/HEAD/plugins/memory/skills/core/ingest/SKILL.md), [`extract`](https://github.com/reddb-io/red-skills/blob/HEAD/plugins/memory/skills/core/extract/SKILL.md), [`context-status`](https://github.com/reddb-io/red-skills/blob/HEAD/plugins/memory/skills/core/context-status/SKILL.md), [`skills-status`](https://github.com/reddb-io/red-skills/blob/HEAD/plugins/memory/skills/core/skills-status/SKILL.md), [`health`](https://github.com/reddb-io/red-skills/blob/HEAD/plugins/memory/skills/core/health/SKILL.md), [`improve-skills`](https://github.com/reddb-io/red-skills/blob/HEAD/plugins/memory/skills/core/improve-skills/SKILL.md), [`doctor`](https://github.com/reddb-io/red-skills/blob/HEAD/plugins/memory/skills/core/doctor/SKILL.md), [`export`](https://github.com/reddb-io/red-skills/blob/HEAD/plugins/memory/skills/core/export/SKILL.md), [`view`](https://github.com/reddb-io/red-skills/blob/HEAD/plugins/memory/skills/core/view/SKILL.md), [`wiki-init`](https://github.com/reddb-io/red-skills/blob/HEAD/plugins/memory/skills/core/wiki-init/SKILL.md), [`wiki`](https://github.com/reddb-io/red-skills/blob/HEAD/plugins/memory/skills/core/wiki/SKILL.md) | | Brain | [`capture`](https://github.com/reddb-io/red-skills/blob/HEAD/plugins/brain/skills/core/capture/SKILL.md), [`search`](https://github.com/reddb-io/red-skills/blob/HEAD/plugins/brain/skills/core/search/SKILL.md), [`think`](https://github.com/reddb-io/red-skills/blob/HEAD/plugins/brain/skills/core/think/SKILL.md), [`status`](https://github.com/reddb-io/red-skills/blob/HEAD/plugins/brain/skills/core/status/SKILL.md), [`view`](https://github.com/reddb-io/red-skills/blob/HEAD/plugins/brain/skills/core/view/SKILL.md) | | MCP servers | [`castle`](https://github.com/reddb-io/red-skills/blob/HEAD/plugins/dev/skills/engineering/afk/MCP.md), [`navigator`](https://github.com/reddb-io/red-skills/blob/HEAD/apps/code-nav/README.md), [`memory-mcp`](https://github.com/reddb-io/red-skills/blob/HEAD/plugins/memory/.mcp.json), [`brain`](https://github.com/reddb-io/red-skills/blob/HEAD/plugins/brain/.mcp.json) | ## Development In This Repo Install dependencies: ```bash pnpm install ``` Common checks: ```bash pnpm build pnpm typecheck pnpm test pnpm bundle ./scripts/doctor-runners.sh ``` The workspace is managed by [`turbo`](https://github.com/reddb-io/red-skills/blob/HEAD/turbo.json) and [`pnpm-workspace.yaml`](https://github.com/reddb-io/red-skills/blob/HEAD/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](https://github.com/changesets/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](https://github.com/reddb-io/red-skills/blob/HEAD/.github/workflows/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`](https://github.com/reddb-io/red-skills/blob/HEAD/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](https://github.com/reddb-io/red-skills/blob/HEAD/.github/workflows/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 publish`es, 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](https://github.com/reddb-io/red-skills/tree/HEAD/LICENSE). See [NOTICE](https://github.com/reddb-io/red-skills/tree/HEAD/NOTICE) for upstream MIT attribution and bundled runtime notices.