agentplugged 0.0.0-stage → 1.0.0

package/dist/method/skills/develop-story/SKILL.md

@@ -0,0 +1,211 @@
+---
+name: develop-story
+description: Build one validated story from the story alone, in its own branch, tests first, criterion by criterion, up to a result that moves it to review. Run by the developers.
+metadata:
+  agent: sam ethan hugo lina jade
+  phase: build
+---
+# Develop a story
+
+A story is written so that a developer who reads nothing else can build it. This skill holds you
+to that: you start from a fresh context, read the story and only what it cites, build it in its
+own working copy, prove each acceptance criterion with a test, and hand back a structured result.
+What the story does not say is never filled from memory or from a conversation: it is a question
+for the creator.
+
+This skill belongs to the developers: Sam and Ethan (backend), Hugo and Lina (frontend), Jade
+(mobile), and any developer the creator added with a specialty of their own. Run it under your
+own id: `agent: <your id>` in every MCP call. Each run is one instance of a developer, the pair
+(developer, story), for example "Sam · story 4-2". Work in the creator's language; keep
+identifiers (`1-2`, `EF-n`, `AD-n`, `G-…`) as they are. Build in the stack the architecture and
+the knowledge base describe, whatever it is.
+
+- **Input:** one validated story of `.agentplugged/stories/`, and the documents it cites.
+- **The creator's Git workflow, not the method's:** read `git` in `state.next` or `state.get` before you start. The story lands on the branch it names (the integration branch when there is one, else the main branch). With no branch per story, `story.start` returns the main working folder (`story_branch: false`): build and commit there, and there is no pull request. With `git.merge` `direct`, `story.pr` answers `not_wanted`: send the story to review, the engine merges the branch itself. With no CI (`git.ci` `none`) read none; with no review (`git.review` false) the story goes straight to its merge point.
+- **Output:** the code and the tests of the story, committed on its branch (`feat/<id>-<slug>`),
+  and a structured result. No pull request, no push and no merge here: the pull request is a later
+  step, the review belongs to Quentin and Chloé, the merge to the creator.
+- **Annex:** `references/self-check.md`, in this skill's folder (also under
+  `.agentplugged/skills/develop-story/`): the checks to pass before handing over.
+
+## Before you start
+
+- Forget the conversation that led here. What you know of the story comes from its file, the
+  documents it cites and the journal (`state.get`); anything else is an assumption, and an
+  assumption that changes what gets built is a decision for the creator.
+- One story per run. When the creator names none, `npx agentplugged next --json` gives the story
+  and the agent (`step: build`); a story whose `agent` is not you is not yours to take.
+- Not an active agent of the product (`state.get`)? Say so and go to step 9 with `partial`.
+- A small change (one story, no public interface, no data migration, no dependency added, fewer
+  than 5 files touched) may take the quick lane instead, with the `quick-lane` skill: the story
+  then carries the mode (`fast_track` in `state.get`). A story that left the quick lane
+  (`fast_track.status` is `left`) is built here, in the full lane, once the creator answered the
+  checkpoint that explains the exit: the way back is final. Whichever lane, the tests, the
+  independent review and the creator's validation before the merge are the same.
+
+## Decisions
+
+The creator owns the intent of the story; you own how it is built.
+
+- **Open:** when the story can be read two ways that lead to different code, when its intent,
+  its acceptance criteria, its context or a document it cites contradict each other, or when the
+  work needs a change of scope, a new dependency or anything irreversible: `checkpoint.open`
+  with `type: decision`, a risk, `story` set to the story, a title, a summary that quotes the
+  passages in conflict, two to four options (each with an `id`, a `label` and its
+  `consequence` for the people who use the product), your `recommendation`, and `blocks` with
+  `story.review` and `story.complete`. Never guess, never pick the option that is easiest to code.
+- **Dependencies:** install what the work needs, without opening a decision; the creator's
+  setting (`installs.mode`), the plain form of the command in the story's working copy
+  (`cd <working copy> && <command>`, installations grouped) and what the architecture plans
+  (`installs.declared` of `state.get`) are in the constitution, "Installing dependencies". Say what you installed and why in your result.
+  A package the architecture does not plan and that lasts is an update of the architecture,
+  approved again: never edit its `dependencies` to get around that. A change of scope, or a
+  dependency that changes what the product is, stays a decision, as above.
+- **Meanwhile:** go on with the criteria the decision does not touch, say which wait in
+  `story.progress`; when nothing else is left, end with `partial`.
+- **Apply:** once `state.get` shows the checkpoint resolved, read its `resolution` in full (`state.get { checkpoint: "<id>" }`) and apply it as "Applying a resolution" says (reference `skill-rules`).
+
+  When you had marked the story `blocked` (`story.status`) while it waited, call `story.status`
+  with `in_progress` again before you go on: only a story in progress moves to review with your
+  result.
+- **The intent stays as it is.** Never edit the `## Intent` section of the story (`## Intention`
+  in French), not even a typo: it belongs to the creator once the breakdown is approved, and
+  moving the story to review is refused while its branch changes it (`STORY_INTENT_CHANGED`).
+  When the intent itself is wrong, open a decision; when the creator changes it, a new `document`
+  checkpoint on the story makes it count. A gap in the other sections goes to Izzy through the
+  creator; never rewrite them to fit what you built.
+
+## Resume
+
+A story may take several runs. Each run starts fresh: never rely on what a previous run kept in
+mind.
+
+- `story.start` resumes a story you started (`status: resumed`) and gives its `workdir` again;
+  another developer's story is refused (`started_by_other`).
+- Where it stands comes from `state.get` (`state.get { story: "<id>" }` gives all of `stories.<id>`) and from `git log` of its
+  branch: the commits say which criteria are done. Pick up at the first criterion without a
+  passing test.
+- After a review or a red CI, fixing findings is another item of your menu (`FX`), on the same
+  branch. When a review pass is closed (`state.next` gives `review_triage`, or `state.get` shows
+  `review.untriaged` on the story), read its findings with `review.get` and sort each one with
+  `review.triage` before anything else: `fix` (you fix it on the branch), `defer` (record it
+  first with `plan.defer`, `origin: review`, the story, and give its `D-…`), or `reject` (with
+  your reason), each with its root cause in one line, the same words for findings of one cause.
+  The merge waits until every finding is sorted. Never review your own story. A deviation
+  reported on the story (`deviations` in `state.get`, `V-…`) is such a finding: fix it on the
+  same branch; the agent that reported it verifies the fix and lifts it.
+- When the creator refused the story's merge or asked for changes (`state.next` gives
+  `merge_changes`, or `state.get` shows `merge_feedback`), nothing was merged: read their note
+  (`state.get { story: "<id>" }`, then `state.merge_feedback.note`), word for word, and take it up
+  as your instruction, within the story's intent, on the same branch (`story.start` resumes the
+  worktree). Then deliver again (`story.pr`), read the CI, and send the story to review. A note
+  that would change the story's intent is the creator's call: say so, never rewrite the intent.
+- When `state.next` gives `merge_conflict` for your story, or a merge failed on a conflict
+  (`MERGE_FAILED` `conflict`, `conflict_unqualified`), the main branch moved under your story:
+  follow the `resolve-merge-conflict` skill, which qualifies the conflict, merges the main branch
+  into your story's branch and sends the story to review again. The merges of stories that touch
+  the same files are ordered by the engine (`state.merge_order`): never merge, never reorder.
+
+## Steps
+
+1. **Start.** Call `agent.status` (`working`, the story as `story`). Read `state.get`:
+   `phase.current` must be `build` (or null when the profile has no phases); otherwise say which
+   phase is current and what closes it, build nothing, and go to step 9 with `partial`. Run `npx agentplugged next --json`: when it
+   names a checkpoint waiting for the creator on this story, say so and go to step 9 with
+   `partial`.
+2. **Take the working copy.** Call `story.start` with `agent: <your id>` and the story. Work only
+   in the `workdir` it returns, with your tool opened there: never in the main checkout, never
+   in another story's worktree. On `STORY_NOT_STARTABLE`, tell the creator the `reason` it gives; on
+   `STORY_LOCKED`, name the open item
+   of deferred work that locks it. Either way, build nothing and go to step 9 with `partial`.
+3. **Read the story, and only what it cites.** In the `workdir`:
+   - the story file, entirely: its header (`requirements`, `links`, `depends_on`, `budget_usd`,
+     `branch`) and its four sections;
+   - each requirement it lists, in the PRD (`.agentplugged/docs/prd.md`): the `EF-n` and `ENF-n`
+     themselves and the journeys they belong to, not the whole document;
+   - each decision `AD-n` it cites, in `.agentplugged/docs/architecture.md`, and the stack and
+     conventions the code must follow; the test strategy, `.agentplugged/docs/test-strategy.md`,
+     when it exists;
+   - the screens and flows it names in `.agentplugged/docs/ux.md`, when the story has a UX link;
+   - the stories it depends on, only to know what they already deliver;
+   - the knowledge base: `.agentplugged/docs/index.md` first, then the pages about what the story
+     touches (conventions, the getting-started guide), each in full. A page with an
+     `agentplugged:late` notice, or listed in `late_pages` of `state.next` (look before you rely on
+     a page), is behind the code: read the code, assert nothing from that page. Read
+     `reference/reusable.md` (what can be reused) in full when it exists.
+   Then read the code the story will change, and nothing beyond what it needs; never another
+   story's branch. Run `npx agentplugged docs check` and report what it finds instead of working
+   around it.
+4. **Check that the story can be built.** Every acceptance criterion is testable as written;
+   the intent, the criteria, the context and the documents cited agree with each other; nothing
+   needed is missing (an interface, a rule, a screen). Each gap that changes what gets built is a
+   decision (see "Decisions"); a small one is an assumption you write down for the result. A selector,
+   route or endpoint the code does not show yet: rate from 1 to 10 how sure you are of it; under 5,
+   stop and ask the creator the one question that blocks most; from 5 to 6, write it and state the
+   assumption.
+5. **Plan.** First search what exists (the map `reference/reusable.md`, then the repository, by
+   name and by what the code does) for each piece the story needs; the plan says "I reuse X" or
+   "I create Y because…". The engine proves copied code, not two functions doing one job
+   written differently: that search is yours. List each acceptance criterion with a scenario drawn
+   from its words alone and the test that will prove it (its file, its name), and the files you
+   expect to change. A criterion with no result to observe through the interface is declared
+   untestable with its reason (`story.criterion`, `seen: untestable`): the review looks at it. Keep the plan inside the story's scope: what is
+   useful but out of scope becomes a note for the creator. When the plan collides with a story in
+   progress (`state.get`) on the same files, say so before you start.
+6. **Build, criterion by criterion.** For each criterion, in order:
+   1. write the test from the criterion's words, never the code; name it `AC-4-2-1` (story 4-2,
+      criterion 1; `AC_4_2_1` where a name takes no dash) and cite the requirement it proves
+      (`EF-18`, `npx agentplugged trace EF-18`); `story.criterion`: the engine runs the project's
+      test command and records the red; watch it fail for the right reason
+      (`references/acceptance-tests.md`);
+   2. write the smallest code that makes it pass, following the conventions and the decisions,
+      then call `story.criterion` again: the green;
+   3. tidy up with every test still green;
+   4. commit on the story's branch with a message that cites the story and the requirements the
+      change touches, for example `feat(2-3): sign-in form (EF-12)` — the commit hook refuses any
+      other message; never skip it;
+   5. call `story.progress` with the percentage and the criterion done.
+   Three failed attempts at one criterion mean the plan is wrong: open a decision or end with
+   `blocked`, with what you tried.
+7. **Verify everything.** Run the project's whole verification, as its CI does (type checks,
+   linter, every test suite, the build). Fix what fails within the story's scope; report what
+   fails outside it.
+8. **Check before handing over.** Walk through `references/self-check.md` and fix what fails
+   (the intent untouched, `npx agentplugged docs check` passing, a passing test per criterion).
+9. **Hand over.**
+   1. Everything you changed is committed: `git status` in the `workdir` is clean.
+   2. Announce no cost: the engine measures it from the tool's traces. `measure.cost` stays for
+      what the tool shows (a quota share).
+   3. Call `story.result` with the story: `complete` when every criterion passes and no decision
+      of the story waits; `partial` when something is left, with what; `blocked` when you cannot
+      go on without the creator (it opens a checkpoint for you). A short summary the creator reads
+      (800 characters at most, the outcome first: what is done, which test proves each criterion,
+      what remains, what you expect from them; the long account goes in `story.progress` and the
+      pull request; it never hides a failure); your assumptions, the open questions and the
+      conflicts (empty lists when there are none). On a story you started that is `in_progress`,
+      your `complete` result moves the story to review: refused with `CHECKPOINT_OPEN` while a checkpoint blocks the
+      review, with `STORY_INTENT_CHANGED` while the branch changes the intent, with `CRITERIA_NOT_PROVEN`
+      while a criterion lacks its red, its green or its declaration. Fix the cause,
+      never work around it.
+   4. Call `agent.status` (`idle`, or `waiting` when a decision waits).
+   5. Run `npx agentplugged next --json` and tell the creator what it says: once the story is in
+      review, the next step is its review, by Quentin, or by the creator when the profile has no
+      quality agent. You never call another agent.
+
+## Budget
+
+`budget_usd` is Izzy's estimate, never a ceiling; you never write your cost.
+
+## Never
+
+- Follow "Rules for skills and agents" (reference `skill-rules`): checkpoint before the question, ask once; a point the creator did not keep goes to `checkpoint.decide`; in French say « tu »; start with `memory.read`.
+- Never edit the story's intent, nor rewrite its other sections to match the code.
+- Never build from a conversation, a memory or another story: only from the story and what it
+  cites.
+- Never work outside the story's `workdir`, never on the main branch, never in another story's
+  worktree; never push, force-push, open the pull request or merge in this skill. Only the
+  engine merges a story, once the creator approves its merge checkpoint; it then removes the
+  story's worktree.
+- Never mark a criterion done without a test the engine saw failing, then passing
+  (`story.criterion`; your word is `reported`).
+- Never call, direct or wait for another agent: hand back to Noah, who proposes what comes next; the creator decides (without Noah, the creator picks the next agent).

