pi-badger-integration

Canonical source for pi coding-agent extensions that are not part of ai-badger (the ai-badger hooks adapter, shift-enter-newline, session-signals, pi-cron, subagent), plus the publish flow that installs them to pi's user scope and vendors the adapter back into an ai-badger checkout.

Domain: Developer tooling for coding agents - extension distribution and ai-badger/pi integration Stacks: node, ts, pi, github Scaffolded by ai-badger 0.217.0. Source of truth for this file: .ai-badger/CLAUDE.md.

Commands

• test: bun run test
• lint: bun run typecheck

Path-specific instructions

Before editing matching files, read the applicable scoped instruction file:

• docs/**/*.md,README.md,CLAUDE.md → .ai-badger/instructions/documentation.instructions.md
• **/package.json,**/bun.lock,**/*.mjs,**/*.cjs → .ai-badger/instructions/node.instructions.md
• **/*.ts,**/*.tsx,**/tsconfig.json → .ai-badger/instructions/typescript.instructions.md
• **/AGENTS.override.md,**/CLAUDE.md,.pi/** → .ai-badger/instructions/pi.instructions.md
• **/.github/workflows/*.yml,**/.github/workflows/*.yaml → .ai-badger/instructions/github-actions.instructions.md

Additional invariants load contextually via these paths — see .ai-badger/invariants/ for the full set.

Agent delegation

• architecture, repo layout and publish-flow design → architect
• pi extension implementation in TypeScript → api-engineer
• unit tests with bun test - design and review → test-engineer
• code review of extensions and the publish flow → code-reviewer
• Every dispatch names its model — the delegation map is .ai-badger/delegation.md.
• Parallel dispatches each name their own isolation — lanes sharing a tree share its build output.

Prompt markers

This project understands prompt markers (see .ai-badger/skills/prompt-markers):

• h: / hint: — a lead to validate before acting (research first).
• f: / feedback: — a high-priority correction; adjust immediately.
• e: / extension: — a request to expand the current task's scope.
• q: / queue: — a queued instruction to analyze and run after active work completes.
• i: / important: — important: high priority, do not drop it; handle at the next natural boundary.
• i!: / important!: — immediate emergency interrupt: STOP, pause/cancel active tasks, and react instantly.

A ! before the colon (f!:, queue!:) makes any marker interrupt-grade: stop and handle it before the work in flight, never queued behind it. A marker sent mid-turn skips the hook that expands it — apply it yourself.

MCP Tools: code-review-graph

This project has a knowledge graph. Reach for the code-review-graph MCP tools before Grep/Glob/Read — they cost fewer tokens and return structural context (callers, dependents, test coverage) that file scanning cannot. Start at semantic_search_nodes_tool; fall back to Grep/Glob/Read only where the graph doesn't reach. Each tool's own description covers the rest.

MCP Tools: ai-raccoon

AiRaccoon is the project memory server. Search memory FIRST — before web search, code search, or asking the user — with query (projectId, scope=all) and 2-3 query formulations. Entries carry source paths, so a decisive hit is evidence: cite it. Escalate by result — a partial hit gets one targeted external search; no hit means search externally, then write the finding back with add_memory including the source path.

Every call passes projectId. Plain writes land in committed project memory; active workspaces isolate in-progress notes and consolidate on finish; share_memory promotes durable cross-project facts. Keep the docs directory searchable: check get_watch_status, then add_watch (projectId + absolute path) when no watch exists.

MCP Tools: semantica

Semantica is the project knowledge graph. It complements AiRaccoon: AiRaccoon answers "what do we know?"; Semantica answers "how are things connected?" and "why was this decision made?".

Start with get_graph_summary for orientation. Record architectural decisions with record_decision. Drill into specifics with query_decisions, find_precedents, or get_causal_chain. Each tool's own description covers the rest.

MCP Tools: playwright

Browser automation over accessibility snapshots: browser_navigate, then browser_snapshot for element refs, then browser_click/browser_type on those refs. Each tool's own description covers the rest.

MCP Tools: task-graph

task-graph owns the decomposed task plan — a DAG of steps carrying status, acceptance criteria and evidence, persisted beside the task tracker in the project's tracking.db.

Plan time: plan_create validates and stores the DAG; plan_replace revises it before execution starts; steps_ready returns the dispatchable frontier and its waves. Execution: step_start, step_complete (evidence + AC results), step_fail, step_skip, ac_check; progress_checklist is the status view, and plan_get, step_get, plan_export read back.

No project .mcp.json (worktree sessions) → use the CLI twin task_graph_cli.py <tool> --json; Hermes operators add the proposed mcp_servers: entry to ~/.hermes/config.yaml.

Non-negotiable invariants

Each rule's full text is .ai-badger/invariants/<name>.md.

• Write to the user in Simplified Technical English (simplified-technical-english) — When you write a response, a report, a status update, a question or a hand-back to the user, use the simplified-technical-english skill.
• Announce parallel work (announce-parallel-work) — When another agent session shares the project, announce started work, opened PRs, review requests and merges on the project bus — read multi-agent-communication when parallel work is active.
• Diagrams default to Archify (archify-diagrams) — Author architecture, workflow, sequence, data-flow and lifecycle diagrams with the archify skill when it is installed.
• Ask if a simpler shape would do (ask-if-simpler) — Before calling any design or change finished, ask whether it is over-engineered and what the simpler version would look like.
• Check the source, not your own reasoning (check-sources-not-yourself) — Re-read the docs, the data and the code before stating a fact about them — those are what go stale, get misremembered, or change under you.
• Consolidated restart (consolidated-restart) — After two failed revision turns, restart the task with a single merged prompt instead of continuing the same thread and compounding drift.
• Critical instruction placement (critical-instruction-placement) — Keep the most important requirements in the first or last block of the prompt; do not bury them in the middle where they are easy to miss.
• Derive the list, or delete it (derive-or-delete-the-list) — A hand-maintained list meant to mirror something else — the gates on disk, the copies of a helper, the skills in the catalog — drifts the moment someone adds to one side and not the other, and nothing notices because nothing compares them.
• Few-shot only for format (few-shot-format-only) — Start zero-shot and use examples only when the output format is the failure mode; otherwise the task should be solvable from the specification alone.
• Final output schema separation (final-output-schema-separation) — Keep free-form reasoning separate from the final output schema and emit the schema last so the output is auditable and machine-checkable.
• Grounded feedback (grounded-feedback) — Every correction must cite failing checks, compiler output, validator output, or source evidence before proposing a new patch.
• Guard clauses over hand-rolled null checks (guard-clauses) — Prefer a dedicated guard/throw-helper for argument validation over hand-rolled x ?? throw ... or ad hoc if (x == null) throw blocks — a guard reads as intent, not boilerplate, and keeps the exception type/message consistent across the codebase.
• Measure only when the measurement pays (measure-when-it-pays) — Run your own benchmark or experiment when the time it costs is repaid by the decision it settles, and not otherwise.
• Minimal comments (minimal-comments) — Write a doc comment as the 1-3 line contract an editor shows on hover — what the thing is and how to use it — and never let a PR, issue or ticket reference appear anywhere in it.
• Let git write git's own storage (never-hand-edit-the-git-dir) — Write a git dir through git config, git remote and git branch --set-upstream-to, each of which takes the config lock and rewrites only the key it was given.
• Use platform security APIs (no-hand-rolled-crypto) — Always use the platform's built-in security and crypto APIs.
• Store secrets outside tracked files (no-hardcoded-secrets) — Keep credentials, connection strings, API keys, and tokens in environment variables, secret managers, or user-scoped config.
• One-turn specification (one-turn-specification) — State the objective, constraints, data sources, and success criteria in the first turn; keep the final ask last so the prompt is explicit and executable without a long back-and-forth.
• Run what you changed; the pipeline runs the rest (pipeline-runs-the-rest) — Run the build and the tests your change touches, and let the pipeline run everything else — a full local sweep buys no coverage the pipeline does not already have and spends the same time twice.
• Plain names (plain-names) — Name things with the simplest accurate word — variables, functions, types, files, folders, flags.
• Positive constraints and validation (positive-constraints-and-validation) — Prefer positive requirements and validator-backed checks over long negative instruction lists; specify the expected outcome and the validation gate directly.
• One PR per task (pr-per-task) — Every unit of work ends in a pull request; never push directly to the main/trunk branch.
• Done means proven (proof-of-done) — Every unit of planned work carries its acceptance criteria and the gate that checks them, named before the work starts.
• A check you have not seen fail is not a check (prove-the-check-fails) — Put the defect a gate, test or acceptance criterion exists to catch in front of it, watch it go red, take the defect away and watch it go green — a check that has only ever passed is indistinguishable from one whose comparison can produce a single answer that looks like success.
• Reasoning scaffolding minimization (reasoning-scaffolding-minimization) — Avoid step-by-step CoT plans on modern reasoning models unless the task is genuine symbolic reasoning; state the goal and constraints instead of narrating the process.
• Record the decision before you build it (record-decisions) — Every change that adds a feature or meaningfully changes how something works gets a decision record before implementation starts, written with the decision-record skill in the format this project already keeps: its ADR log, its spec framework, or both as a linked pair.
• Screaming architecture (screaming-architecture) — Organize folders and modules by domain/business concept, not by generic technical bucket.
• Small commits, early draft PR (small-commits-early-draft-pr) — Commit one coherent work package at a time and push often.
• Route state transitions through a state machine (state-transitions-through-a-machine) — Where a domain object has explicit states, make the declared transitions the only way it moves between them, and record what triggered each move.
• TDD is mandatory (tdd-mandatory) — Write a failing, behavior-focused test before any production code change.
• Run each suite once; CI runs the rest (test-run-economy) — Normal flow runs the modified surface's suite once — plus the suites of anything that consumes the changed behavior, so an API change pulls the frontend end-to-end that exercises it — and leaves the full suite to CI on push.
• Tests are designed before they are written, and judged after (tests-are-designed-and-reviewed) — Green is the floor, not the evidence: a test list comes out of the acceptance criteria before the first test is written (design-tests, each row naming the failure mode it targets and the mutation that proves it real), and a change that adds or alters tests is not done until something other than its author has run review-tests and asked whether that suite could have gone red.
• Tool schema and success criteria outrank persona prose (tool-schema-success-criteria) — Define explicit tool contracts, required parameters, stop conditions, and success predicates before polishing role text; in short-horizon work, a clear schema plus outcome check beats a clever persona.
• Releases are traceable (traceable-releases) — Every release records the version it went out at and what changed in it, using whatever version marker and release notes this project already keeps.
• Pin actions to a commit SHA; declare least-privilege permissions (pin-actions-to-sha) — Every third-party GitHub Action referenced in a workflow is pinned to a full commit SHA, never a tag or branch — a mutable tag is remote code you re-fetch on every run, not a fixed dependency.

Framework

Skills, personas, and instructions here are managed by ai-badger. Run welcome-ai-badger to re-scaffold after changing .ai-badger/config.json, and feed-badger to contribute project-agnostic improvements back to the framework. Provenance: .ai-badger/manifest.json.