What you get

riprap is two halves. The plugin carries 21 guardrail documents, twelve skills, twelve hook registrations and one agent, and puts no file in your repository. /riprap:install adds the half that has to live in the repo: the guardrail scripts, their shared pattern libraries, the git hooks, and the four stack commands the hooks call.

Nothing on this page needs an installation to read. That is the point of it — deciding whether to hand a tool write access to your repository is easier when you can see the inventory first.

The guardrail documents

Grouped by task rather than alphabetically, mirroring the router Claude Code injects and Codex skills load on demand. That grouping is deliberate: git.md and git-hooks.md sound interchangeable and cover different problems, and the file you want when CI is red is not named after CI in most repositories. Guessing from filenames costs more than reading a map.

The router also carries a line count next to each entry. Those are there so the model can budget context — two 80-line files usually beat one 215-line file when either would answer the question — and they are left off this page, because a human reader gets nothing from them and they would rot on every edit of every document.

Starting work

• project-standards.md — conventions that apply to everything in this repo. Read this first.
• interaction-preferences.md — how to work with the person on the other side of the session: when to argue, where a plan goes, and what to ask before starting.
• design.md — a change with material UI or UX impact gets a mockup before it gets an implementation, drawn inside the project’s design system and in its frontend library’s own primitives. Copy edits and invisible refactors are explicitly exempt; a new feature gets a full design, not one screen.
• development-workflow.md — when to stop and plan, how to scope a bug fix, what to clean up, and what “done” has to mean.
• handoffs.md — session handoffs always go in tmp/handoff/, never in docs/ or the repo root.
• writing-style.md — the writing standard that governs every reply, plan, task, commit message and pull request body: voice, tense, prescriptive verbs, and the bar a task has to clear before somebody else can pick it up. Distilled from the Google developer documentation style guide.
• communication-preferences.md — how long a conversational reply should be and what it should not contain: answer first, no preamble or recap, no hedging filler, prose over bullets, and length matched to the question.

Writing code

• design-principles.md — how much structure to build and when: the simplest thing that solves the whole problem, SOLID as a symptom detector, and what to do when the two pull apart.
• code-style.md — naming, structure, and comments: the parts of style a formatter cannot decide for you.
• error-handling.md — let errors surface, and keep secrets and personal data out of the logs.
• mcp-servers.md — how to decide whether a capability belongs in an MCP server at all, and what has to be written down when you add one.
• tech-footprint.md — never add a language, runtime or tool the repository does not already use without asking first.

Testing

• testing.md — how to write tests first, how to run them, how to interpret failures, and the four mistakes that cost the most.

Committing and merging

• git.md — worktrees, branching, when to commit, and merging rules, plus the failure modes that cost the most to undo.
• code-review.md — run /riprap:review over the diff before the pull request opens, publish every finding in the body with a disposition and a reason, and stay with the pull request until it merges.
• git-hooks.md — two hook families live under bin/hooks/. Telling them apart is the whole document.
• merge-gates.md — some changes never merge autonomously, however clean the review and however green the CI.
• ci-hygiene.md — how to re-run CI without corrupting the result or burning the budget.

Security

• secret-hygiene.md — credentials must never enter an agent’s context, and never reach a tracked file.
• permissions.md — what the allow/deny/ask lists can and cannot do, and why riprap never edits them for you.

Extending the guardrails

• guardrail-template.md — the shape every guardrail document follows. Copy it, fill in the sections, delete the guidance.

All 21 guardrail documents, alphabetically

The other view: what to scan when you want to be sure you have seen everything.

The twelve skills

Namespaced by the harness, so a repository with its own /learn keeps it.

None of them carry settings for you to edit. What a skill needs to know about your project it works out, confirms with you once, and writes into your own .riprap/instructions/ — a value edited into a skill would be reverted the next time the plugin updates.

