ericrisco/rsc-harness

---

The problem

• You explain everything again. Every new session, every new project: the stack, the conventions, what was decided, what must not be touched.
• What the agent does not know, it invents. And the guess looks plausible, which is worse than an obvious error.
• Decisions die with the chat. What you settled yesterday is gone the moment the window closes.

The most important thing an agent needs is documentation, and nobody keeps it for the agent.

When people fix this by hand, the result is a Frankenstein harness: duplicated instructions, unrelated skills, premature hooks, unnecessary MCPs and no clear owner. Open standards cover single parts (Agent Skills, MCP, AGENTS.md), but none of them decides which complete harness your project needs.

---

The idea: documentation is your agent’s memory

The model is the brain your agent rents, and you already have it. rsc adds the rest, in four pieces:

Why documentation comes first

An agent without documentation spends most of its effort searching. It opens files, greps, reads the same module twice, and still ends up guessing. Every one of those turns costs tokens, and the guess costs more later.

With a well-structured 02-DOCS/, the agent knows where to look. It finds what it needs in one read instead of ten, so the same task costs fewer tokens.

And because it finds what already exists, it builds on it:

• It reuses the function you already have instead of writing a second one.
• It follows the structure your project already uses, every time.
• It works from what is true about your code, not from a plausible guess, so less of what it writes breaks.

Good documentation is not overhead for your agent. It is what makes it cheaper and better at the same time.

---

A day with rsc

1. You install it. It asks a few questions in plain language: how technical to talk, what the project is for, its goal, and which assistants you use. It reads only the project root.
2. It shows the plan before it writes anything. Every piece is selected, deferred or excluded, each with its reason. Nothing is written until you accept that exact plan.
3. You ask for things. The agent decides how much process each request needs, and says so in one line: an answer, a quick change (FTD), or the full chain (SDD).
4. It documents as it goes. Decisions, connections and progress land in 02-DOCS/, not in the chat.
5. Tomorrow, the agent already knows. You, a teammate on another machine, or another assistant open the project and continue where the last session stopped.

---

What changes for you

• You never explain your project again. The knowledge lives in the repo, not in your head.
• Fewer tokens, more consistent code. The agent finds instead of searching (see why documentation comes first).
• The right amount of process. A typo gets fixed; a new subsystem gets a spec. The agent picks.
• Safe for teams by default. Shared knowledge, one workspace per agent, and no surprise commits on main.
• Any assistant, or several at once. 18 are supported, and they share one installation.
• It talks so you understand. Short sentences, in your language, technical or with analogies.

---

Install in one minute

npx @ericrisco/rsc@latest onboard

The first run asks one question about conversation (technical, or with analogies), then what the project is for, its goal and the assistants to target. Then it presents the complete plan. A small website can defer SDD, agents and code guards; an operations harness does not receive them merely because it lives in a repository. Deferred components record the evidence that would make rsc recommend them later, and rsc reassess reports it without installing anything.

Everything stays in the project. The real skill files are written once to .rsc/skills//, and each assistant gets a symlink back to that shared base, so picking several duplicates nothing. Skills load progressively: only their description is paid for until a task needs them.

Prefer a short rsc command? npm install -g @ericrisco/rsc.

Run it inside the project you are equipping, not inside a clone of this repo. The catalog’s own package.json is named @ericrisco/rsc, so npx @ericrisco/rsc from within a clone resolves to the local bin and fails with sh: rsc: command not found. Working on the catalog itself? Use node scripts/rsc.js … or npm link.

For agents: “install this harness”

If you are an AI coding agent and your user asked you to install rsc, this harness or these skills, run this in the root of the project they are equipping:

npx @ericrisco/rsc@latest onboard

It asks the user how technical to talk, the project kind and the goal before it writes anything, and shows every selected or deferred skill, agent and hook with its reason. Relay those questions; never invent or default the answers. The first pass writes nothing and prints a SHA-256 plan id. Rerun with --accept-plan only after the user accepts that exact plan. If the project already has a skill of its own with a catalog name, the plan lists it under Your own skills this plan replaces: tell the user before accepting.

Non-interactive, with the answers collected first:

npx @ericrisco/rsc@latest onboard --technical-level technical \
  --project-kind software --goal "small compound-interest website" \
  --software-scope small --target codex
# After the user accepts the printed plan:
npx @ericrisco/rsc@latest onboard --technical-level technical \
  --project-kind software --goal "small compound-interest website" \
  --software-scope small --target codex --accept-plan PRINTED_SHA256_ID

