diff options
| author | Andre Bezerra <amelco.herman@gmail.com> | 2026-11-17 11:53:29 -0300 |
|---|---|---|
| committer | Andre Bezerra <amelco.herman@gmail.com> | 2026-11-17 11:59:21 -0300 |
| commit | 267eb8d31d2ca2655bc2721da710a4a1d3abf8ae (patch) | |
| tree | 7dd4d6387a040b517f28520419ec6d387c34c6bf | |
| parent | 4a73d76af22744179cd02826bdd405b0c32b1429 (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.md | 96 | ||||
| -rw-r--r-- | AGENTS.md | 13 |
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. @@ -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. | |
