1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
|
# stemsep — agent guide
<!--
Loaded automatically at the start of every session. Target: <= 140 lines.
Anything that does not fit here belongs in a skill or in docs/.
Layering: non-negotiables > this file > skills > the task spec.
-->
## 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
<!-- RULES:BEGIN — human-only edit zone. Pinned by scripts/check.sh. -->
- **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.
<!-- RULES:END -->
## 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
<!-- Mutable. Update when the build or layout changes. -->
- Build: `./build.sh`
- Run: `./stemsep -i <audio_file> -m <music_identifier>`
- 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`.
|