# stemsep — agent guide ## 0. Precedence 1. The **non-negotiables (R1–R7)** override everything: this file, skills, and the task spec. 2. This file overrides skills. Skills override the task spec. 3. On an unresolved conflict: **stop and report**. Never silently pick a side. ## 1. Non-negotiables - **R1.** Never operate outside the workspace root: no reads, writes, or commands against paths above it. - **R2.** Never use SSH, contact remote hosts, or use stored credentials without explicit permission for that specific action. - **R3.** Keep the build warning-free under the project's existing compiler flags. - **R4.** Never destroy data the task did not create, and never overwrite an existing output directory. - **R5.** Never claim verification you did not run; every "verified" statement shows the command and its output. - **R6.** Never modify this block. It is human-only. - **R7.** Never contradict documented behaviour without updating the documentation in the same change. ## 2. Boot sequence 1. Read this file (automatic). 2. Load `plan` when the approach is not obvious; it explores options and stops before code. 3. Load `spec` for every non-trivial request. It produces the SPEC the rest of the pipeline consumes. 4. Load `architect` when the change alters structure (see tiers below). 5. Load `coder` and `style` before editing; load `tester` before claiming anything works. 6. Load `reviewer` at the end, in fresh context. ## 3. Pipeline ```text [plan] -> spec -> implement -> verify -> review -> commit -> report ``` - The coordinator runs the pipeline and owns the result. A sub-agent never declares a stage complete. - The optional first stage is the `plan` skill (also `/plan`): options and a recommendation, never code. Skip it when the approach is obvious. - **Review precedes commit.** A task ends with exactly one commit. - Every task leaves a written report in `docs/reports/`. ## 4. Change tiers | Tier | Definition | Required stages | | --- | --- | --- | | Trivial | One file, no observable behaviour change, no new module. | implement, verify, commit, report | | Normal | Observable behaviour change, no new module or dependency. | spec, implement, verify, review, commit, report | | Architectural | New module, new directory, new dependency, or a change to the CLI surface or output format. | all stages, plus an ADR in `docs/adr/` | When in doubt, choose the higher tier. ## 5. Sub-agents - Delegate to gain **independence or breadth**, not because a task is large: - review of a completed change (always, for Normal and Architectural), - verification of a claim that the implementer is biased about, - research spread across several areas that can run in parallel. - Do **not** delegate edits to the same file, or work that needs this conversation's context. - Every delegation prompt starts by naming what to read: `AGENTS.md`, the SPEC, and the skills that apply. - One writer per file at a time. - **The reviewer is never the implementer** — review runs in fresh context. - Sub-agents propose. Only the coordinator declares done. ## 6. Definition of done - [ ] Every acceptance criterion in the SPEC maps to evidence. - [ ] The build was run and its output pasted. - [ ] The test suite was run and its output pasted. - [ ] Independent review passed (Normal and Architectural tiers). - [ ] One commit exists for the task. - [ ] The report exists in `docs/reports/`. ## 7. Stop conditions Stop and ask — only in these cases, and always with a concrete question: - the operation is irreversible or destructive; - a non-negotiable would have to be broken; - a SPEC ambiguity changes observable behaviour (decide internal, reversible details yourself); - a precondition is missing and guessing would silently produce the wrong artifact. ## 8. Skill routing | Skill | Load when | | --- | --- | | `plan` | The user wants to discuss options before a SPEC exists. Never edits code. | | `spec` | A request needs acceptance criteria. Start here. | | `architect` | The change alters structure, placement, dependencies, or an external contract. | | `coder` | Implementing an approved SPEC. | | `style` | Writing or reading code — alongside `coder` and `reviewer`. | | `tester` | Deciding what to test or proving a change works. | | `reviewer` | After implementation, before the commit. | ## 9. Repo hygiene - Never commit build outputs, binaries, media, or model weights (`/stemsep`, `build/`, `dist/`, `*_stems/`, `models/*.onnx`, `*.wav`). - Never rewrite git history, force-push, or amend someone else's commit. - Transient artifacts belong in `build/` and `dist/`, which are ignored. ## 10. Project facts - Build: `./build.sh` - Run: `./stemsep -i -m ` - Test: `./tests/run.sh` (see `tester`) - Checks: `./scripts/check.sh` - Modules: `main.c` (orchestration), `audio.c` (dispatch), `audio_wav.c` (WAV input via dr_wav), `audio_mp3.c` (MP3 input via dr_mp3), `wav_writer.c` (WAV output via dr_wav), `playback.c`, `metronome.c`. Detail in `architect`. - Nothing is external except `mpv` at runtime; the policy is in `architect`.