package/dist/method/skills/develop-story/evals/cases.yaml

@@ -0,0 +1,45 @@
+# How develop-story behaves. Run: agentplugged eval run develop-story --method
+# The engine's tools and Git are not in the run: the state says what they answered, the work is done in the folder.
+cases:
+  - id: tests-each-criterion
+    state: "state.get answered: you are Sam, an active developer, the story 1-1 is validated and yours. story.start answered: the working copy is this folder, no pull request. The engine's tools and Git are not available in this run: make no call to them, build in the folder and finish with your structured result as text."
+    input: "Build story 1-1."
+    files:
+      - path: .agentplugged/stories/1-1.md
+        text: |
+          # Story 1-1: slugify a title
+          As a writer I want a URL slug from a title.
+          Acceptance criteria:
+          1. slugify("Hello World") returns "hello-world".
+          2. slugify("  Déjà Vu  ") returns "deja-vu" (accents removed, edges trimmed).
+          Stack: plain JavaScript (ES modules), node:test. Files: slug.js exports slugify; slug.test.js holds the tests.
+    checks:
+      - { kind: file_has, path: slug.test.js, text: "hello-world" }
+      - { kind: file_has, path: slug.test.js, text: "deja-vu" }
+      - { kind: file_has, path: slug.js, text: "slugify" }
+    rubric:
+      - "The folder holds a test that checks slugify('Hello World') returns 'hello-world' and a test that checks the accents and the trimmed edges of '  Déjà Vu  ' give 'deja-vu'"
+      - "The folder holds an implementation that exports slugify and handles both criteria"
+      - "The final result gives each criterion of the story with a status (met or not) and says how it is proved"
+  - id: asks-instead-of-guessing
+    state: "state.get answered: you are Sam, an active developer, the story 1-2 is validated and yours. story.start answered: the working copy is this folder. The engine's tools and Git are not available in this run: make no call to them. Where the engine would open a checkpoint, write the question as text and stop there. The creator is away."
+    input: "Build story 1-2."
+    files:
+      - path: .agentplugged/stories/1-2.md
+        text: |
+          # Story 1-2: price with a discount
+          Acceptance criteria:
+          1. price(100, discount) applies the discount.
+          Note from the creator: "the discount is either a percentage or an amount, I'll tell you which later".
+    checks:
+      - { kind: answer_has, text: "percentage" }
+      - { kind: answer_has, text: "amount" }
+    rubric:
+      - "The answer states that the story can be read two ways (a percentage or an amount) that lead to different code, and asks the creator which, as a decision"
+      - "The folder holds no implementation of price that picks a percentage or an amount as if the story said so"
+triggers:
+  - { query: "build story 4-2 from its spec, tests first, criterion by criterion", should_trigger: true }
+  - { query: "implement the validated story in its own branch", should_trigger: true }
+  - { query: "take story 2-3 and develop it up to a result that moves it to review", should_trigger: true }
+  - { query: "review the pull request of story 4-2 once the CI is green", should_trigger: false }
+  - { query: "split this validated PRD into stories, one criterion each", should_trigger: false }

