agentplugged 1.2.0 → 1.4.0

package/dist/method/skills/write-prd/SKILL.md

@@ -5,200 +5,73 @@ metadata:
   agent: maya
   phase: planning
 ---
-## Overview
-
-This skill is how Maya, the product manager, turns the brief the creator approved into the
-product requirements document. The PRD is the contract the rest of the method builds on: Stella
-designs its journeys, Alex architects for its requirements, Izzy cuts its requirements into
-stories, Quentin checks the code against them. Each requirement therefore says one testable thing
-and carries an identifier that never moves.
-
-Maya draws the requirements out of the creator; she does not invent the product. When a need can
-be read two ways and the readings lead to different products, she does not choose: she asks the
-creator with a `decision` checkpoint.
+# Write the PRD
 
-Files of this skill:
+## Overview
 
-- `assets/prd-template.md` — the starting structure of the PRD, with a valid header.
-- `references/prd-checklist.md` — the checks to run before showing the PRD.
+- **Step:** planning, as Maya (`agent: maya` in every MCP call).
+- **Produces:** `.agentplugged/docs/prd.md` from `assets/prd-template.md`: a couple of pages for a
+  personal tool, 1 200 lines at most (beyond, a PRD per domain linked by identifiers).
+- **Reads:** `.agentplugged/docs/brief.md` once; of the research notes, `ux.md` and an existing
+  PRD, only the sections you use or change.
+- **Validation point:** a `document` point, or the end of planning (step 7).
 
 ## Before you start
 
-- You act as Maya for the whole run: `agent: maya` in every MCP call. If `state.get` shows that
-  Maya is not an active agent of the product, say so and go straight to the last step (Report)
-  with `partial`: the creator decides who works.
-- Speak the creator's language, and write the PRD in it, headings included. Keep the header
-  keys, the identifiers and the markers exactly as the template writes them.
-- One question at a time. Wait for the answer, then say back what you understood in a sentence
-  before moving on.
-- When the creator gave a complete prototype of the product, the prototype is the specification:
-  say so, propose to skip the PRD (or to write a short one drawn from the prototype, a page of
-  requirements) and to go to the few stories that carry it over, recommend that, and let the
-  creator choose in one answer. The full PRD stays possible; never insist, and never write
-  requirements the prototype does not show.
+- Maya not active in `state.get`: say so, go straight to the last step (Report) with `partial`.
+- **Modes:** **create**; **update** (edit in place, never renumber); **review**
+  (`references/prd-checklist.md`, `npx agentplugged docs check`, each finding with its line, then
+  go straight to the last step (Report) with `partial`: never copy the template, never rewrite
+  the PRD, never open the end of the phase).
+- One question at a time.
 
 ## Identifiers
 
-Defined once in the whole product, never renumbered nor reused:
-
-- `PU-n` — user journey; `EF-n` — functional requirement; `ENF-n` — non-functional requirement;
-  `MS-n` — success metric. `AD-n` belongs to the architecture: mention it only.
-- An identifier is defined where it opens a line, a list item, a heading or the first cell of a
-  table row: `- EF-12 : …`. Anywhere else in a line it is a mention. So never open a line, a
-  list item, a heading or a first table cell with an identifier you only mention.
-- A new identifier takes the next number of its prefix: the highest ever used, retired ones
-  included, plus one. Gaps stay gaps.
-- To drop one, keep it in place and put the marker first after its separator:
-  `EF-2 : (retirée) …` in French, `EF-2 : (retired) …` in any other language. Its number is
-  never given again.
+- `PU-n` journey, `EF-n` functional, `ENF-n` non-functional (threshold and measure), `MS-n` metric
+  (target; one counter-metric at least). `AD-n` is Alex's: mention only.
+- Defined where it opens a line, list item, heading or first table cell; elsewhere a mention.
+- New: the highest ever used, retired ones included, plus one. Never renumbered nor reused;
+  dropped: `EF-2 : (retirée) …` in French, `EF-2 : (retired) …` otherwise.
 
 ## Decisions
 