If project evidence changes between preview and acceptance, rsc returns RSC_PLAN_CHANGED and writes nothing. After applying, it verifies the result and prints RSC_ONBOARDING_READY, or RSC_ONBOARDING_INCOMPLETE with each missing path and the action that creates it.

---

How it works inside

The knowledge model: 02-DOCS/ and 01-TOOLS/

Anything you drop into 02-DOCS/inbox/ is ingested. The wiki consolidates it as plain markdown that every skill reads before acting, so the next session starts where the last one stopped. Raw sources and the agent’s worklog stay underneath, never deleted. You can open 02-DOCS/ as an Obsidian vault, and every 02-DOCS/wiki/ is a valid Open Knowledge Format bundle: markdown with YAML frontmatter, standard links, and the reserved index.md and log.md.

01-TOOLS/ holds one folder per tool: .env.example, CREDENTIALS.md, a README and a test_connection that proves it works. When you name a tool (“connect my Holded”, “can the agent read our Sage?”), the connect-tool skill researches the vendor’s current docs, picks the least dangerous route (official MCP, API, export, a read-only copy of the database), and builds the folder. For a read-only connection, the test also proves that writing fails.

Three lanes, and the agent picks

Every turn takes exactly one lane, and the agent names it in one line, in your language.

1. Answer. The request asks for information: explain, compare, investigate, audit, review, propose. It is read-only: nothing is written and no artifact is created. When intent is unclear it asks one question and stays here.
2. FTD, Fast-Track Development. The request authorises a change. This is the default for ordinary work. One feature document holds intent, scope, a checklist, the evidence and the next step. Tasks are checked off against observed proof, never against intention.
3. SDD, the ten-phase chain. For the big or complex: several decisions that affect each other. The agent enters it on its own, and you still decide what gets built: you approve the spec and answer the clarifying questions, then review each phase or let it run on autopilot. Publishing always asks.

Ask for the other lane and it switches.

Skills, and how they are recommended

The unit of installation is one skill: install fastapi without ever pulling go. Two faces share one catalog (manifest.json):

• In the terminal, rsc consult ranks the catalog against your words and what it detects in the repo (package.json + next → nextjs, go.mod → go, Dockerfile → docker).
• In the chat, the always-on suggest notices when a task needs a skill you do not have, names it, and installs it on a one-word yes.

Every skill passed a research → spec → implement → adversarial review pipeline and an objective rubric (scripts/skill-rubric.md) written before any skill existed. Skills that scored 8.0 were sent back and fixed, not waved through.

Hooks and guards

In Claude Code, hooks enforce what instructions only ask for: the lane decisor on every turn, a refusal before a commit on a closed main, a confirmation before destructive commands, and a nudge to write the feature document before the first code edit. Every refusal says how to carry on. The rules only see what the agent runs; a person committing in their own terminal is never touched.

Limit, stated plainly. Those guards run in Claude Code. In Codex, Gemini, Cursor and OpenCode the same rules travel in the skills and the session memory. They are followed, but no hook enforces them.

Working as a team

Day ninety is where harnesses break, especially with several people, assistants and sessions on one project. rsc handles four things by default:

How it knows a project is complex. A hook counts what anyone can check: a CI setup, a deployment file (Dockerfile, vercel.json, fly.toml…) or at least two people in the last 50 commits. The answer you gave at install always wins over this detection.

Knowledge sync, step by step

ana    · feat/login     edits 02-DOCS/wiki/api.md ──► rsc/knowledge      (when her turn ends)
eric   · feat/payments  📥 1 change from Ana        ◄── rsc/knowledge      (before his next message)
main   · protected      untouched, gets it inside the next merged pull request
new    · clones main    has it all after the first message

• When a turn ends, your changes in those folders are committed on your branch as 📝 docs(auto): … and sent to rsc/knowledge. Only the copy on rsc/knowledge carries [skip ci], so your own pushes still run CI. On a closed main, or with code of yours still uncommitted, nothing is committed on your branch: the snapshot only goes to rsc/knowledge.
• Before each message, what teammates sent comes into the branch you are on as a 📥 docs(auto): sync commit, and you are told in one line. Only knowledge folders are touched.
• It never pushes to main, pushes your code, brings in anybody else’s code, syncs your personal user-profile.md, or overwrites a file you are editing.

