🪨 benitogf.github.io/detritus — what detritus does, at a glance: the knowledge base, code intelligence, candyland, and the delivery pipeline.
Detritus is an MCP server for AI coding assistants. It exposes a curated
knowledge base of engineering doctrine (kb_* tools) and live codebase
exploration (code_*) — and layers
on slash commands that share one delivery pipeline: plan, build,
review-with-rework, deliver. Those commands run either in your session (/plan,
/smith, /forge, /janitor, /gh-*, /todo, …) or hand off to the
out-of-process candyland sidecar for multi-agent, dashboard-observable
delivery (/candyland, /quest). No flow merges on
its own — the human merge stays the gate.
Install
Ask your AI coding tool to install Detritus from this repository:
That is the human install path. You should not need to run Detritus as a CLI
tool yourself. Manual install details for an assistant or maintainer live in
INSTALL.md.
Commands
Use Detritus by command name. This table is generated from docs/flows/ (run
detritus --readme); the folder a doc lives in is its category. Internal
building blocks (docs/core/), agent roles (docs/roles/), and reference
material (docs/ooo/, docs/patterns/) are kb_get-only and intentionally
absent — they are not commands.
Plan
Command
Use it for
/plan
Analyze requirements/feedback, create implementation plan, provide insights and questions
/vibe
Executive intake for autonomous delivery.
Build & maintain
Command
Use it for
/candyland
Launch ONE candyland run in the sidecar — a tech-lead agent partitions the work, coders build it concurrently in worktrees, a reviewer loops fix→re-review until clean, then the run delivers.
/forge
Drive a settled plan to a PR with a parallel tech-lead + coders implementation loop, in-process.
/janitor
Create a recurring proactive code-maintenance worker that audits, safely fixes, verifies, self-reviews, and routes delivery through /gh.
/quest
The one flexible, persistent iterative loop in the candyland sidecar — a quest-lead ticks discover→triage→launch serial child runs against an objective + scope lens, with two delivery modes (converge-until-clean → one PR per impacted repo; per-finding → one PR per accepted finding).
/smith
Recurring loop that takes a feature from /plan all the way to an open PR — the in-session single-agent instantiation of the universal pipeline.
GitHub
Command
Use it for
/babysit
Watch a single PR on an interval — fix any review feedback via /gh-feedback-work, and merge once an approval lands on the latest commit.
/caregiver
Watch a single PR from the reviewer's seat — re-review on each push or discussion by dispatching the one-shot /gh-pr, re-posting a commit-pinned verdict only when it materially changes, until the PR is merged or closed.
/gh
Router for GitHub issue/PR workflows — reads conversation context and dispatches to gh-issue-create, gh-issue-work, gh-feedback-work, gh-self-review, gh-pr, and the PR-watch loops babysit and caregiver.
/gh-feedback-work
Address open review feedback on a PR, push fixes, and update the PR body in place — never posts issue/PR comments.
/gh-issue-create
Draft a GitHub issue from the current conversation, confirm with the user unless the post was already directed, post it with the Claude Code attribution footer, then offer next steps (/gh-issue-work, refine, or leave).
/gh-issue-work
Take a GitHub issue end-to-end — branch, fix, test, commit, push, self-review the diff, confirm with the user unless opening the PR was already directed, then open PR with a product-focused summary and the Claude Code attribution footer.
/gh-pr
Hard-review a GitHub PR under truthseeker rigor — verify the PR's own claims, hunt for fragility, demand evidence before flagging OR approving, and post an APPROVE or REQUEST_CHANGES review via gh api.
/gh-pr-safe
Hard-review a posted GitHub PR with the same truthseeker rigor as /gh-pr and auto-post an APPROVE or REQUEST_CHANGES review, but never mutate the working tree of the clone it runs from.
/gh-self-review
Deep self-audit of pending local changes (committed + uncommitted) under truthseeker rigor before commit/push/PR.
Project
Command
Use it for
/checkpoint
Durable per-topic session context — serialize load-bearing state to .checkpoint/.md at a boundary so a /clear is lossless and a later session (hours or weeks on) resumes the topic by name.
/code
Explicit entry point for code exploration backed by the zero-setup code_* tools (code_map, code_outline, code_graph) plus native Grep.
/settings
Show or change global detritus settings — the model and effort the generated reviewer and coder agents run on.
/todo
Cross-session todo management — router, conventions, and ALL everyday item operations (view, add, done, edit, defer, clear, file) in one doc.
Testing
Command
Use it for
/flaky-check
Flaky test detection - manually-driven batches of -race runs that PRESERVE full failure logs, reproduce faithfully, and account for cross-test/ordering flakes
/testing
Testing index - entry point for all testing workflows
E2E testing - consolidated tests covering full state lifecycles
/testing-go-backend-mock
Mock testing - minimal mocking at boundaries, simple state toggles
Principles & style
Command
Use it for
/coding-style
Self-documenting code - naming, extraction, readability rules for AI
/go-modern
Modern Go patterns - auto-fix with gopls modernize after Go edits
/line-of-sight
Line-of-sight code style - flat code, early returns, separate error handling from business logic
/truthseeker
Foundational principles - ALWAYS ACTIVE, do not invoke
Maintainer
Command
Use it for
/absorb
Close the learning loop on a shipped PR - resolve its candyland unit, fix outstanding blockers, and distill the review outcome into the KB
/cleanup-extra-rules
Remove all detritus-generated rule files, hook scripts, and the matching settings.json hook entries.
/detritus-release
Cut a release of detritus and/or candyland (bump → annotated tag → CI build), then update the local installation.
/detritus-update
Update detritus to the latest released version by running detritus --update.
/grow
Learn from conversation corrections - distill manual fixes into KB updates
/learn
Learn from candyland telemetry - mine failure signatures across runs/quests into audited KB updates
/optimize
Re-index and optimize KB docs for agent retrieval efficiency
/setup-extra-rules
Generate personalized Claude Code rule files and hook scripts based on the user's actual environment.
/setup-superpowers
Apply baseline Claude Code settings (deny list, status line, effort/thinking, autoMode environment).
Pdf
Command
Use it for
/pdf
Generate a PDF to whatever format and style the user describes — general-purpose, multi-page, diagrams when useful.
/pdf-management
Turn the issue under discussion into a single-page decision PDF for a non-technical stakeholder — premise-only, plain real-world terms, no jargon, no component names or technical mechanisms.
/pdf-tech
Turn the issue under discussion into a single-page decision PDF at a bare-minimum, high-level technical register — name the component and mechanism conceptually, no code or deep internals.