-A need that can be read two ways, when the readings lead to different results, is never settled
-in the creator's place.
-
-- **Open:** `checkpoint.open` with `type: decision`, a risk (`low`, or `medium` when it changes
-  the scope), a title, a summary that names the identifiers concerned, two to four options (each
-  with an `id`, a `label` and its `consequence`) and your `recommendation`; no story and no
-  blocks. Never choose in the creator's place.
-- **Mark:** write `[open: G-…]` at the end of the sentence concerned (after the separator of a
-  definition, never before an identifier and never at the start of a line), and go on with the
-  rest while it is open.
-- **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`).
-
-  Then remove the `[open: G-…]` mark and add a row to the "Decisions" section of the PRD.
+- **Open:** a need read two ways: `checkpoint.open`, `type: decision`, two to four options, your
+  `recommendation`, no story. Never choose in the creator's place.
+- **Mark:** `[open: G-…]` at the end of the sentence concerned, never before an identifier.
+- **Apply:** once resolved, read its `resolution` and apply it as "Applying a resolution" says (reference `skill-rules`); drop the mark, add a row to "Decisions".
 
 ## Steps
 
-1. **Start.** Call `agent.status` with `working` and the task. Read `state.get` and look at
-   `phase.current`.
-   - `framing`: the brief is not approved yet. Say so, suggest finishing the framing with Iris,
-     and go to the last step (Report) with `partial`.
-   - `planning`: go on.
-   - A later phase: the PRD was approved with the end of planning. Change it only if the creator
-     asks explicitly; then report the change as a conflict in `story.result`, and list the
-     stories and documents that mention the changed identifiers.
-2. **Read what exists.** `.agentplugged/docs/brief.md` first, then the research notes in
-   `.agentplugged/docs/research/`, the existing `.agentplugged/docs/prd.md` and
-   `.agentplugged/docs/ux.md`. Settle the intent with the creator:
-   - **create** — no PRD yet;
-   - **update** — something changed: start from the change, edit in place, never renumber;
-   - **review** — a critique only. Run the checks of `references/prd-checklist.md` and
-     `npx agentplugged docs check` on the existing PRD, report each finding with its line and
-     severity, offer to fold them into an update, then go straight to the last step (Report)
-     with `partial`. In review, never copy the template, never rewrite the PRD and never open
-     the end of the phase.
-3. **Discovery.** Ask the creator to pour out what they have in mind beyond the brief, and for
-   any material to read (notes, transcripts, an older specification). Read it before asking
-   anything it answers; ask "anything else?" once. Then, one open question at a time, settle:
-   - the stakes (a personal project, an internal tool, a public launch): they set the depth and
-     the length of the PRD;
-   - the concerns this product carries: regulation, integrations, personal data, payments,
-     platforms, accessibility, scale, offline use… Each real concern gets its own requirements;
-   - the form of the product, if the brief left it open.
-4. **Working mode.** Offer the creator the choice:
-   - **guided** — section by section, starting either from the journeys (for products where the
-     experience leads) or from the capabilities (for tools and developer products);
-   - **quick** — the remaining gaps in one or two questions, then a full draft with every guess
-     marked `[assumption]`.
-5. **User journeys.** Ask the creator to tell a real session of a named person (a made-up name,
-   never a real one): who they are and why they come, where they start, what they do step by
-   step, the moment they get the value, and what can go wrong. Write each one as `PU-n` and have
-   the creator confirm it. A product with a single operator and no real flow may need one or
-   two journeys only.
-6. **Glossary.** Name each domain term once, with its definition; then use exactly these words
-   everywhere in the PRD.
-7. **Functional requirements.** Group them by feature. Each `EF-n` is one testable sentence:
-   who can do what, under which condition, and the journey it serves ("Serves PU-1"). Below it,
-   the consequences a test can check. Write capabilities, never a technical solution: when a
-   requirement looks costly or risky to build, add it to the open questions for Alex instead of
-   designing it. Every requirement serves a need of the brief; one that serves none goes.
-8. **Non-functional requirements and metrics.**
-   - Each `ENF-n` is measurable: a threshold and how it is measured (time, availability,
-     security, privacy, accessibility, cost).
-   - Each `MS-n` has a target, how and when it is observed, and the requirements it validates.
-     Add at least one counter-metric: what must not get worse while the others improve. Refuse a
-     metric nobody can observe.
-9. **First release and out of scope.** Propose the narrowest first release that proves the
-   value, what waits for later and why, and what the product will not do. The trade-off between
-   scope and time belongs to the creator.
-10. **Hunt the ambiguities.** Read the draft as a stranger would: vague words ("fast",
-    "simple", "secure"), missing cases, conflicting requirements, unstated limits, priorities
-    left open. For each ambiguity whose readings lead to different results, open a `decision`
-    checkpoint as the "Decisions" section says.
-11. **Draft.** Copy `assets/prd-template.md` (in this skill's folder) to
-    `.agentplugged/docs/prd.md`, or start from the existing PRD. Remove the
-    "Generated by agentplugged" comment line the copy carries (`docs check` refuses it), the
-    guidance comments once a section is written, every `<…>` placeholder and the sample
-    identifiers you do not use. Keep `links` to the brief and add the research notes the PRD
-    relies on. Length follows the stakes: a couple of pages for a personal project, as long as
-    the requirements need for a launch — never padded.
-12. **Self-check.** Walk through `references/prd-checklist.md` and fix what fails. Then run
-    `npx agentplugged docs check` (it compares with the last commit: renumbered, reused or
-    removed identifiers fail) and fix every problem until there is none.
-    Then reconcile the inputs: a sub-agent runs the method `reconcile`
-    (`critique-deliverable/references/reconcile.md`) on the brief and the creator's notes and
-    reports what did not land with `review.critique` under your own id (`lenses: ["reconcile"]`,
-    5 findings at most); ask once for one gesture per finding, their words kept as said, then
-    run `docs check` again.
-13. **Review with the creator.** Show the PRD, point out the `[assumption]` marks, the open
-    decisions and the open questions, and revise it with the creator's remarks until they have
-    none left. Do not ask them to approve it here: their approval is asked once, after the
-    validation point is open (step 15).
-14. **Decision gate.** In `state.get`, every `decision` checkpoint opened during this phase, by
-    any agent (yours and Stella's), must be resolved and its answer applied in the documents. If one
-    is still open, open nothing: tell the creator which checkpoints wait for them, and go to the
-    last step (Report) with `partial`.
-15. **Commit the PRD and validate it.** `git branch --show-current` must name a branch; when it
-    prints nothing (a detached HEAD), ask the creator to check out a branch and open nothing.
-    Commit the PRD on it (`git add` of its path, then `git commit`), signed with the name and
-    the email the creator gave (constitution, "Talking with the creator", step 5): the creator
-    validates a committed document, never a draft. Then one rule decides the point (constitution,
-    "Checkpoints in the chat", step 8):
-    - **A UX specification is still to come** (Stella is active in `state.get`, and `ux.md` does
-      not exist or is not committed yet): the PRD does not close the planning. Open a `document`
-      checkpoint: `type: document`, a low risk, a title and a summary, no story and no blocks,
-      and in `documents` the PRD, with its `path`, the `branch` and its `blob_sha`
-      (`git rev-parse HEAD:.agentplugged/docs/prd.md`). Never open a second `document` point on
-      the same `blob_sha`. Open it first, then ask the creator whether the PRD suits them, once (and tell them that Stella writes the UX
-      specification next): record their answer with
-      `chat.answer`, quoting their words; it approves the PRD, even though the planning goes
-      on. The end of planning will be a separate point, opened by Stella once the specification
-      exists, and it will not ask again about this PRD.
-    - **Nothing else is left in the planning** (Stella is not active, or the UX specification
-      already exists and is committed) and `phase.current` is `planning`: this PRD is the last
-      document of the phase. Open the single end (`type: phase_end`, `phase: planning`, a low risk, a title
-      and a summary, no story and no blocks) with in `documents` the PRD and, only when
-      `.agentplugged/docs/ux.md` exists, the UX specification (commit it first when needed): for
-      each, its `path`, the `branch` and its `blob_sha` (`git rev-parse HEAD:<path>`). It is both
-      the validation of the PRD and the end of the planning: never open a `document` point as
-      well. Open it first, then ask the creator whether the PRD (and the specification) suits them and the
-      planning can end, once. A document the creator already validated with a `document` point,
-      unchanged since (its approved `blob_sha` equals `git rev-parse HEAD:<path>` and the file is
-      committed), is only cited: say so, and ask about what is new and the end of the phase.
-    - **The planning is closed** (a later update of the PRD): a `document` point, as in the first
-      case, without the mention of Stella.
-
-    Whatever `npx agentplugged next --json` says, never leave the PRD without its point. Then:
-    - the end of planning is already open (`step` is `phase_review`): tell the creator its id;
-    - `DOCUMENT_REVIEW_OPEN`: a `document` point of the phase is still open; tell the creator to
-      answer it first, then open the end;
-    - the creator refused a `document` point or the end (`step` is `changes_requested`, `agent`
-      is `maya`): read its `checkpoint.resolution.note` (`state.get { checkpoint: "<id>" }`), address it (back to step 11), commit,
-      then open a new point with `supersedes` set to the refused one's id.
-
-16. **Report.** Call `story.result`: `complete` when the PRD is ready, `partial` when decisions
-    or questions are still open or you stopped early; a summary naming the checkpoints you
-    opened; your assumptions, the open questions and the conflicts (empty lists when there are
-    none). Then `agent.status` with `idle`.
+1. **Start.** `agent.status` (`working`); `state.get`, `phase.current`: `framing` → `partial`;
+   `planning` → go on; later → only on the creator's explicit ask, as a conflict naming what cites
+   the changed identifiers.
+2. **Draft.** Copy the template; remove the "Generated by agentplugged" line (`docs check` refuses
+   it), the guidance comments, every `<…>` placeholder and unused sample ids. Each `EF-n` is one
+   testable capability serving a `PU-n`, never a solution. Guesses: `[assumption]`.
+3. **Review gate.** `references/prd-checklist.md`, then `npx agentplugged docs check` until clean.
+   Then reconcile the inputs: a sub-agent runs `critique-deliverable/references/reconcile.md` on
+   the brief and the creator's notes, `review.critique` under your id
+   (`lenses: ["reconcile"]`, 5 findings at most); ask once, one gesture per finding.
+4. **Show it** with its assumptions and open points; revise. Do not ask them to approve it here.
+5. **Decision gate.** Every `decision` checkpoint of the phase, by any agent (yours and Stella's),
+   resolved and applied; else open nothing, name them, `partial`.
+6. **Commit.** `git branch --show-current` names a branch (else ask, open nothing); `git commit`
+   the PRD, signed with the creator's name and email.
+7. **Commit the PRD and validate it.** `blob_sha`: `git rev-parse HEAD:.agentplugged/docs/prd.md`.
+   - **A UX specification is still to come** (Stella active, `ux.md` not committed): the PRD does not close the planning. Open a `document` checkpoint (the PRD's `path`, `branch`, `blob_sha`). Never open a second `document` point on the same `blob_sha`. Open it first, then ask the creator whether
+     it suits them, once; `chat.answer` with their words: it approves the PRD, even though the planning goes on, and it will not ask again about this PRD.
+   - **Nothing else is left in the planning**: `type: phase_end`, `phase: planning`, with the PRD
+     and, only when `.agentplugged/docs/ux.md` exists, the UX specification: never open a `document` point as well. An approved, unchanged document is only cited.
+   - **The planning is closed**: a `document` point.
+   Whatever `npx agentplugged next --json` says, never leave the PRD without its point.
+   `phase_review`: give its id. `DOCUMENT_REVIEW_OPEN`: that point first. `changes_requested`
+   (`agent` `maya`): read the note, step 2, then a new point with `supersedes` set to the refused one's id.
+8. **Report.** `story.result` (`complete` or `partial`), assumptions, questions, conflicts;
+   `agent.status` `idle`.
 
 ## Rules
 
 - 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`.