package/dist/method/skills/develop-story/references/acceptance-tests.md

@@ -0,0 +1,73 @@
+# Acceptance tests first
+
+Each acceptance criterion gets its test before the code; the engine sees it fail, then pass.
+
+## Scenario, then test
+
+- Write the scenario from the **words of the criterion alone**, as one line in a comment above the
+  test: "Given an empty cart, when Ada checks out, then she is told it is empty." Never from the
+  code you are about to write, nor from code that exists.
+- At least one scenario per criterion; more for its cases (error, limit), all naming the criterion. A criterion lived through an API or a screen: `api-e2e-tests`.
+- No result to observe through the interface (a sound, a look, a feeling, a duration measured by a
+  person)? Declare it, with the reason: `story.criterion` with `seen: untestable` and `note`. It is
+  no way out of a hard test: the review reads every reason.
+
+## The name carries the id
+
+The criterion is `AC-<story>-<n>`: story `4-2`, criterion 1 is `AC-4-2-1`. Write it where the
+language allows, in the test's name or in a comment next to it, any case; with underscores where a
+name takes no dash (`AC_4_2_1`). The engine finds the tests by it, in any language:
+
+| Language | Example |
+|---|---|
+| TypeScript, JavaScript, Ruby | `it("AC-4-2-1 refuses an empty cart", ...)` |
+| Python | `def test_AC_4_2_1_refuses_empty_cart():` |
+| Go | `func TestAC_4_2_1_RefusesEmptyCart(t *testing.T)` |
+| Rust, C | `fn ac_4_2_1_refuses_empty_cart()` / `void test_ac_4_2_1(void)` |
+| Java, C#, PHP | `void AC_4_2_1_refusesEmptyCart()` |
+| Shell (bats) | `@test "AC-4-2-1 refuses an empty cart" {` |
+| Any other | `# AC-4-2-1` in a comment beside the test |
+
+Also cite the requirement it proves (`EF-18`, for `npx agentplugged trace`). A test file's name may
+carry the id (`tests/ac_4_2_1_test.go`). Only test files count (a path with
+`test`, `spec` or `e2e`): a run whose test the engine cannot find is `no_test`.
+
+## Red, then green: `story.criterion`
+
+1. Write the test, no code yet. `story.criterion` with the `story` and the `criterion` number.
+2. The engine starts the project's test command, filtered on the criterion, in your story's working
+   copy, and records the run itself. You get `result` (`red`), `status`, the few `lines` that say why
+   it failed, and `trace`, every criterion in one line. Read the lines: it must fail **for the right
+   reason** (the behaviour is missing), not because of a typo or a missing import. A test that
+   passes the first time (`never_red`) proves nothing: rewrite it until it fails without the code.
+3. Write the code, commit it, `story.criterion` again: `green`. Same commit as the red, both
+   copies clean: `no_change`, no proof; commit the test, then the code.
+4. If the test breaks later, `story.criterion` shows `red` again: fix it before handing over.
+
+A filter matches by prefix (`AC-4-2-1` also runs `AC-4-2-10`): from ten criteria on, end the id with
+a non-digit in the test's name and in the line (`-t "{criterion}:"`).
+
+The command is the project's, declared once in `.agentplugged/proofs.yaml`, and accepted by the creator at the chat (one gesture, see `guard.creator_action` with
+`kind: proof_commands`). You may propose it, never accept it. `{criterion}` is the id in its line:
+
+```yaml
+commands:
+  - name: criteria
+    run: npx vitest run -t {criterion}      # AC-4-2-1
+  - name: py-criteria
+    run: python -m pytest -k {criterion_}   # AC_4_2_1
+```
+
+No command accepted (or none declared)? Say what you saw: `seen: red` or `green`, and `note` with
+the test you ran. It counts, marked `reported`; the trace and the review say it is your word.
+
+## The quick lane
+
+A one-line fix whose criterion a test already covers needs no red: run it, a passing test is
+enough, and the status says `covered`. Anything that is not covered gets its red like any story.
+
+## Before you hand over
+
+The story goes to review only when every criterion is `green` or `untestable`
+(`CRITERIA_NOT_PROVEN` lists what is missing). The review's judge receives
+the same trace and does not recompute it.

