# XX Spec Map
This file is the short agent table of contents. Keep it concise.
## First Read
1. `docs/superpowers/review/track-start-prompt.md` - track/chunk workflow contract.
2. `docs/adherence.md` - execution and evidence constraints.
3. `docs/review_criteria.md` - consensus review contract.
## Track Plan Index (2026-05-05)
All 12 implementation track plans are in `docs/superpowers/plans/`:
| Track | Plan file |
|---|---|
| track01 | `2026-05-01-track-01-xx-setup-plan.md` |
## Conversation Commands (Spec-First)
- `./agent start track TRACK [chunk CHUNK]`: resolve scope and report scope only.
- `start track TRACK chunk CHUNK`: equivalent (tool-conversation form) for the above.
- `start chunk CHUNK`: infer active track from current context when clear; otherwise ask for track.
- `confirm start`: execute only the confirmed chunk plan.
- `./agent review track TRACK CHUNK`: run chunk review protocol against monitor/task artifacts.
- `review track TRACK CHUNK`: equivalent (tool-conversation form) for the above.
- `./agent review-track-gate TRACK [CHUNK]`: verify track/chunk gate completion from the latest review cycle.
- `./agent preflight`: run `tools/agent/preflight.sh`.
### Scope Convention
Treat these commands as *documentation planning gates* until implementation work starts. This repo is currently in spec stage.
## Hard Rules
1. Keep this repo spec-first: do not claim implementation closure without evidence artifacts.
2. Use small, explicit artifacts with low abstraction overhead.
3. Keep track/chunk evidence synchronized across:
- `docs/superpowers/plans/`
- `docs/superpowers/tasks/`
- `docs/superpowers/evidence/`
- `docs/superpowers/implementation/`
4. Adherence and review criteria are mandatory inputs before closing any chunk.
5. Use relative file paths that match repo-local references only.
6. Do not revert unrelated work unless explicitly asked.
## Rust Rules
[1] Read Cargo.toml, workspace, edition, rust-version, features, lints, CI, src/lib.rs, tests, unsafe/FFI before editing.
[2] Preserve public API, feature behavior, edition, and MSRV unless explicitly asked to change them.
[3] Borrow by default at API boundaries; avoid unnecessary ownership, allocation, and clone().
[4] Use Option for absence, Result for failure, and avoid unwrap on caller-controlled input.
[5] Keep binaries thin and reusable logic in libraries.
[6] Do not widen pub visibility to make code compile.
[7] Async: do not block executor threads or hold locks across .await.
[8] Unsafe: keep narrow, document every block with SAFETY, and wrap in safe abstractions.
[9] FFI: isolate raw bindings, document ownership/lifetime/layout/unwind assumptions.
[10] Add docs and tests for new public behavior.
[11] Run or satisfy fmt, clippy, check/test/doc, dependency/security, package, and semver gates.
[12] Flag semver impact for public API changes.
## Canonical Policy
- Product scope and architecture: `docs/xxx.md`
- Current plan index: `docs/plans/`
- Execution conventions and commands: this file + `docs/superpowers/review/track-start-prompt.md`
- Schemas: `docs/spec/*.schema.json`
- Review governance: `docs/adherence.md` and `docs/review_criteria.md`
## Harness Commands
- `scripts/check-spec-harness.sh` - lightweight spec consistency and link checks.
- `./agent start TRACK [CHUNK]` -> `tools/agent/start_track.sh`.
- `./agent review TRACK CHUNK` -> `tools/agent/review_chunk.sh`.
- `./agent review-track-gate TRACK [CHUNK]` -> `tools/agent/check_track_gate.sh`.
- `./agent next-chunk TRACK` -> `tools/agent/next_chunk.sh`.
- `agent check-track-artifacts` -> `scripts/check-track-artifacts.sh`.
- `agent check-agent-tools` -> `scripts/check-agent-tools.sh`.
- `agent preflight` -> `tools/agent/preflight.sh`.
## Track Closure Gate
- Track/chunk completion requires a successful latest-review-cycle pass:
- `PASS 3/3`
- 3/3 reviewers
- zero blocking findings
- zero non-blocking findings
- PASS verdict
- Do not move to the next chunk or next track on narrative progress alone; require the applicable latest review cycle to reach `PASS 3/3` first.
- Current track01 execution constraint: stay mac-first; keep Windows/Linux/headless jobs scaffold-only and deferred from `chunk00` closure until explicitly redirected.
- Use `tools/agent/check_track_gate.sh TRACK CHUNK`.
## Verification
Run this before marking a track chunk complete:
```bash
scripts/check-spec-harness.sh
```
Run full workflow check before closure:
```bash
tools/agent/preflight.sh
```