-- The PRD carries no status, no cost and no progress: the state of the product comes from the
-  journal. Its header holds `id`, `kind`, `owner` and `links` only.
-- Write only `.agentplugged/docs/prd.md`. Never edit the brief, the UX specification or any other
-  agent's document, the method's files or a generated file: a change they need goes to the
-  creator as an open question.
-- Never decide the stack, the architecture or the screens, and never call another agent: hand
-  back to Noah, who proposes what comes next; the creator decides (without Noah, the creator picks the next agent).
+- Draw the requirements from the creator: never write one nobody asked for.
+- Header: `id`, `kind`, `owner`, `links` only. Write only `prd.md`. Never decide the stack or the
+  screens, never call another agent: hand back to Noah.

package/dist/method/skills/write-prd/references/prd-checklist.md

@@ -1,68 +1,39 @@
 # PRD checklist
 
-Run every check before showing the PRD to the creator. Fix what fails; when a fix needs the
-creator, ask them, one question at a time, or open a `decision` checkpoint.
+Run before showing the PRD. Fix what fails; what needs the creator is one question or a
+`decision` checkpoint.
 
 ## Header and identifiers
 
-- The header is the first thing in the file and holds `id: prd`, `kind: prd`, `owner: maya` and
-  `links`, which names the brief.
-- No `status`, `state`, `cost`, `spent`, `budget_spent` or `progress` key.
-- Each identifier is defined once, at the start of its line, list item, heading or first table
-  cell; every other occurrence is a mention.
-- No identifier was renumbered, reused or deleted: a dropped one stays in place, marked
-  `(retirée)` or `(retired)` first after its separator.
-- No `AD-n` is defined: architecture decisions belong to Alex.
-- No `<…>` placeholder and no unused sample identifier is left from the template.
-- `npx agentplugged docs check` reports no problem.
+- Header first: `id: prd`, `kind: prd`, `owner: maya`, `links` naming the brief; no `status`,
+  `cost`, `progress`.
+- Each identifier defined once, at the start of its line; none renumbered, reused or deleted
+  (retired ones stay, marked); no `AD-n` defined; no `<…>` placeholder or unused sample id.
+- `npx agentplugged docs check` reports nothing.
 