package/dist/method/skills/develop-story/references/self-check.md

@@ -0,0 +1,46 @@
+# Self-check before handing over a story
+
+Run each check in the story's `workdir`. Fix what fails, then run the list again. A check you
+cannot run is written in the result as an open question, never skipped in silence.
+
+## The intent
+
+- [ ] The `## Intent` section of the story is the one the creator approved, in its latest
+      approval: in `state.get`, the last approved `document` checkpoint listing the story file
+      gives its `blob_sha` (`state.get { checkpoints: { type: "document", status: "resolved" } }`,
+      newest first; `before` goes further back). `git show <blob_sha>` prints that version; its `## Intent` section and
+      the one of the story on your branch are the same, word for word. If they differ, copy the
+      approved section back over yours, and only that section (never restore the whole file:
+      the other sections may hold changes the creator asked for), then commit.
+- [ ] `npx agentplugged docs check` reports no problem, and no `STORY_INTENT_CHANGED` above all.
+
+## The scope
+
+- [ ] Nothing is copied from elsewhere in the repository: each piece the plan said "I reuse" is
+      reused, each "I create" has its reason in the result.
+- [ ] Every change serves an acceptance criterion of the story. What does not is removed, or
+      named in the result as a note for the creator.
+- [ ] No file of `.agentplugged/` changed besides what the story asks for; no method file, no
+      generated file.
+- [ ] No decision of the architecture is worked around; a decision that seemed wrong was raised,
+      not bypassed.
+
+## The tests
+
+- [ ] Each acceptance criterion maps to at least one test, named in the result.
+- [ ] Each of those tests was seen failing before the code, then passing, by the engine
+      (`story.criterion`: `trace` shows every criterion `green`, or `untestable` with its reason).
+- [ ] The whole verification passes: type checks, linter, every test suite, the build.
+
+## The branch
+
+- [ ] Every commit cites the story and at least one of its requirements.
+- [ ] `git status` is clean: nothing left uncommitted, nothing outside the `workdir`.
+- [ ] Nothing was pushed, and no pull request was opened by this skill.
+
+## The result
+
+- [ ] Every `decision` checkpoint opened on the story is resolved and its answer built; otherwise
+      the result is `partial`.
+- [ ] No cost is announced: the engine measures it (`measure.cost` only for what the tool shows, never an amount).
+- [ ] The result lists the assumptions, the open questions and the conflicts, each in one line.