It runs in the turn hooks of Claude Code, Codex, Gemini, Cursor, OpenCode and DeepSeek Harness. It is a project switch: if one person stopped sending, the rest would stop seeing their work.

Sharing the harness through git

Commit these: .rsc.json (which assistants, which skills, which catalog version), 01-TOOLS/, 02-DOCS/, and skills or agents you wrote by hand. rsc ignores the rest for you: .rsc/ (machine state) and the skill entries it manages (symlinks here, copies on Windows).

Three files carry the harness through git: .rsc.json, .claude/settings.json and .claude/rsc-bootstrap.mjs, the small file that notices in a clone that the rest is not built yet. Commit all three. Because rsc-bootstrap.mjs runs on every session, review changes to it the way you would review a CI workflow.

Whoever clones runs one command and gets the same harness, at the version the project pinned in its .rsc.json as catalogVersion:

npx @ericrisco/rsc@ sync

You do not have to know that. Open the project and the assistant tells you, in the first message, what is missing and the exact command, naming the pinned version. It asks; it never installs on its own. A teammate who clones in three months gets what you had, not what shipped since. After a git pull, rsc doctor tells you what no longer matches; nothing is written by a pull.

Own skills. A skill your team wrote lives in the repo and works for whoever clones. rsc never installs, updates or overwrites it: its version is the commit. Installing a catalog skill with the same name is refused, and doctor lists what is yours by reading the files. Declaring a skill under ownSkills still works.

Git permissions

A harness installed from scratch lets the agent run git commit, git push and gh pr create without asking, because those steps close every lane. A force-push still asks, and in Claude Code a commit on a closed main is still refused. It is saved as gitPermissions in .rsc.json.

rsc git-permissions status | on | off explains, per assistant, what rsc controls and what is left to the assistant.

Memory between sessions

On supported local targets, rsc checkpoints observable repository state (branch, worktree, HEAD, changed paths, commits, SDD status) and injects it before the first action of a new session in the same checkout.

• Full: Claude Code, Codex, Gemini CLI, OpenCode and DeepSeek Harness. Codex asks you to trust the project hook once with /hooks.
• Assisted: Cursor desktop, through an always-on rule that reads before acting.
• Never cloud: the memory runtime makes no network request.

The journal never stores prompts, responses, tool output, file contents or secrets. It stays in a git-excluded local path, keeps 30 days, and injects at most 4,096 bytes. rsc memory off disables it.

Review that only brings you what is real

In SDD, review sends three adversarial reviewers at the diff (correctness, security, tests). They often report the same defect in different words, and a reviewer hunting for problems can overstate one. So rsc review consolidate merges the duplicates, and every serious finding left goes to a fresh finding-verifier agent whose starting position is that the finding is false. It blocks the merge only if the verifier reproduces or traces it. You get “11 reported → 4 unique → 2 confirmed”, with the refuted ones listed and their reason.

It talks so you understand

• Short sentences, one idea each, in the style of ASD-STE100 (the controlled writing of aircraft manuals), always in your language.
• The answer first. Every answer stands alone, without “that fix” or “as above”.
• One setting: technical, or with analogies.
• A ladder when you do not follow: text, then a diagram, then an HTML page, and a video only if you ask.

Every turn closes with a short compass: where you are, and the next step as a question. Text you send to other people (emails, posts, READMEs) goes through unslop, so it sounds like a person.

---

Supported assistants

The real files land once in .rsc/skills//; each assistant gets a symlink or a converted file. The wizard asks which ones; --target a,b does it non-interactively.

codex, zed, amp, opencode, deepseek and jules share one root AGENTS.md; the block is written once.

DeepSeek Harness (dsh) has no project-level hooks, so once per machine rsc adds one marked block to ~/.dsh/cordis.patch.yml that runs the hooks of whichever project the session is in. Restart dsh once after the first install; delete the block to turn it off.

manifest.json is the generated public inventory: 34 agents (5 base + 29 selective specialists) and 53 command entries (20 fixed + 33 stack aliases). Unsupported means rsc writes nothing for that surface. Generated agents carry no model: on OpenCode, so they use the session’s model; pin one for the team with rsc agent-model . If you edit a generated agent, rsc sync keeps your file, and rsc agents reset takes rsc’s version back after a backup.

---

CLI

rsc below is short for npx @ericrisco/rsc. Without a global install (npm i -g @ericrisco/rsc), the bare rsc answers command not found: type the npx form.

