summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorAndre Bezerra <amelco.herman@gmail.com>2026-11-17 11:53:29 -0300
committerAndre Bezerra <amelco.herman@gmail.com>2026-11-17 11:59:21 -0300
commit267eb8d31d2ca2655bc2721da710a4a1d3abf8ae (patch)
tree7dd4d6387a040b517f28520419ec6d387c34c6bf
parent4a73d76af22744179cd02826bdd405b0c32b1429 (diff)
add the plan stage to the agent harness
Wire the optional pre-spec plan skill into the boot sequence and pipeline, and record when to use it in the skill routing table.
-rw-r--r--.agents/skills/plan.md96
-rw-r--r--AGENTS.md13
2 files changed, 104 insertions, 5 deletions
diff --git a/.agents/skills/plan.md b/.agents/skills/plan.md
new file mode 100644
index 0000000..311f9bf
--- /dev/null
+++ b/.agents/skills/plan.md
@@ -0,0 +1,96 @@
+---
+name: plan
+description: Use when discussing a feature or fix before implementation — reads the current code, researches options, and recommends the simplest approach. Never edits code.
+whenToUse: When the user wants to think through a change, compare approaches, or scope work before a SPEC exists.
+user-invocable: true
+---
+
+# plan
+
+A thinking partner. The output is a decision, not a diff.
+
+## Hard rules
+
+- **Never modify code, tests, documentation, or configuration.** No edits, no
+ file writes, no commits, no branches.
+- Never opine on code you have not read. Reading comes first.
+- Building and running the program to understand behaviour is allowed.
+- The plan stays in the conversation. Nothing is written to the repo unless the
+ user explicitly asks for a file.
+
+## Process
+
+1. **Restate** the goal in one sentence, and the problem it actually solves.
+2. **Read** the relevant code. Name the files and functions involved.
+3. **Ask** the questions whose answers change the design. One focused round, not
+ a wall of text. If nothing is genuinely ambiguous, say so and proceed.
+4. **Research.** The repository first. Then the internet, whenever the answer
+ depends on facts outside the repo — format specifications, library behaviour,
+ algorithm properties, prior art, known pitfalls. Cite what you use.
+5. **Propose at least two options.** One of them must be the smallest thing that
+ could possibly work. Include "do nothing" when it is a real option.
+6. **Recommend one**, and let the reason be simplicity.
+7. **Check the plan against the other skills** (table below).
+8. **Name the risks and unknowns** — what would make this plan wrong.
+9. **Hand off**: end with the acceptance criteria that `spec` will formalize.
+
+## Simplicity test
+
+The recommended option must pass every line, or the exception must be stated
+explicitly:
+
+- Does it reuse an existing module instead of adding one?
+- If it adds a file, can the responsibility be named in one sentence?
+- Does it add indirection a reader must follow to understand one behaviour?
+- Does it add a dependency? (the answer is no unless proven otherwise)
+- Does it solve the stated problem, and not the neighbouring one?
+- Could a competent reader understand it without a design document?
+
+The simplest implementation that satisfies the acceptance criteria wins. Not the
+most general, not the most future-proof, not the most elegant.
+
+## Consistency with the other skills
+
+| Skill | The plan must answer |
+| --- | --- |
+| `architect` | Which module owns this? Does `main.c` grow? Any new dependency, and if so, the ADR and the removal task? |
+| `style` | Can it be written in the existing idioms without inventing a convention? |
+| `tester` | How is it tested? What is observable? Does it fit the 10-minute suite? |
+| `coder` | Can it be implemented without touching unrelated code? |
+| `spec` | What are the acceptance criteria, and what is out of scope? |
+
+A plan that violates `architect` is not a plan — it is a rewrite proposal.
+
+## Output
+
+```text
+PLAN
+- Goal:
+- Current behaviour:
+- Options:
+ 1. <smallest> — cost, risk
+ 2. <alternative> — cost, risk
+- Recommendation: <n> — because <simplicity reason>
+- Files touched:
+- Risks / unknowns:
+- Out of scope:
+- Acceptance criteria (for spec):
+- Open questions:
+```
+
+## Research notes
+
+- Search when the answer is external: ONNX Runtime behaviour, mpv options, WAV
+ and MPEG framing, resampling properties, C library behaviour.
+- Do not search for what the repository already answers.
+- Prefer primary sources — specifications and official docs over tutorials.
+- Link what shaped the recommendation, not everything that was read.
+
+## Anti-patterns
+
+- Writing code in the answer, even "just to show the shape".
+- Proposing a rewrite when a local change reaches the same acceptance criteria.
+- Introducing an abstraction for a single use.
+- Planning past the stated goal into "while we're here" territory.
+- Presenting one option as if it were the only one.
+- Declaring a design "simpler" without saying what got smaller.
diff --git a/AGENTS.md b/AGENTS.md
index 47bfcae..86236a6 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -29,18 +29,20 @@ Layering: non-negotiables > this file > skills > the task spec.
## 2. Boot sequence
1. Read this file (automatic).
-2. Load `spec` for every non-trivial request. It produces the SPEC the rest of the pipeline consumes.
-3. Load `architect` when the change alters structure (see tiers below).
-4. Load `coder` and `style` before editing; load `tester` before claiming anything works.
-5. Load `reviewer` at the end, in fresh context.
+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
-spec -> plan -> implement -> verify -> review -> commit -> report
+[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/`.
@@ -88,6 +90,7 @@ Stop and ask — only in these cases, and always with a concrete question:
| 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. |