arxii

Use when running or writing tests in this repo — choosing the SQLite fast tier vs Postgres parity tier, the just test recipes, @tag("postgres") decisions, --keepdb pitfalls, or diagnosing SQLite-vs-PG test failures.

Use when working on a GitHub issue from start to merged PR. Picks up an issue (or prompts for one), drafts the spec onto the issue body for team review, implements after a member approves it (spec:approved label), opens a PR, watches CI and fixes failures, and handles post-merge cleanup including filing follow-up issues. Polytoken-native: orchestrates the ported brainstorming + writing-plans + using-git-worktrees skills.

Use when starting feature work that needs isolation from the current workspace, or before executing implementation plans — ensures an isolated workspace exists.

Use when a class/function/model has no live caller and you're deciding whether it's a speculative stub, dead code, or unfinished work — or when writing new code whose caller doesn't exist yet. Traces a surface's origin (git history, linked issue/spec, roadmap/ADR) before classifying it, and documents intent forward so the next reader doesn't have to redo the trace.

Use when a feature design, spec, or implementation plan is about to propose a new code surface (model, dataclass, enum, serializer, component, hook, helper, field, endpoint) OR wire up an existing stub (a "not wired" button/endpoint/flow), or when relying on a systems/architecture/roadmap doc's claim about what exists or doesn't, OR when filing a follow-up/audit issue or writing a "deferred follow-up" into a spec (a deferral is a proposed future surface — verify its premise before it becomes a filed issue) — before committing the spec, filing the issue, or writing code.

Use when models have changed significantly, after migrations, or when cross-app relationship data in docs/systems/MODEL_MAP.md seems stale. Also use when you can't find how systems connect and need to regenerate the model map.

Use when adding or working with Django models in this repo, resolving an apparent N+1, optimizing queries, caching, or walking foreign-key relationships — and before writing any resolve_/batch_fetch_ helper or flushing the identity map.

Use this before any creative work — creating features, building components, adding functionality, or modifying behavior. Explores user intent, requirements, and design before implementation. Drafts the spec into the GitHub issue body for team review.

Use when you have an approved spec or requirements for a multi-step task, before touching code. Produces an ephemeral implementation plan (worktree-only, never committed).

Use when designing or restructuring a subsystem's interface, deciding where a seam goes, judging whether a class/module earns its keep, or making code more testable — the shared deep-module design vocabulary.

Use when introducing or sharpening a domain term, when a design conversation lands a hard-to-reverse decision, or when working in an app whose AGENT_GLOSSARY.md or docs/adr/ needs updating — keeps the glossary and ADR log current and used.

Use before any GitHub operation via the gh CLI — creating/editing/closing/commenting on issues or PRs, assigning, labelling, or referencing an issue/PR number. Especially right after gh issue create / gh pr create when you need the new number, or when about to mutate an issue you "know" the number of.

Use when asked to find architectural friction / deepening opportunities in the codebase, or to periodically audit a subsystem for shallow modules and leaky seams. Produces a markdown report of candidate refactors.

Use when you notice a recurring tool-call failure or environment-quirk pattern. Logs the friction; when ≥5 entries accumulate, proposes CLAUDE.md edits (apply now) or files a follow-up issue. Replaces the permission-prompt model that doesn't apply in the devcontainer (where Claude runs with --dangerously-skip-permissions).