# Setup
rsc onboard                          # plain-language onboarding; writes nothing until you accept
rsc reassess                         # check deferred components against new evidence
rsc add fastapi postgresdb           # install skills by name
rsc consult "I want to launch a SaaS"  # recommend only
rsc sync                             # refresh managed skills and hooks

# Team
rsc main status | unlock | lock      # whether the agent may work on main
rsc isolation status | off           # worktrees for parallel sessions
rsc knowledge-sync status | off      # the shared knowledge exchange
rsc git-permissions status | on | off

# Agents and review
rsc agent-model opencode inherit     # agents use the session's model
rsc agents status | reset      # installed agents, and the ones you edited
rsc review consolidate c.md s.md t.md  # merge reviewer findings; serious ones go to finding-verifier

# Documentation
rsc ingest notas.md --topic crm      # move a file into 02-DOCS/raw/ (verified copy), then document it
rsc copy rules | check ad.txt        # the phrases this project forbids, and a check before publishing

# Memory and diagnostics
rsc memory status | off | resume     # session continuity; «recuerda esto» goes to 02-DOCS/wiki/
rsc doctor                           # harness health and onboarding readiness
rsc repair                           # put the harness back to what is declared
rsc backups | restore latest         # project-local snapshots
rsc uninstall  | purge           # remove one skill, or everything rsc installed

rsc doctor

doctor answers two questions, on separate lines:

Harness health: healthy
Onboarding readiness: pending
Pending: 02-DOCS/wiki/sdd/constitution.md (draft)

Harness health says whether what is installed works, and it is the only thing the exit code follows. Onboarding readiness says whether onboarding is finished (ready, pending, incomplete, or not onboarded for a manual install); it never changes the exit code.

Something’s off? rsc repair

If the harness is wired for the wrong assistant, a hook runs several times, or skills appear that you never asked for, run npx @ericrisco/rsc@latest repair. It shows what it found before touching anything, keeps a recoverable copy, and never touches skills or agents you wrote by hand. Add --dry-run to see the pass without writing.

Update

rsc updates itself. At session start it checks npm. A release in the same major installs in the background and takes effect next session; a new major asks first. To turn it off, create .rsc/.no-auto-update. By hand: npm install -g @ericrisco/rsc@latest && rsc sync. Every sync snapshots the project first, so rsc restore latest undoes a bad update.

---

The catalog

269 skills, grouped by what you are trying to do. Click any skill to read its SKILL.md. It fires on its own when a task matches.

🧭 Core & control plane

init · harness · orient · suggest · unslop · author-skill · sdd-init

📐 Spec-Driven Development

Two lanes for change: ftd for ordinary work, and the ten-phase chain when durable artifacts would settle a real ambiguity. idea-refinement runs inside specify; decision-challenge is on demand.

ftd · sdd · constitution · idea-refinement · specify · clarify · plan · tasks · analyze · decision-challenge · implement · source-grounded-development · verify · review · simplify-code · ship · debug · worktrees · parallel

💼 Run a business

finance-ops · invoicing · bookkeeping · pricing · sales-pipeline · lead-gen · cold-outreach · proposals · contracts · customer-support · client-onboarding · retention · hiring · people-ops · inventory · logistics-ops · procurement · meeting-notes · sop-builder · project-ops

💸 Raise & model money

pitch-deck · investor-materials · financial-model · fundraising · unit-economics · grants

⚖️ Legal, privacy & compliance

gdpr-privacy · terms-conditions · compliance · data-policy · ip-trademark

📣 Market & brand

marketing · seo-geo · content-engine · social-publisher · brand-voice · brand-identity · newsletter · landing-copy · ads · article-writing · case-studies · video-shorts · podcast · market-research · competitor-watch · press-kit · community · webinar · review-management

🎬 Grow a channel

Each with a 02-DOCS feedback loop that learns from your own results.

youtube-api · youtube-strategy · youtube-ideation · youtube-thumbnails · youtube-packaging · remotion-video · tiktok-api · instagram-api · shortform-strategy · shortform-ideation · shortform-packaging · shortform-editing · viral-score · linkedin-api · linkedin-strategy · linkedin-content · linkedin-carousels · linkedin-outreach · medium-writing · medium-publishing · medium-strategy

🔌 Connect & automate

connect-tool · stripe · email-connector · google-workspace · notion-connector · whatsapp-telegram · automation-flows · api-connector-builder · webhooks · data-scraper · spreadsheet-ops · calendar-scheduling · document-processing · e-signature

