r3vs

using-the-ledger

Use the shared decisions ledger correctly from any task — read pins, add a finding, run the compressed interview, record a decision with flip_criteria, and never let an agent commit a decision the human did not elect. The spine both codebase-rescue and greenfield-forge run on.

branch-lifecycle

Run work on a branch or git worktree from start to finish — branch per scope, commit against pins, keep parallel agents from colliding, and finish cleanly. Makes the executor's "one scope at a time" enforceable by giving each scope its own tree. Use when starting a unit of work, running agents in parallel, or finishing a development branch.

Code & Development Listed

code-review

Review a change against the contract it claims to satisfy, and reopen rather than decide — a reviewer surfaces findings as pins, never elects the fix. Covers requesting a review, giving one, and receiving one without deferring to authority. Use before merging, when asked to review a diff or PR, or when responding to review feedback.

learning-layer

Close the operator gap, not just the codebase gap — a thin coaching layer that lets a less-expert developer reach senior-grade output on the existing workflow WHILE learning from it. Use it over codebase-rescue, greenfield-forge, or any spec→plan→test→review flow when the user wants to level up as they work, onboard onto a codebase, "learn while shipping", "explain why, not just what", or be coached rather than handed answers. Delivery is never blocked by teaching; the teaching is a passive, opt-out byproduct that fades as the user improves. Not a tutorial generator and not a separate "learn mode" — it wraps real work.

project-memory

Maintain durable, cross-session project memory — conventions, gotchas, "why" notes, user preferences, and the decisions that shaped the codebase. Use to record something worth remembering, or to recall project context at the start of a task. Complements the decisions ledger (which is decision-memory) with lighter project facts.

Code & Development Listed

systematic-debugging

Find a bug by narrowing a hypothesis against evidence instead of guessing at fixes — reproduce, isolate, prove the cause, fix, then prove the fix. Binds to the decisions ledger as a defect pin so the root cause is recorded, not just the patch. Use when something is broken, a test fails mysteriously, or behavior differs between environments.

Testing & QA Listed

test-driven-development

Write the failing test first, then the code that passes it — with the red step recorded as an acceptance_criterion pin in the decisions ledger, so what the test proves is the same object the interview elected. Use when implementing any BuildItem, fixing a defect, or when asked to add tests to existing code.

verification-before-completion

Prove a change works by exercising it before calling it done — run the thing, observe the behavior, and only then move a pin to resolved. Distinguishes "the tests pass" from "the feature works". Use before claiming any task complete, closing a defect, or reporting a result to the user.

grounded-research

Answer a library / framework / API or architecture question with CURRENT, cited sources instead of stale training memory. Escalates local → Context7 docs → DeepWiki exemplars → web, tags confidence by source, and treats external content as untrusted input. Use before generating code against a dependency or deciding a stack.

Code & Development Listed

static-first-analysis

Use the strongest deterministic static signal before model judgment, and in-loop on the diff — type-checkers/compilers, LSP/SCIP navigation, and architecture-fitness / dependency-constraint checks. Deterministic findings carry high confidence and skip the false-positive gate. Use when analyzing, refactoring, or validating code.

writing-skills

Author or edit a skill in this package correctly — the Agent Skills spec frontmatter, the references/core path convention, keeping the drift-linter and roster parity green, and staying agent-agnostic (Claude Code + opencode + AGENTS.md). Use when adding, renaming, or editing a skill, module, or agent.

Data & Documents Listed

codebase-rescue

Rescue and elevate a whole codebase — especially large AI-generated / "vibecoded" ones — by reconciling backend, frontend, and database into an aligned, state-of-the-art state. Use this whenever the user wants to audit, rescue, resume, clean up, or "save" a codebase; whenever they mention slop code, a messy/abandoned/half-finished project, layers that are not aligned or contradict each other, or turning a prototype into something production-grade. Trigger even when the user only says things like "review my whole app", "the frontend and backend don't match", "pick up where I left off", "this codebase is a mess", or "make this production-ready" — do not wait for the word "audit". Prefer this skill over ad-hoc file reading or generic security review for anything that spans multiple layers or the codebase as a whole.

greenfield-forge

Start a NEW project the right way — turn an idea into an aligned, intentional, state-of-the-art codebase so it never needs rescuing. Use this whenever the user is beginning something from scratch: "I want to build X", a new app / SaaS / service / CLI, a "greenfield" project, "design the architecture before I code", "scaffold a new codebase", "set this up properly from day one", or "help me decide the stack / data model / API". It elects the to-be (the design) in a compressed decision interview BEFORE any code exists, defines the cross-layer contract once and generates aligned layers from it, then builds thin vertical slices test-first. Prefer this over ad-hoc scaffolding or jumping straight to code for anything that will outlive a throwaway script. Its sibling `codebase-rescue` handles the opposite end — cleaning up an existing mess.

run-workflow

Run a deterministic, parallel workflow over the codebase — fan out many read-only sub-agents, verify adversarially, and surface findings as ledger pins. Use for codebase-wide finding/audit (rescue Phase-1), multi-perspective review, or any task too broad for one context window. The engine is pure and journaled (replayable); YOU write the results to the ledger.