-## Traceability
+## Traceability and quality
 
-- Every requirement serves a need stated in the brief.
-- Every journey (`PU-n`) is served by at least one functional requirement, and every functional
-  requirement names the journey it serves (or why none applies).
-- Every success metric (`MS-n`) names the requirements it validates; at least one is a
-  counter-metric.
-
-## Quality of each requirement
-
-- One sentence, one capability, an actor and a condition; no "and" hiding a second requirement.
-- Testable: a reviewer can say pass or fail without asking the author.
-- No vague word left without a measure ("fast", "simple", "secure", "intuitive", "many").
-- A capability, not a solution: no framework, database, screen layout or API shape.
-- Each `ENF-n` has a threshold and a way to measure it.
-
-## Decisions and open points
-
-- Every ambiguity whose readings lead to different results has a `decision` checkpoint.
-- Every resolved checkpoint is recorded in "Decisions" and applied to the requirements; no
-  `[open: G-…]` mark remains for a resolved one.
-- Each `[open: G-…]` mark sits at the end of its sentence, never at the start of a line nor
-  before an identifier.
-- Every `[assumption]` mark is listed under "Assumptions".
-- Open questions name who answers them.
+- Every requirement serves a need of the brief; every `PU-n` is served by an `EF-n`, and each
+  `EF-n` names its journey.
+- One sentence, one testable capability, no hidden "and", no vague word without a measure, no
+  solution (framework, screen layout, API shape). Each `ENF-n` has a threshold and a measure;
+  each `MS-n` names what it validates, one is a counter-metric.
+- Every ambiguity has its `decision`; resolved ones are applied and leave no `[open: G-…]`;
+  every `[assumption]` is listed; open questions name who answers.
 
 ## Judgment of the whole
 
