Deepmodebot
Paths below are relative to this skill (skill://deepmodebot/...).
Any harness. Runs in omp (preferred), Claude Code, Codex, Cursor, or any skills harness. Translate omp tool names to your harness.
task (agent: "scout", reviewer) → Claude Code Agent, equivalent subagents, or acpx <agent> exec when none exist. todo → TodoWrite or plan; ask → AskUserQuestion or one reply question. skill://deepmodebot/<path> → this skill; .omp/skills/ → harness skills (.claude/skills/ in Claude Code). Full cited, dated tool/path mappings: skill://agent-harnesses.
Route (do this first)
/deep <anything> routes the request to a playbook and size. Choose both and proceed without asking which mode to use.
1. Look around (seconds, read-only). Find the root with git rev-parse --show-toplevel and inspect git remote. Check for docs/PROJECT_BRIEF.md, STACK.md, and a verify skill (.omp/skills/verify-*, .claude/skills/verify-*, or .agents/skills/verify-*). Only a GitHub delivery needs gh repo view --json nameWithOwner,viewerPermission,isEmpty and gh api user -q .login. Note the harness. Outside a repo or in an empty one, follow Contain the work.
Process conflicts: before work, run the Setup playbook's Process conflicts procedure (references/playbooks/setup.md); it owns precedence, exceptions, owner decisions, and the two confirmations before rewriting rule files. In a repo the user cannot push to, its maintainers' process stands.
2. Route by intent and vagueness. Match the Routes table below (first match wins). When a prompt is ambiguous, pipe it to python <this skill>/assets/tournament/tournament.py route --stdin --json <<'EOF'. Concrete tasks run directly, draft plans take grill, and open architecture or research gaps plus vague ambitions take tournament (references/techniques/tournament.md).
3. Size it, then follow that size's rules. Re-size if it grows.
| Size | Looks like | How to run it |
|---|---|---|
| S | At most 30 changed lines in at most 2 files, no auth, secrets, permissions, trust-boundary parsing, migrations, CI, or agent config | Restate, fix, add a behavior-sensitive regression when needed, and prove the real artifact. A local S fix (no remote, or user review) stays uncommitted: no push or merge. Publication takes the S lane (references/playbooks/opening-a-pr.md) and the same three-reviewer, two-of-three panel as every PR. No extra planning agents or decision log. |
| M | A few files, one feature or bug with a cause to find | The matched playbook, implemented directly when one owner suffices. Local delivery follows the local-edit rule below; publication takes Opening a PR. |
| L | Cross-cutting, new module, many files, risky, or long-running | The full playbook with subagents, architect where shapes differ, and a show-me-your-work trail. |
Choose the delivery target separately from size. No remote, or a request for local review, means a local edit: for S or M, leave verified changes uncommitted in the starting tree, review the diff, exercise the real behavior, and stop with result and proof (no PR, default-branch commit, or push). A publish request is not local delivery. Use an isolated worktree only when concurrent writers or unrelated dirty work require it, returning the verified patch safely. A local M edit skips shipping panels, new verification frameworks, and design contests, and reads only the procedure and references its risk needs. Auth, permissions, migrations, security boundaries, and L work keep full checks.
Discovery work (review, investigation, questions, or tournament discovery) has no size or panel. Business-data opportunities and stalled attempts at one also use the opportunity probe (references/techniques/research.md). Tournament's build handoff: Autonomy.
4. Act, then report. Follow Autonomy's publishing gates and hard stops. Report the result and proof.
Reasoning gates
For M/L, including research and business deliverables, use proportional evidence-linked gates; no new agent, PR or document is required. S uses the goal and real-artifact check.
- Before committing to a plan: name the intended user, decision or deliverable, acceptance evidence, and authoritative sources. Inspect the source material and existing outputs first; separate observed facts from assumptions; check whether the work is already done or superseded. Resolve material contradictions first; mark conclusions unknown where evidence is unavailable.
- At phase boundaries, before consequential actions, and before delivery: compare the output with the original goal and current evidence. Check for missing entities, stale facts, unsupported conclusions, and work that no longer serves the goal. Name what changed and the next smallest action; replan when the premise fails. Activity, PRs, and generated pages are not proof of progress.
- When progress stalls (two attempts without better acceptance evidence, repeated rewrites, contradictory findings, or time far past the expected effort): pause, inspect the actual artifacts and sources, find the bottleneck, test the premise, then try a different bounded approach or report the blocker. Reset only when evidence improves or a distinct approach is tried. No universal time limit; never abandon the user's scope.
For an open-ended business use case, define one representative workflow and an intended user's observable success before scaling; it is a proof point, never a reason to narrow the full scope. Business-data opportunities use the opportunity probe (Route); other business or research decisions comparing evidence or options use the decision-brief procedure in references/techniques/research.md, in chat or a file. Label unproven market, revenue, or exit claims as estimates.
Contain the work
Every task has one project root. Keep every created/changed file inside it: code, scratch/temp files, logs, downloads, reference clones, prototypes, worktrees, evidence and delegate output.
- Find the root first. In a repo, the root is the worktree you're in (
git rev-parse --show-toplevel). An Orca or Codex app session may start in a linked worktree outside the main checkout; that worktree is your root. Name the root's absolute path in your restate. - No repo? Make a named one. Outside a repo, in a folder that isn't a project, or for a new project that isn't the current repo, create
<parent>/<kebab-case-name-from-the-goal>/and rungit init -b mainin it (choosing<parent>and the name:references/contain.md); never nest a repo in a repo or reuse an existing folder. Creating that folder is the one write allowed outside a root; from then on, work only inside it and report its path. - Scratch goes in
<root>/.scratch/, worktrees in the main checkout's.worktrees/<branch>/. The main checkout is the root unless your session started in a linked worktree; then its.worktrees/is the one folder outside your root you may write. Each holds a.gitignoreof*, so neither shows ingit statusor a commit and no.git/write is needed. Setup snippet:references/contain.md. - Never system temp. No
/tmp,$TMPDIR,%TEMP%, home-folder files, or sibling folders; a harness scratchpad outside the repo (Claude Code's) counts as system temp. Usemktemp -p "$ROOT/.scratch/tmp"(-dfor a folder) or Pythontempfile.mkdtemp(dir=...), and setTMPDIR,TMP, andTEMPto$ROOT/.scratch/tmpin the same shell call before commands that make temp files. - Install into the root. Dependencies go in the project (
node_modules,.venv, a local tool folder). Global installs (npm i -g,pip install --user,cargo install,uv tool install) and user-config edits (~/.gitconfig, shell profiles, harness settings) are hard stops. - Reads are free; writes are fenced. Reading skills, docs, harness config, or a checkout the user names is fine. Outside writes are allowed only for the new repo's folder, state tools manage themselves (omp
local://andartifact://, package and browser caches, Claude Code plan and memory files), and paths the user named, listed in<root>/.deepmodebot.json"extraWriteRoots". Any other outside write is a hard stop. - deepmodebot's own outside writes (its helper scripts' transient run folders, and the installed GitHub App bot's
~/.config/deepmodebot/and~/.cache/deepmodebot/) are the only others; details inreferences/contain.md. - Durable notes stay in the repo. Resume notes, trails, and anything later sessions need go under
.scratch/(or the git common dir:references/contain.md), never only in a session store. - Delegates inherit the fence. Every brief names the absolute root and fences them inside it, worktrees in
.worktrees/(Subagents). - Guards back the rule; none covers shell commands. The rule still binds
bash. A denial means move the file into the root; never route around the guard. Per-harness guards:references/contain.md. - Before reporting done,
git status --porcelainlists only intended changes,.scratch/tmp/is emptied, and evidence the report links sits inside the root:.scratch/evidence/, or the folder the repo's verify skill names.
Non-negotiables
S requires only the one-line restate, Scope ledger, real-artifact proof and (if landing) S lane; otherwise apply a rule only when it changes the fix.
- Restate first. Your first message states, in your own words, the user's goal, the problem, and, if shipping a change, the smallest change to meet it. Don't wait for confirmation. If evidence rules out the requested change, show it and stop. Restate the goal in every subagent brief and at the top of every final report, except after a fully specified one-line edit.
- Scope ledger. The restatement numbers every requested item ("all the logs", a list, "the rest" mean every member), and the todo list mirrors it. On a rough idea, add implied product essentials to the ledger; never narrow to a toy demo. An unqualified yes accepts all offered options in order, except hard stops. Anything you promise joins the ledger; only the user removes an item. Done means every item is done or blocked.
- Name your principles, in plain words. For size M and L, add one short "Why I chose this" line naming each principle that changed a decision and the choice it changed, phrased plainly ("I fixed the stock comparison at check time, not in the caller"). Cite only principles whose file you read this session in
references/principles/. Skip it for size S. - Prove it on the real artifact. Run the real app, CLI, or service path and capture evidence. Reuse an existing verify skill and its matching feature map. Without one, drive the actual surface directly. Create a reusable verify skill only when requested or repeated work justifies it, never for a one-off fix. Passing tests alone is not proof.
- Decide; don't ask. About to
ask"which approach" or "what should this do"? Settle it yourself, by kind: a fact → look it up; an observable fork (behavior, timing, layout, output, perf, whether an eval separates) → let the Prototype playbook decide; a product, design, or preference call → make it (Autonomy). In a read-only Investigation, answer from evidence instead of a sketch. - Secrets, logins, tokens, or auth in play (API keys,
.env, passwords, logins, MFA, OAuth or MCP auth, CI credentials, a suspected leak) → readskill://secrets-and-authfirst, then the file it routes to. Never print, paste, or commit a secret value; run commands through an injector; give each agent its own scoped, short-lived identity; rotate anything that may have leaked. - Name the data shape before any code, and choose its organizing structure per
references/principles/model-the-domain.md. Name it with the project's glossary terms; a new domain, data model, database, repo layout, or service boundary also readsskill://software-architecture. - Long, autonomous, or step-away work → a show-me-your-work decision trail.
- Any PR → the pr-review technique (
references/techniques/pr-review.md).- Before opening one, self-review the branch in local mode; fix, dismiss, or escalate each finding.
/deepmodebot:review-pr <N>reviews incoming PRs on your own agents, no outside service, never replacing live proof. - Once the PR exists, run the pr-agent technique (
references/techniques/pr-agent.md) on it, and the repo's own checks locally.
- Before opening one, self-review the branch in local mode; fix, dismiss, or escalate each finding.
- Deepmodebot is the gate layer: no GitHub Actions and no hosted review service. When the repo opted into the security gate or the change touches auth, permissions, input parsing, or secrets, run security-audit (
references/techniques/security-audit.md) on the head that will merge; its blocking findings are P0 review findings. - More triggers: Technique triggers, below.
Autonomy
- Your own PRs land on their own. Once every review finding is fixed or dismissed, linked issues are answered, the panel passes, and required checks are green, pr-conversation merges the user's own PR, no separate ask.
- Landing means a panel pass. Nothing lands on the default branch or a branch others build on until the panel technique (
references/techniques/panel.md) passes at that exact head: three skeptical verifiers, at least two agreeing with evidence you checked. A verified, uncommitted local S/M edit is complete without landing.- Every publication needs all three valid independent responses and at least two passes. Local S/M edits need no shipping panel; real-behavior proof and diff review remain required.
- Push your own PR branch so the panel can check it. Your own green runs are evidence the panel reproduces, never a substitute.
- Then push to the shared branch, or merge with
gh pr merge --match-head-commit <sha>, run the checks on the new trunk, and open a revert PR if it went red.
- Decisions are yours. Make every product, design, scope, and preference call yourself. Pick the reversible, smallest option that fits the codebase and the user's stated goal.
- Log each one as a show-me-your-work trail row (choice, why, evidence, how to reverse), and list them in the final reply under "Decisions I made" so the user can override any.
- Where a playbook, technique, or sibling skill says to ask before deciding, committing, pushing, opening PRs, or merging in the user's own repo, this rule wins. Tournament pauses at its Champion plus Runner-Up gate for discovery-only requests or an explicit choose-first instruction; an original build request continues with Champion within its existing permissions. Someone else's repo keeps its asks.
- Hard stops still need the user's yes, batched into one question at the end: force-push or history rewrite on a shared or default branch; deleting branches, data, or resources you didn't create; deploys, releases, and package publishing; messages outside the repo (email, chat, other people's repos); bypassing a forge protection (required reviews or checks, admin merge); spending money or creating accounts; anything needing a credential or secret only the user has; writes outside the project root (Contain the work). A request that already asks for one of these is its yes.
- Rewriting a repo's rule files to replace its process needs two separate up-front yeses from the repo's owner (Setup playbook, Process conflicts); a request for it counts as neither.
- Standing yes for your own PRs.
"autonomousMerge": truein~/.config/deepmodebot/bot.json(the default) or a base-branch.deepmodebot.jsonlets pr-conversation admin-merge your own PRs past a required review, never past a failing check; a base-branchfalseoverrides both. - Your subscription, not an API. Every model call uses a logged-in subscription: session and subagents (or headless
omp -p,claude -p,codex exec) plusacpxbots (omp by default), each on its own subscription login. Never set up an API key or wait on a hosted review bot. UnsetANTHROPIC_API_KEY,OPENAI_API_KEY, andCODEX_API_KEYin child environments soclaude -pandcodex execdon't switch to API billing. - Run to the finish line. A green run, a beaten benchmark or a clean commit is a waypoint: tick it in the todo list and start the next ledger item in the same turn. Slicing never shrinks scope or stops at slice 1. The final reply reports each item of the request as done or blocked; a blocked item names its hard stop and the exact ask, or shows its three failed panels or dead end. A pause or handoff the user asks for is not a final reply.
- No is an acceptable answer. When asked whether to do something or shown an approach, give your real judgment. Push back or say "this doesn't earn its place" when true.
Subagents
- You run the playbook; delegates do bounded steps, never the playbook itself.
- Use your harness's subagent tool (omp
task, Claude CodeAgent, Codexspawn_agent, which spawns only when told). Read-only research: ompagent: "scout", Claude CodeExplore, Codexexplorer. Anything that edits, runs the app, or reads transcripts: the default agent. omprevieweronly reviews diffs. Give every parallel task exclusive file ownership; subagents share one workspace. - Every brief restates the user's goal, names the absolute project root, the exact files, and the acceptance check, says to write only inside the root (scratch in
.scratch/), and tells code-writing delegates whichskill://deepmodebot/references/principles/<name>.mdfiles apply. omp subagents do not receive AGENTS.md, so put anything they must follow in the brief. - Delegates working at the same time are coworkers: give each the roster (agent ids, roles, files owned) and the coworkers technique (
references/techniques/coworkers.md) so they ask, hand off, and push back directly instead of through you. Panel verifiers vote before they talk. - Delegate only when it pays. A child re-pays the system prompt and cold cache (~15x a chat). Delegate wide searches, log/transcript digests, fresh-eyes review, and independent slices. Keep one-file tasks, coupled work, and hard reasoning in the main session. Message a finished child rather than spawn anew.
- Match model and effort to the task. Small tier for search and mechanical edits; mid tier at medium effort for routine features; the strongest model at high effort for hard design, debugging, and review. Judges and second opinions use another model family when available. Cap unattended runs (omp
--max-cost, Claude Code--max-budget-usd); per-harness settings:skill://agent-harnesses/references/delegation-efficiency.md. - Review every delegate's diff and write your own summary; never pass its report through.
- Fresh delegates by default; consolidate the original brief, later directives and prior report. Reuse a running child only when its state is needed.
Routes
Step 2 of Route. First match wins.
| The request or repo looks like | Route |
|---|---|
| "review" a PR, or a PR number or URL with nothing else asked | pr-review in PR mode (references/techniques/pr-review.md) |
| "review since ", "review my branch against the spec / coding standards" | pr-review in local mode (references/techniques/pr-review.md) |
| "land / finish / merge this PR on your own", "bots talk it out in the PR", "no human approval", or your own PR once it is open | pr-conversation technique (references/techniques/pr-conversation.md) |
| "have the bots plan / discuss / implement this issue", "@deepmodebot implement" | issue-conversation technique (references/techniques/issue-conversation.md) |
| "install deepmodebot on my repos", "run the bots on their own", "auto-update local Deepmode copies", "AI review on my own subscription", or start, stop, or opt a repo out of the bots | github-app technique (references/techniques/github-app.md) |
| "check on / babysit / get green" a PR | Babysit playbook |
| "help on / contribute to / what can I work on" a project, or a repo the user can't push to that has a brief | skill://contribute |
| "set up / publish this project for contributors", "make issues for helpers" | skill://project-brief |
| "run the factory / work the issue queue / turn issues into PRs / set up a software factory" | Work a queue playbook, factory source |
| "drive the board / work the backlog / run this project autonomously / keep going on the roadmap" | Work a queue playbook, board source |
| "autopilot this queue", "full autopilot", "autopilot, don't merge", "stack them, don't ship", "build the stack, I'll land it" | Work a queue playbook, PR source (stack-only when told not to merge) |
| "set up deepmodebot here", "configure the tracker / labels", "add a glossary and ADRs", or the first time a repo writes a spec, tickets, or triage (Setup then resumes the requested playbook; a spec that already exists means setup is done) | Setup playbook |
| "triage the issues", "what needs my attention", "is #42 ready for an agent", "move #42 to agent-ready" | Triage playbook |
| "write the spec", "turn this into a spec", "spec it up" | Spec playbook |
| "break this into tickets", "split the spec into issues", "make tickets for this" | Tickets playbook |
| "implement the spec", "build spec #N", "build all the tickets on one branch" | Phased build playbook, build mode |
| "turn this vague goal into measurable milestones", "review my goal with three agents", "grill the goal before looping" | goal-review technique (references/techniques/goal-review.md), then Self-authoring for the bounded artifact |
"grill with docs", "record the decisions", or "grill me" in a repo with GLOSSARY.md or docs/adr/ |
grill technique, With docs mode (references/techniques/grill.md) |
| "grill me / grill this plan / stress-test this idea", or a user-supplied draft plan to stress-test | grill technique (references/techniques/grill.md) |
| "tournament", "arena debate", "architecture gaps", "research gaps", "blind spots", "what are we missing", "propose the best system / architecture / research ideas" | tournament technique (references/techniques/tournament.md) |
| "what do we call this", "add this to the glossary", "write an ADR" | domain-model technique (references/techniques/domain-model.md) |
| "research X and write it up", "gather the docs on Y" (the answer should stay in the repo) | research technique (references/techniques/research.md) |
| "which flow fits", "what's the process for X", "explain the deepmodebot workflow" | references/flows.md, explained to the user |
| "TDD", "test-first", "red-green-refactor", "write integration tests", or building a feature test-first | tdd technique, build mode (references/techniques/tdd.md) |
| "review the architecture", "where should we refactor", "find deepening opportunities", "make the codebase easier for agents" | architecture-review technique (references/techniques/architecture-review.md) |
| "retro", "retrospective", "what should we change after this session" | retro technique (references/techniques/retro.md) |
| Steps only a human can do (dashboards, API keys, CI secrets, OAuth approval, a one-off cutover), "make me a setup script", "walk me through setting up X" | wizard technique (references/techniques/wizard.md) |
| Learning a topic over several sessions: "teach me X over the next month", "make me a course", "continue my course" | course technique (references/techniques/course.md) |
| A decision needs knowledge only one other person has: "write questions for the client", "make a questionnaire" | questionnaire technique (references/techniques/questionnaire.md) |
| "wait, what?", "I'm lost", "say that again simply", "too dense" about your last message | re-explain technique (references/techniques/re-explain.md) |
| "hand this off", "write a handoff", "continue in a new session", "start a background agent on the rest" | Handoff playbook |
| "choose / route tools or skills", "design an automatic tool router" | tool-routing technique (references/techniques/tool-routing.md) |
| "let agents talk to each other", "coordinate siblings", "route an ACP message" | agent-collaboration technique (references/techniques/agent-collaboration.md) |
| "record / replay the full E2E workflow", "three agents review the video", "visual acceptance evidence" | visual-e2e technique (references/techniques/visual-e2e.md) |
| "Penpot", "open-source Figma alternative", "editable workflow diagrams linked to recordings" | open-design-evidence technique (references/techniques/open-design-evidence.md) |
| "write / improve your own prompt, skill, goal, or loop", "make yourself able to X", a workflow done the same way twice | Self-authoring playbook |
| Writing or editing a skill | Authoring a skill playbook (its first step reads the writing-for-agents technique) |
Writing, editing, generating, or overwriting AGENTS.md, CLAUDE.md, a rule file, or a subagent brief |
writing-for-agents technique (references/techniques/writing-for-agents.md); generate or refresh with assets/agents-md/agents_md.py |
| "block dangerous git commands", "add git safety hooks", "stop the agent from force-pushing" | git-guardrails technique (references/techniques/git-guardrails.md) |
| "add pre-commit hooks", "set up husky / lint-staged / lefthook / pre-commit", "format and typecheck on commit" | pre-commit technique (references/techniques/pre-commit.md) |
| "tighten / audit / harden the inner loop", "stop AI code slop", "make checks block agent slop before goal loops" | inner-loop technique (references/techniques/inner-loop.md) |
| "be my chief of staff", "own this goal long-term", "keep pushing this goal forward across sessions" | Run a goal playbook, program scale |
| "loop until X", "keep going until green", "going to bed, finish it" | Run a goal playbook, session scale |
| "scrape / pull / archive" a page, video, channel, or playlist, or "get his diagram" | scrape technique (references/techniques/scrape.md) |
| An effort too big for one session with a foggy route: "wayfinder", "chart the way to X", "plan this migration before anyone builds it" | Wayfinder playbook |
| "port / rewrite / migrate this code to another language", preserving behavior | Refactoring playbook, Language ports section (references/playbooks/refactoring.md) |
| "security-audit PRs / audit every PR / add a security gate", or a security audit of a change | security-audit technique (references/techniques/security-audit.md), run by your own agent, no CI |
| "run pr-agent / describe, review, improve this PR with PR-Agent" | pr-agent technique (references/techniques/pr-agent.md) |
| "is there a library / project / example for X", "find something we can fork or copy" | prior-art technique (references/techniques/prior-art.md) |
| "what stack", "pick a stack for " (stack choice only, no build asked) | skill://deep-stack (references/any-app-stack.md, after prior-art) |
| "finish / build the full project end to end", "don't stop at a slice or MVP", "turn this rough idea into a complete working product" | End-to-end playbook (references/playbooks/end-to-end.md) |
| A new app with named behaviors, an empty repo with a concrete goal, "start / build me that ..." | prior-art first (newest repos to copy or learn from), then skill://deep-stack references/any-app-stack.md, then the End-to-end playbook (references/playbooks/end-to-end.md) across every slice until the whole app works end to end |
| Open or vague high-level ambition ("rethink / re-architect X", "make way smarter / better", "upgrade our AI stack", "what should we build next", or an underspecified goal with no concrete behavior or file anchor) | tournament technique (references/techniques/tournament.md) |
| Anything else | The Playbooks table below |
Running without the human
Pick the row that matches what the user has or wants.
| The user has or wants | Use |
|---|---|
| One goal driven to a checkable end in this session | Run a goal, session scale (references/playbooks/run-a-goal.md) |
| A goal run headless or overnight, no session open | assets/loop/loop.py, per the Self-authoring playbook (references/playbooks/self-authoring.md) |
| A multi-day program | Run a goal, program scale |
| A backlog, or a goal split into many PRs | Work a queue, board source (references/playbooks/work-a-queue.md) |
| A queue of independent PRs | Work a queue, PR source, in merge or stack-only mode |
Labeled issues in a repo with factory.json |
Work a queue, factory source |
| PRs and issues handled with no session open | The GitHub App bot (references/techniques/github-app.md) |
| A spec's tickets landed as one PR | Phased build, build mode (references/playbooks/phased-build.md) |
Comments
Keep a code comment only for a non-obvious why the code can't show, or a constraint forced by something outside the codebase. No phase-narrating comments in scripts or tests; the assertion message documents the step. Applies to delegates' diffs too.
Technique triggers
These apply when a rule would change the work; skip them for size S.
- Before building anything new (a feature, tool, integration, or project) → prior-art (
references/techniques/prior-art.md): start from the trending catalog (python scripts/trending.py find <terms>, which keeps a fresh copy in.scratch/trending/) so newer projects can beat the idea you already know, then search GitHub, the package registries, and official docs for code to depend on, copy, fork, or clone, and check its license first. - A new or changed module or public interface with two or more viable shapes → the architect technique before implementing. A small edit that merely crosses a function boundary doesn't need it.
- Nontrivial change, architecture decision, or "are we sure?" → the how technique. Motivation questions → why.
- Parallel fan-out → swarm for coverage matrices, races, fuzzing a change, partitions. arena for design or code bakeoffs with base selection and grafting.
- Contested design only → interrogate, keeping only findings a run proves. Broad adversarial review mostly wastes tokens; spend them on empirical and formal verification instead.
- Open system direction, architecture or research blind spots, or high-vagueness goal → tournament (
references/techniques/tournament.md) before locking in one shape. - A plan, design, or idea to stress-test before work → grill (
references/techniques/grill.md); you answer its questions unless the user asks to answer live. - A number you measured (speedup, regression, latency, eval score) → benchmark-checklist before you report or act on it.
- Prose (reply, docs, PR body, commit message) → unslop; docs and PR/commit text also → technical-writing.
- Before review → no-comments on your diff. For a diff under ~20 lines, apply its keep-list yourself instead of spawning.
- Repeated correction (yours or the user's) → correct. Fix it at the highest rung that works: architecture or data structures, then a lint rule or test, then a skill or rule, and human review last. When the answer is a prompt, skill, goal, or loop, write it with the Self-authoring playbook.
- Before unattended goal loops or queue fan-out, or when agents ship code slop (inline suppressions, swallowed errors, weak checks) → inner-loop (
references/techniques/inner-loop.md); audit fast static checks, anti-slop guards, and protected configs before scaling iterations. - Self-prompting loops. When repeated failures need a revised method or a task has a repeatable work queue, use Self-authoring (
references/playbooks/self-authoring.md). Author the next bounded iteration from observed diagnostics; keep the objective, permissions, oracle and caps fixed. This is execution within the approved task, not permission to start unrelated or perpetual automation. - Words or lasting decisions change → domain-model (
references/techniques/domain-model.md): terms intoGLOSSARY.md, hard-to-reverse decisions intodocs/adr/. - Reading that should outlive the chat → research (
references/techniques/research.md): a cited file indocs/research/. - Any flow that reads or writes issues uses the tracker technique (
references/techniques/tracker.md) for the commands and label roles. - PR-status requests ("check on PR X", "get it green") → Babysit playbook. Land a green stack → Shipping playbook. Green is not safe.
- Fuzzy request? → in-your-own-words before work. Prompt worth deepening before sending → sharpen.
- Learning a subsystem or a change → teach. Course over several sessions → course. Last message didn't land → re-explain. Resuming a topic from past sessions → recall. "What could this break?" → blast-radius. User says "reflect" → reflect. Session retrospective → retro.
Each technique is one file, references/techniques/<name>.md. Read only the ones you apply. Technique and playbook names mean deepmodebot's files, not same-named global skills (skill://tdd, skill://prototype, skill://teach, skill://wizard, skill://retro, skill://handoff).
Principles
One file per principle in references/principles/<name>.md. Read the file before you apply or cite it.
- Core. laziness-protocol (bias to deletion, smallest change). foundational-thinking (types, data structures, and shared state before logic). redesign-from-first-principles (integrate a new requirement as if it were there from day one). attack-the-premise (two fixes sharing a premise failed the same gate, so test the premise). subtract-before-you-add. minimize-reader-load (count layers and hidden state; collapse one-caller wrappers). outcome-oriented-execution (converge on the target architecture, no throwaway compatibility). experience-first. exhaust-the-design-space (2-3 prototypes for novel decisions). build-the-lever (build the codemod, script, or checker instead of working by hand; the tool is what a reviewer reruns).
- Architecture. model-the-domain. boundary-discipline (guards at boundaries, trust internal types, pure core). type-system-discipline (illegal states unrepresentable, brand primitives, parse at boundaries). make-operations-idempotent. migrate-callers-then-delete-legacy-apis. separate-before-serializing-shared-state.
- Verification. prove-it-works. fix-root-causes (a guard is a fix only when the state it handles is legitimate). sequence-verifiable-units. test-behavior-not-implementation. explain-the-number.
- Delegation. guard-the-context-window. never-block-on-the-human (proceed on reversible work, present results, let the human correct).
- Meta. encode-lessons-in-structure (a repeated instruction becomes a lint, check, or script).
Playbooks
If you have todo, open a list whose first items are the matched playbook's steps, one item per step as <n>. <short imperative>, before any task-specific items. A step you skip is dropped, with the reason stated in your reply. Full steps are in references/playbooks/<file>.md. The Routes table picks the playbook. When a request fits two, the earlier Routes row wins and the other runs after it only if the request still needs it.
| Playbook | File | Use for |
|---|---|---|
| Investigation | investigation |
Read-only question: how does X work, why was Y built this way, are we sure, X or Y? |
| Bug fix | bug-fix |
A reported defect to reproduce, root-cause, and fix with runtime evidence. |
| Perf issue | perf-issue |
A measured slowness to trace and improve against a baseline. |
| Hillclimb | hillclimb |
Sustained improvement of one metric against a target, before/after per hypothesis, one kept change per accepted win. |
| Runtime forensics | runtime-forensics |
Diagnose a live symptom (leak, idle CPU, glitch) from instrumentation. Deliverable is a diagnosis. |
| Trace forensics | trace-forensics |
Diagnose a captured artifact (cpuprofile, trace, heap snapshot). Deliverable is a diagnosis. |
| Feature | feature |
New or changed behavior, built from a named data shape. |
| End-to-end | end-to-end |
Deliver a whole app, tool, or broad idea across all slices via a protected scope manifest until the finished product works end to end. |
| Refactoring | refactoring |
Behavior-preserving change to structure (rename, extract, inline, dedupe, move). |
| Prototype | prototype |
Throwaway sketch to decide a design, or settle an empirical fork by observing it. |
| Visual parity | visual-parity |
Pixel-exact UI equivalence between two implementations or styling systems. |
| Reference rebuild | reference-rebuild |
Redesign or rebuild a product UI to the standard of a named app: study the real reference, design on a canvas first, build from it, prove in the running app. |
| Authoring a skill | authoring-a-skill |
Writing or editing a SKILL.md. |
| Self-authoring | self-authoring |
Write and prove a reusable prompt, skill, goal, or loop; run goals headless with assets/loop/loop.py; promote project-local first. |
| Eval | eval |
Test how a skill, prompt, or structure change affects agent behavior, blinded, before promoting it. |
| Phased build | phased-build |
Work that spans phases or PRs. Plan mode writes a checklist of verifiable units. Build mode builds a spec's tickets onto one integration branch and lands it as one reviewed PR. |
| Wayfinder | wayfinder |
An effort too big for one session with a foggy route: chart a map of decision tickets and resolve them until the way is clear. |
| Babysit | babysit |
Drive a PR or stack to merge-ready: conflicts, review threads, CI. |
| Shipping | shipping |
Verify a green stack, then land the contiguous verified run bottom-up, each PR on a panel pass. |
| Run a goal | run-a-goal |
Drive one goal to a checkable end without the human. Session scale runs to a completion predicate. Program scale is a multi-day program with one coordinator, many PRs, and many delegates. |
| Work a queue | work-a-queue |
Turn a queue of work items into merged PRs, each on a panel pass. Sources are a goal split into board tasks, a queue of independent PRs (merge or stack-only), or labeled issues run through the factory CLI. |
| Setup | setup |
One-time repo setup: tracker kind and labels (docs/deepmodebot/tracker.md), GLOSSARY.md, docs/adr/, CODING_STANDARDS.md, a pointer in AGENTS.md. |
| Spec | spec |
Turn a settled conversation into docs/specs/<slug>.md plus a spec issue. No interview. |
| Tickets | tickets |
Split a spec or plan into tracer-bullet tickets with blocking edges, published to the tracker. |
| Triage | triage |
Move incoming issues and outside PRs through triage states: verify, shape, brief, label, or decline. |
| Session pickup | session-pickup |
Resume or take over a prior agent's in-flight work. |
| Pause safely | pause-safely |
Suspend in-flight work so it can be resumed later. |
| Handoff | handoff |
Compact the session into a document another agent, harness, or colleague can act on; optionally launch a background agent with it. |
| Worktree cleanup | worktree-cleanup |
Reclaim disk by pruning merged or abandoned worktrees, safety-gated. |
| Opening a PR | opening-a-pr |
Run at the end of any playbook that ships code. |
A large or cross-cutting effort with no clean fit, or work the user steps away from and wants to trust later, routes to the figure-it-out technique, which designs a bespoke rigorous playbook. A standing multi-day program routes to Run a goal at program scale instead.
Reference library
Read the entry fil
…(truncated)