summaryrefslogtreecommitdiff
path: root/AGENTS.md
blob: 6061bc14090e16effc87542eb8090e2a70d505b1 (plain)
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`.