• /riprap:install — installs or refreshes the repository payload, wires git hooks without taking over another hook manager, proposes stack-seam configuration, reports overlaps, and verifies the result.
• /riprap:learn — reviews the session and writes what was learned into your project’s instructions, never riprap’s, which are replaced on update. Also proposes narrow permissions.allow entries for any tool-and-argument pattern approved twice or more in the session — always the narrowest rule that covers actual usage, always confirmed with you before it touches settings.json.
• /riprap:spec — interactive feature definition: stakeholder interviews, mockups, phased work items, acceptance tests. Planning only; it writes no implementation.
• /riprap:architect — turns a settled requirement into an implementation plan its reader can execute without re-exploring: what already exists with line references, what has to change, the files, the ordered steps and how each is verified. Planning only; it writes no source.
• /riprap:implement — builds an approved plan: tests first, then three review passes — over the tests, the implementation and the pull request — each presented to you before anything is incorporated. Drives the checks green and hands the merge back to a person.
• /riprap:advise — a planning council: parallel research agents, a draft, then parallel critics against it before anything is presented.
• /riprap:prune — prunes merged and stale branches and triages quiet pull requests. Reports the whole plan first and never deletes, merges or closes without per-action confirmation.
• /riprap:release — cuts a release: green checks, a confirmed version, notes drafted from what actually merged, the tag on the merged commit, and a final check that the release exists. A green pipeline is not a finished release.
• /riprap:review — reviews a branch or a pull request, yours or someone else’s, across at least six angles including simplicity, maintainability and dependency creep. Posts inline comments on the lines they concern plus a summary carrying every finding, its class and a recommended fix, and closes with an explicit merge verdict against a named commit. It reports and never edits or merges.
• /riprap:vet — drives /riprap:review and the fixes it asks for through a bounded number of cycles, keeping review and remediation in separate turns so the separation the review skill depends on still holds. Pushes between cycles, because a review reads the pull request and an unpushed fix is invisible to it. Stops when the findings stop, when one survives three cycles and is therefore not converging, or at the cycle cap — then hands over. It never merges. Expensive: on the order of twenty agents and over an hour for one pull request, because every cycle fans the review angles out into their own contexts. A deliberate choice for a change worth that, not a default.
• /riprap:write — reviews or rewrites a document, plan, pull request body or README against riprap’s writing standard, and carries the full Google developer documentation style guide as reference: the word list, punctuation, tables, code and UI formatting. It edits prose and never changes behaviour.
• /riprap:handoff — writes the document that carries work across a lost context, and resumes from one. Goal, plan, what is done, what is next, what done means, how to resume: one document per unit of work, rewritten in place rather than appended to. Three hooks trigger it, because the moment the context runs out is the one moment there is no turn left in which to write anything.

Fuller descriptions, and what each one costs you in context, are on what riprap tells the model. How the five that carry a feature from a stakeholder ask to a published release chain together — what each hands the next, and where “deploy” fits — is on the feature cycle.

The agent

Namespaced the same way skills are, and discovered the same way: nothing to configure, nothing to install separately.

• riprap:agent — a generic role-based worker, for dispatching a task tagged with a role (architect, developer, reviewer, release) without naming the skill directly. It maps the role to the matching skill and follows that skill’s process exactly. For release, it also checks for in-flight pull requests first, and never performs the skill’s own two human-only acts — merging the version-bump pull request, or running the publish step.

What is enforced

Twelve hooks are registered, six of which can stop a tool call. The table naming each one, what triggers it and whether it blocks is on guardrail architecture, rather than repeated here.

What lands in your repository

Only these files, and nothing else in your project is touched.

Everything under bin/hooks/riprap/ and bin/riprap is riprap’s: refreshed wholesale on every install, and files riprap stops shipping are pruned rather than left running. The rest is yours from the moment it lands.

MANIFEST is the allowlist of record. The installer copies only what it names and refuses anything else, rather than copying whatever happens to sit in the payload directory. A recursive copy will carry a .pyc, a .DS_Store, or an editor backup into someone else’s public repository, and a compiled artifact embeds absolute source paths that no text scrubber can see inside.

The commands

• Installing riprap — the three commands, and what lands where
• Guardrail architecture — what is enforced, and how a rule is made to hold
• What riprap tells the model — the rules, and what they cost you in context
• Source on GitHub