codebase: Instructions file for Codex

Codebase Guidance

Essential Commands

# Run tasks via Nx (always prefer this)
nx run <project>:<target>:<configuration>
nx run-many --target=typecheck-code,lint-code,format-code,format-code,guard-code --all
nx affected --target=vitest --base=main

# Install dependencies
pnpm add --filter <project> <package>
pnpm add -w <package>  # Workspace root

# Tools that run directly (not via Nx)
docker build --platform linux/amd64 -t myapp .
kubectl get pods
helm upgrade --install myrelease ./chart

Agent Workflow

Work in this repository integrates skills from both mattpocock/skills and obra/superpowers to clarify, specify, track, implement, and review non-trivial features, refactors, and bugfixes with strict verification gates.

Planning is human-gated; implementation is continuous. During planning, never chain skills automatically — stop after each step and wait for explicit invocation. During implementation, subagents execute autonomously and may create sub-issues without asking.

1. Clarify: Run brainstorming with grill-with-docs (domain models/ADRs) or grill-me (plain interview). Follow grilling pacing (one numbered frontier with recommendations; ask ask-matt if unsure). When done, summarize understanding and stop.
2. Specify: Run to-spec only on manual request. Publish the spec issue, link it, and stop.
3. Decompose: Run to-tickets only on manual request. Confirm breakdown, publish tickets/sub-issues, and stop. Reach for wayfinder if work exceeds one session. (Ignore writing-plans / docs/superpowers/specs/ hand-offs; see docs/agents/issue-tracker.md).
4. Handoff: Run handoff only on manual request for multi-session work. Post the # Handoff comment on the spec issue (see Handoffs) and stop.
5. Build: Set tickets to status:in-progress before testing (see docs/agents/issue-tracker.md).
   • Multi-ticket spec: Dispatch each parent issue to a fresh subagent (subagent-driven-development); never implement sequentially in this session. Parallelize independent tickets (dispatching-parallel-agents) or stack dependent ones (gh-stack). Brief each with its ticket, the spec, and steps 5–8. See Multiple Pull Requests.
   • TDD loop: Use implement with test-driven-development (strict red-green cycle) and tdd (confirmed seams, public interfaces; refactoring belongs to step 6). Test via nx run <project>:vitest:<kind> (see Testing & Coverage).
   • Debugging: Use systematic-debugging (root-cause gate) with diagnosing-bugs.
6. Review: Request review via requesting-code-review (fresh subagent handed base/head commits), review with code-review, and apply feedback via receiving-code-review.
7. Validate: Run validate-code gated by verification-before-completion.
8. Integrate: Use finishing-a-development-branch for the merge/PR decision, executing via submit-changes, commit-code, and create-pull-request. Read its test step as nx affected --target=vitest --base=main.