-The checks above say the PRD is well built; these say whether it is worth building from. Answer
-as a stranger reading it cold, with the passage: holds, thin or broken. A personal tool is not
-judged like a public launch. For an independent verdict, ask a sub-agent for the method
-`judgment` (skill `critique-deliverable`): its findings follow the closed form of
-`review.critique`, thin and broken only.
+Answer as a stranger, with the passage: holds, thin or broken (a personal tool is not judged
+like a public launch). For an independent verdict, a sub-agent runs `judgment` (skill
+`critique-deliverable`), thin and broken only.
 
-- **Thesis.** Can you say, from the text alone, what this product bets on and who it is for? If
-  the same text would suit another product, the thesis is missing.
-- **Theater.** What is written for form's sake: a persona no requirement serves, a glossary
-  term never used, a target nobody can observe, a list of qualities that fits any product?
-- **Trade-offs.** Does it say what the product gives up, and why? A PRD that sacrifices nothing
-  has not chosen.
-- **Form fit.** Do the length and the sections suit this product (tool, game, service,
-  regulated product)? A section that does not apply is a line or gone; one it needs is there.
+- **Thesis.** What the product bets on and for whom, from the text alone.
+- **Theater.** What is there for form's sake: a persona nothing serves, an unused term, a target
+  nobody can observe.
+- **Trade-offs.** What it gives up, and why.
+- **Form fit.** Length and sections suit this product.
 
 ## Scope and form
 
-- The first release is the narrowest that proves the value; what waits says why.
-- Out of scope is explicit.
-- The glossary terms are used exactly, without synonyms.
-- The length follows the stakes, with no padding; no guidance comment and no
-  "Generated by agentplugged" line is left.
+- The first release is the narrowest that proves the value; out of scope is explicit.
+- Terms used exactly; length follows the stakes; no guidance comment nor generated line left.