⚙️ Automation

Drive the big automation platforms through their REST API or MCP server. automation-strategy decides whether, what and which platform.

automation-strategy · n8n · make · zapier · power-automate

📊 Data & analytics

analytics · dashboard · kpi-framework · reporting · ab-testing · forecasting · data-cleaning · business-intelligence

🤖 AI: build it in

building-agents · rag · embeddings-search · prompt-engineering · llm-pipeline · agent-eval · chatbot · ai-media · replicate-images · structured-extraction · agent-safety · cost-tracking

🛰️ AI: run it on

replicate · runpod · modal · huggingface · ollama · together-fireworks · fal

🎓 AI: train it

machine-learning · deep-learning · nlp · finetuning · training-data · unsloth · open-weights · vllm

🗣️ Languages

typescript · python · java · csharp-dotnet · php · ruby · cpp · elixir · bash-scripting · sql · go

🏗️ Frameworks & app stacks

fastapi · nextjs · react · react-native · vue-nuxt · angular · svelte · astro · solid-js · htmx · nodejs · nestjs · django · laravel · rails · spring-boot · phoenix · flutter · swift-ios · kotlin-android · compose-multiplatform · expo · tauri · electron · rust · wordpress · shopify · no-code-app · chrome-extension · api-design

🎮 Game development

godot · unity · unreal · game-design · game-storytelling · level-design · gamedev-shaders · gamedev-multiplayer · gamedev-physics · gamedev-pathing · gamedev-shipping

🗄️ Databases & data layer

postgresdb · mysql · mongodb · redis · supabase · neon · planetscale · sqlite-turso · prisma-orm · drizzle-orm · firebase · dynamodb · vector-db · clickhouse-analytics · duckdb · db-migrations · backups

☁️ Ship & operate: platforms

vercel · netlify · cloudflare · railway · render · fly-io · coolify · hetzner · digitalocean · aws-essentials · gcp-essentials

🛠️ Ship & operate: devops

docker · github-actions · git-workflow · domains-dns · monitoring · email-deliverability · scaling · deployment · deprecation

🔒 Ship & operate: quality & security

code-review · security-scan · secure-coding · testing-py · testing-web · testing-go · e2e-testing · accessibility · performance · error-handling · observability

🌀 Motion & interface craft

variant-explorer · scroll-film

🎨 Design & content craft

design · ux · presentations · course-storytelling · course-builder · technical-writing · translation-l10n

🧠 Knowledge & meta

knowledge-ops · codebase-onboarding · research-ops · decision-records · continuous-learning · skill-scout · context-budget · roast-me · fable-operator

---

Why you can trust it

The harness is built on ten principles. Three of them shape everything else:

• Evidence over claims. A task is done when its check was observed, not when someone believes it works. The same rule applies to this README: every number here comes from manifest.json or the code, and tests check that the README and the code agree.
• A gate that checks nothing is worse than no gate. Every rule rsc declares binding ships with the mechanism that enforces it and a test that watches that mechanism fail and pass.
• Friction proportional to risk. Silence for the trivial, ceremony only where failure is expensive. A harness that nags on harmless work gets switched off.

Known limits, stated openly: the hard guards run only in Claude Code; OpenCode 2 and Windows have had less real-world testing than macOS and Linux; and the session memory is local by design, never cloud.

---

Contributing

skills// is the single source of truth. Each skill is a directory whose SKILL.md frontmatter drives triggering and recommendations:

---
name: my-skill
description: Use when [specific triggers]… NOT x (that is sibling).
tags: [keyword, keyword]        # what the consult advisor searches over
recommends: [sibling-skill]     # what the system offers to install next
origin: risco
---

After editing any skill:

npm run manifest            # regenerate manifest.json from skills/*/SKILL.md
npm run validate            # validate frontmatter and recommends integrity
npm test                    # unit and integration tests
bash scripts/eval-lint.sh   # validate every skills/*/evals/cases.yaml

manifest.json is generated, never edited by hand; CI fails if it is stale. The rubric every skill is held to is scripts/skill-rubric.md. Bug reports are welcome as GitHub issues. Release notes are in GitHub Releases.

Third-party skills

Most of this catalog is written here. These are not, and they keep their author’s credit:

Adapted, not mirrored: each carries rsc frontmatter, routing evals and hand-offs to its siblings. The craft bar in them is the original author’s.

License

MIT. See LICENSE.