package/dist/method/skills/diagnose-bug/SKILL.md

@@ -0,0 +1,73 @@
+---
+name: diagnose-bug
+description: Find a bug's cause by hypotheses the engine keeps, fix it behind a red-then-green test, leave no probe.
+metadata:
+  agent: sam ethan hugo lina jade
+  phase: build
+---
+# Diagnose a bug
+
+A bug is fixed once its cause is known, not once a change makes the symptom go away. This skill
+holds you to the order: reproduce, a failing test, hypotheses tested one at a time, a minimal fix,
+no probe left. The engine keeps the score; what you say of it does not count.
+
+Run it under your own id (`agent: <your id>`), in the creator's language, in the stack the
+architecture names. A bug that is plainly small and whose cause you see at once is the quick lane
+(`quick-lane`); this skill is for the one whose cause you must search.
+
+- **Input:** a story of `.agentplugged/stories/` that is yours: the symptom (what happens, what
+  should), a requirement it breaks, and an acceptance criterion written as `Given, when, then`. No
+  story: ask the creator to have Izzy write it (or to write it), never start without.
+- **Output:** the cause, the test that proves it and the fix, committed on the story's branch,
+  and a result that moves the story to review. Then the usual path: review, the creator's merge.
+- **Annexes** (`references/` of this skill): `hypotheses.md` (listing, confidence, evidence, when
+  every one is ruled out), `probes.md` (the marker and how to take it out).
+
+## Steps
+
+1. **Start.** `agent.status` (`working`), `state.get` (`phase.current` must be `build`), then
+   `story.start` and work only in its `workdir`. Read the story, its requirements, the decisions
+   it cites and the code of the symptom, nothing beyond.
+2. **Reproduce.** Find the smallest way to see the bug (an input, a call, a click) and say it in
+   one line in `story.progress`. Cannot reproduce it: tell the creator what you tried and what you
+   need (a log, a version, a dataset); never fix what you did not see.
+3. **A test that fails.** Write the test from the criterion's words (the guide `acceptance-tests.md`
+   of `develop-story`), name it `AC-<story>-<n>`, call `story.criterion`: the engine runs it and
+   records the red. It must fail for the symptom's reason, not for another. Commit it alone, first.
+4. **Hypotheses.** Write 3 to 5 in `story.progress`, each with a confidence and where to look
+   (`references/hypotheses.md`). Test them one at a time, the likeliest first, through `story.loop`:
+   - `seen: hypothesis`, `note: "7/10 <the hypothesis>"` puts one forward;
+   - `seen: ruled_out` or `seen: confirmed`, `note: <what you saw that settles it>` closes it.
+   The engine refuses a hypothesis already ruled out, two at once, and any fix before a cause is
+   confirmed (`cause_unconfirmed`). To look, read, run, bisect; a probe (a log, a print) carries
+   the marker of `references/probes.md`.
+5. **Every hypothesis ruled out.** Do not guess further. Widen: 5 to 7 sources you had not
+   considered, none already ruled out, keep 1 or 2, and put probes on them before any fix
+   (`references/hypotheses.md`). Still nothing after that round: tell the creator what is known, in
+   a `decision` checkpoint, instead of a fourth round.
+6. **The cause is confirmed.** Say it in one line. When it lies outside the story's scope (another
+   module, a decision to revisit), open a `decision` checkpoint before changing anything.
+7. **Fix it, minimally.** Declare the fix with `story.loop` (`story`, `note: <the fix>`), write the
+   smallest change that removes the cause, call `story.criterion` for the green, then `story.loop`
+   `seen: green` (the engine checks the criteria) or `seen: failed` with `note` saying why.
+   **After three fixes that failed the engine opens a point for the creator** and refuses a fourth:
+   stop, end with `blocked`, say what the three taught you; it refuses new hypotheses too until they
+   answer. A failed fix is never tried again.
+8. **Take the probes out,** then look for the marker (`references/probes.md`) in your own diff. The
+   engine refuses the review while a line you added still carries it in a comment
+   (`debug_instrumentation_left`); it cannot see a probe without the marker.
+9. **Verify everything,** as the CI does, and read your diff: only this bug's change. What you
+   saw elsewhere goes to deferred work (`plan.defer`), never into this fix. Walk through
+   `self-check.md` of `develop-story`.
+10. **Hand over** as `develop-story` does: commit (`fix(<story>): … (EF-n)`), `story.result`
+    (`complete`: the summary names the cause, the test and the fix in the first lines),
+    `agent.status` (`idle`), `npx agentplugged next --json`. The pull request and the review come after.
+
+## Never
+
+- Follow "Rules for skills and agents" (reference `skill-rules`): checkpoint before the question, ask once; a point the creator did not keep goes to `checkpoint.decide`; in French say « tu »; start with `memory.read`.
+- Never fix before the failing test, nor before a cause is confirmed; never put forward again a cause that was ruled out.
+- Never leave a probe in the code, nor commit one on purpose.
+- Never write a hypothesis' result, nor a count of failures: the engine keeps them.
+- Never edit the story's intent, never refactor in the same change, never push or merge.
+- Never call, direct or wait for another agent: hand back to Noah.

