ai-badger

Use when a project needs a memory server — search project and shared memory first, write durable facts with source paths, watch a docs directory, or promote facts across projects.

Use when the user wants Claude to auto-approve tool calls — "enable autonomic/autonomous work mode", "/auto-wm", "partner mode", "work by yourself for N hours", "no one will be around to approve/answer" — or to check status, switch modes, or turn it off ("awm status", "auto-wm away 4h", "auto-wm off").

Use when interacting with web pages, running manual E2E browser tests, testing UI flows, or inspecting live web surfaces via Playwright MCP. Employs text-first accessibility snapshots and element refs, network inspection, form filling, and custom Playwright script execution.

Use when ai-badger's own machinery needs to be observed — "did that hook even run?", "enable debug logging", "why is the drift notice silent?", "turn on the audit log", "what did the hooks do?" — or to check, tail, or switch off that logging. Records which hook ran, in which project, under which version, to an append-only log.

Use when reviewing code — a PR, a diff, or freshly written changes — and you want concrete pass/fail checks rather than impressions. An aviation-style preflight checklist organised into sequential phases, with stack-specific items merged in from the project's config.

Use when a project has accumulated uncommitted changes and nobody has said so out loud — several edits in a row with no commit in between — or when a subagent may be stuck and about to lose its work ("did that agent commit?", "is anything at risk?", "ensure work is committed"). A PostToolUse hook watches the live `git status --porcelain` count after every edit-shaped tool call and commands a commit once it crosses a threshold; after repeated unanswered commands it records the work as at risk, and `scripts/ensure_committed.py` reports that to a parent.

Use when a feature idea needs to become an exact, agreed specification before anyone builds it — "spec this out", "create a task spec", "turn this idea into requirements", "what exactly should we build". Interrogates the person for what they know instead of proposing content for them to approve, using Gherkin's own grammar to decide which questions must be asked and when the document is complete. Emits a .feature behavioural contract plus a spec.json manifest that the task skill consumes.

Use when an already-scaffolded project is behind the framework — a drift notice appeared, a new ai-badger version shipped, or the user asks to "refresh"/"update ai-badger". Reports what changed, backs up .ai-badger/, and re-scaffolds from the project's existing config.

Use when tests have to be designed or written for a target — "write tests for X", "add coverage here", "what should I test", a new behaviour with no test yet, a bug that needs a reproduction test, a coverage gap someone wants closed, or a bare "write some tests" with nothing named. Works with a target given or none given. Not for judging tests that already exist (review-tests) and not for diagnosing one already-flaky failure (dotnet-flaky-test-diagnosis).

Use when a feature already exists in code but has drifted from — or was never reconciled with — its intended design, and someone must decide what changes before a refactor is scoped. Triggers: two parallel implementations of the same thing, code that reads as dead but may be a ratified extension point, an architecture nobody can tell from accumulated cruft, or a refactor about to be scoped off review documents instead of decisions.

Use when something learned in this repo belongs in the ai-badger framework itself — a new skill, persona, invariant, instruction or fix that is project-agnostic — and the user wants to contribute it back. Opens a draft PR against the framework; refuses anything project-specific.

Use when a git push fails for a reason the quality gate did not cause, CI goes red on a pushed branch, or a PR moves through review and merge outside the tracked-task flow: non-fast-forward recovery with force-with-lease, CI log triage and flake attribution, draft-to-squash PR lifecycle, squash-merge conventions, and join-time conflict resolution on plain branches.

Use when writing or editing prose (documentation, blog posts, release notes, PR descriptions, emails) to strip AI writing artifacts, apply research-grounded humanization levers, and adopt a natural human voice.

Use when agent instruction files have drifted from each other or from the policy model — CLAUDE.md, copilot-instructions.md, AGENTS.md, hosted-review and path-scoped instruction files — or when validation/drift checks fail in CI. Reconciles them from the machine-readable model in .ai-badger/agent-instructions/.

Use when MCP tool selection needs help — the agent keeps picking the wrong tool, server tool definitions are bloating the prompt, or MCP servers were just added or removed. Manages .ai-badger/mcp-tools.json: tags, intent descriptions, and the hook that recommends tools per turn.

Use when a design, refactor or review document needs a per-decision ruling from one human reviewer and the answers must come back attached to the decision they belong to. Triggers: pasting a long document into chat and getting a wall of prose back, an answer that can't be matched to its question, a reviewer hand-editing answer slots in markdown, or a set of decisions that must each be approved, changed, rejected or deferred before work is scoped.

Use when a prompt starts with a marker prefix — `h:`/`hint:` (a lead to validate before acting), `f:`/`feedback:` (a correction to apply immediately), `e:`/`extension:` (a request to widen scope), `q:`/`queue:` (a queued task for after current work), `i:`/`important:` (important, high priority) or `i!:`/`important!:` (immediate emergency interrupt) — every marker also accepts a `!` importance token between alias and colon, making it interrupt-grade — or when the user asks to add, change, or inspect those markers. The UserPromptSubmit hook detects them and injects the matching behaviour.

Use when a change is small enough to skip the full task pipeline — one focused fix or small feature that fits a single commit pushed straight to main with no PR: a minimal plan, touched-surface tests only, the project's fast gates (lint, docs), one quick focused review, one commit. Escalate to `task` the moment the change outgrows that shape.

Use when tests that already exist have to be judged rather than written — "are these tests any good", "review the tests in this PR", "why did the suite stay green while that shipped", a coverage number nobody trusts, a gate nobody has watched fail, a lane that flakes, or a test file a reviewer flagged. Takes a directory, a file list, a diff, or "the tests for X"; refuses to run with no target. Returns findings, not edits.

Use when reasoning over structured project knowledge — record decisions with provenance, trace causal chains, extract entities from conversations, or run graph analytics. Complements AiRaccoon memory (recall) with structured reasoning (connections and causality).

Use when the user asks where things stand mid-task — "status", "status report", "where are we", "what's the current task", "task progress", "what's next", "subagent status", "is the delegation done" — or wants a progress snapshot while work is still running. Answers NOW from the /task tracking files: current task, progress as a checklist, what is next, and sub-agent/delegation status. Important by default: never deferred to task end, never delegated, never turned into analysis.

Use when the user wants to start, continue, or finish a backlog task — "/task <id>", "start task X", "work on the next task", "finish this task". Runs it end-to-end as a token-tracked unit of work with two effort levels (low/high), plan packaging with mandatory integration package, MoE panels for high-effort, and automated task-ID derivation ({repo-alias}-{key}). Delegates planning/review to high-reasoning models and implementation to persona-routed agents. Project specifics from .ai-badger/config.json; source-control and PR behaviour from config-gated extensions.

Use when a repository should be set up with ai-badger — "welcome-ai-badger", "scaffold this project", "add agent instructions here", "onboard this repo" — whether it is new or already has agent files. Detects stacks, writes .ai-badger/, and generates each configured agent's discovery file.