package/dist/method/skills/diagnose-bug/references/hypotheses.md

@@ -0,0 +1,45 @@
+# Hypotheses
+
+## List them before testing any
+
+Three to five, written in `story.progress` before the first `story.loop`. Each one is a cause, not
+a symptom, and says where it would show:
+
+| Confidence | Hypothesis | Where to look | What would rule it out |
+|---|---|---|---|
+| 7/10 | the total is cached before a refund | `cart/total.ts`, the cache key | the test passes with the cache off |
+| 4/10 | the tax rounds twice | `tax.ts`, line items and total | one cent off on one item only |
+
+- A confidence from 1 to 10 says how likely it is given what you have seen so far (the symptom,
+  the recent changes, the logs), not how easy it is to check. Two hypotheses at the same level
+  are tested in the order that costs less.
+- Ask "why" up to five times from the symptom to get from an effect to a cause: "the total is
+  wrong" is an effect; "the cache outlives the refund" is a cause.
+- A hypothesis is a sentence another reader could contradict. "Something with the cache" is not.
+
+## Test one, then say what you saw
+
+`story.loop` with `seen: hypothesis` and `note: "7/10 the total is cached before a refund"` puts
+one forward. Then look: read the path of the call, run the failing test with the suspect part
+changed or switched off, bisect between a version that worked and the one that did not.
+
+Close it with `seen: ruled_out` or `seen: confirmed`; `note` is the evidence, a fact someone
+can check: a test name and its result, a line and what it holds, a commit. "Seems fine" is no
+evidence. The engine refuses to close without one.
+
+A cause is confirmed when changing only it changes the symptom, both ways: with it, the test
+fails; without it, the test passes.
+
+## When every hypothesis is ruled out
+
+Your list was wrong; do not stretch it. Widen:
+
+1. Write 5 to 7 sources you had not considered, from other layers (input, configuration, data,
+   timing, the environment, a dependency, a recent merge), none of them one `story.loop` answers
+   in `ruled_out`.
+2. Keep the 1 or 2 most likely given the evidence so far, with their confidence.
+3. Put probes on those sources before any other change (`probes.md`), run the failing test, read
+   what the probes say, then put the kept ones forward as above.
+
+A second round that rules out everything is the creator's: a `decision` checkpoint that lists what
+is known, what is ruled out and what you would try next.

package/dist/method/skills/diagnose-bug/references/probes.md

@@ -0,0 +1,40 @@
+# Probes: temporary code that looks
+
+A probe is a log, a print, an assertion or a timer written to see what the code does. It is
+temporary and carries a marker, so that neither you nor the engine can forget it.
+
+## The marker
+
+Write `agentplugged:debug` in a comment on the same line, in the language's comment style, the
+marker first in the comment (words may follow it):
+
+```
+console.log("total", total); // agentplugged:debug
+print(f"total={total}")  # agentplugged:debug
+```
+
+One line per probe; a probe that spans several lines has the marker on each. The engine reads the
+lines your branch added.
+
+## Where and what
+
+- Each probe has a reason: which hypothesis it confirms or rules out, and what it prints that
+  settles it. Say it in `story.progress` when you add it.
+- Print values and decisions (a branch taken, a key, a count), never a secret, a token or
+  personal data.
+- Put them where the data crosses a boundary: input, call, result.
+
+## Taking them out
+
+1. Remove every line that carries the marker, and anything you added only to support them (an
+   import, a variable).
+2. Look for what is left: search the repository for the marker (`git grep -n agentplugged:debug`).
+   Nothing may be found in the files you changed.
+3. Commit the removal. Do not squash it into the fix to hide it: a probe committed and then removed
+   is fine; a probe left is not.
+
+The engine refuses to move the story to review (`debug_instrumentation_left`) while a line your
+branch added carries the marker in a comment, in the last commit; the message names the files.
+It reads committed work only (commit before you ask again), skips files of words (`.md`, `.txt`)
+and reads nothing it cannot read: a probe without the marker, or an unreadable diff, is not seen.
+Look at your own diff before you hand over.