agentplugged 0.0.1 → 1.0.1

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

@@ -0,0 +1,204 @@
+---
+name: write-prd
+description: Maya's workflow for the planning phase. Write, update or review the PRD in .agentplugged/docs/prd.md from the approved brief, with stable requirement identifiers.
+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.
+
+Files of this skill:
+
+- `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.
+
+## 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.
+
+## 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.
+
+## 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.
+
+## 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`.
+
+## 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).

package/dist/method/skills/write-prd/assets/prd-template.md

@@ -0,0 +1,121 @@
+---
+id: prd
+kind: prd
+owner: maya
+links:
+  - brief
+---
+<!-- Product requirements template (skill write-prd). Copy it to .agentplugged/docs/prd.md,
+write it in the creator's language, and remove these guidance comments as each section is
+written, along with the "Generated by agentplugged" line and every <…> placeholder. Keep the
+header keys as they are; `links` names the brief and the research notes the PRD relies on.
+Never add a status, a cost or a progress to the header.
+
+Identifiers: an identifier is defined where it opens a line, a list item, a heading or the first
+cell of a table row; anywhere else it is a mention. Number each prefix in order, never renumber,
+never reuse. To drop a definition, keep it in place with the marker first after the separator,
+for example `EF-2 : (retirée) …`. The sample definitions below (PU-1, EF-1, ENF-1, MS-1) are
+placeholders: replace them, or remove those you do not use.
+
+A spot waiting for a decision checkpoint carries [open: G-…] at the end of its sentence (after
+the separator of a definition), never at the start of a line and never before an
+identifier. -->
+
+# Product requirements: <product name>
+
+## Purpose of this document
+
+<!-- One paragraph: who reads this PRD, what it builds on (the brief, research notes), and what
+comes after it (UX specification, architecture, stories). -->
+
+## Vision and goals
+
+<!-- What the product does for its users and why it matters, in a few sentences. Then the goals
+of the first release, each one tied to a success metric below. -->
+
+## Users
+
+### Who it is for
+
+<!-- The groups of users and what each one is trying to get done. -->
+
+### Not for, in the first release
+
+<!-- Who is explicitly not served yet, when the boundary is not obvious. -->
+
+## Glossary
+
+<!-- Each domain term once, with its definition. Use exactly these words everywhere else. -->
+
+- **<term>** — <definition>.
+
+## User journeys
+
+<!-- One journey per real session, told by the creator with a named (made-up) person. Below the
+definition: where it starts, the steps, the moment of value, what can go wrong. -->
+
+- PU-1 : <person> <does what>, <in which situation>.
+  - Starting point: <where they are, what they already have>.
+  - Steps: <three to five concrete steps>.
+  - Moment of value: <when and how they get what they came for>.
+  - What can go wrong: <one real failure and what they do next>.
+
+## Functional requirements
+
+### <feature name>
+
+<!-- A short description of the feature and the journeys it serves, then one requirement per
+capability: who can do what, under which condition. Below each, the consequences a test can
+check. Capabilities only, never a technical solution. -->
+
+- EF-1 : <actor> can <capability> <condition>. Serves PU-1.
+  - <a consequence a test can check>
+
+## Non-functional requirements
+
+<!-- Qualities of the whole product, each with a threshold and how it is measured: response
+time, availability, security, privacy, accessibility, cost. -->
+
+- ENF-1 : <quality> <threshold>, measured by <method>.
+
+## Success metrics
+
+<!-- Each metric: its target, how and when it is observed, the requirements it validates. At
+least one counter-metric: what must not get worse while the others improve. -->
+
+- MS-1 : <metric> reaches <target>, observed by <method> <when>. Validates EF-1.
+
+## First release
+
+### In
+
+- <what the first release covers>
+
+### Later
+
+- <what waits, and why>
+
+## Out of scope
+
+- <what the product will not do>
+
+## Decisions
+
+<!-- One row per decision checkpoint, once the creator has answered it. -->
+
+| Checkpoint | Question | Decision | Identifiers concerned |
+| --- | --- | --- | --- |
+| G-<id> | <the ambiguity> | <the option chosen, and why> | <identifiers> |
+
+## Open questions
+
+<!-- What is still unknown, who answers it (the creator, Stella, Alex) and when it must be
+settled. Spots still waiting for a decision carry [open: G-…] in the text. -->
+
+- <question>
+
+## Assumptions
+
+<!-- Every [assumption] mark of the document, gathered for the creator to confirm. -->
+
+- <assumption>

package/dist/method/skills/write-prd/evals/cases.yaml

@@ -0,0 +1,46 @@
+# How write-prd behaves. Run: agentplugged eval run write-prd --method
+# The engine's tools are not in the run: the state says what they answered, and the files are written in the folder.
+cases:
+  - id: prd-from-brief
+    state: "state.get answered: Maya is an active agent, the creator approved the brief in .agentplugged/docs/brief.md and answered every question. The engine's tools are not available in this run: make no call to them, write the document in the folder."
+    input: "Write the PRD from my approved brief."
+    files:
+      - path: .agentplugged/docs/brief.md
+        text: |
+          # Brief: Invoicely
+          For freelancers who invoice a few clients a month.
+          What it does: create an invoice from a client and lines of work; send it to the client by email;
+          show which invoices are paid and which are late.
+          What it does not do: accounting, taxes, payroll.
+          Success: a freelancer sends a first invoice in under five minutes.
+    checks:
+      - { kind: file_has, path: .agentplugged/docs/prd.md, text: "EF-1" }
+      - { kind: file_has, path: .agentplugged/docs/prd.md, text: "Invoicely" }
+      - { kind: file_lacks, path: .agentplugged/docs/prd.md, text: "TODO" }
+    rubric:
+      - "prd.md has a requirement for creating an invoice, one for sending it by email and one for showing paid and late invoices, each under its own EF-n identifier that opens its line"
+      - "prd.md has no requirement about accounting, taxes or payroll, which the brief leaves out"
+      - "Each EF requirement says one thing that a test could check, with no 'and' joining two behaviours"
+      - "prd.md carries the five-minute first invoice as a measurable success metric (an MS-n identifier)"
+  - id: prd-ambiguous-need
+    state: "state.get answered: Maya is an active agent. The engine's tools are not available in this run: make no call to them, write in the folder. The creator is away: do not wait for an answer."
+    input: "Update the PRD: add that invoices should be 'sent automatically'."
+    files:
+      - path: .agentplugged/docs/prd.md
+        text: |
+          # PRD: Invoicely
+          - EF-1: The freelancer creates an invoice from a client and lines of work.
+          - EF-2: The freelancer sends an invoice to the client by email.
+    checks:
+      # The requirements already written keep their number and their text, whatever else happens.
+      - { kind: file_has, path: .agentplugged/docs/prd.md, text: "EF-1: The freelancer creates an invoice from a client and lines of work." }
+      - { kind: file_has, path: .agentplugged/docs/prd.md, text: "EF-2: The freelancer sends an invoice to the client by email." }
+    rubric:
+      - "The answer or the PRD says that 'sent automatically' can be read two ways (for example on creation, or on a due date) and does not pick one as if the creator had said it"
+      - "If a new requirement was written, its identifier is EF-3 and EF-1 and EF-2 keep their number and their text"
+triggers:
+  - { query: "write the PRD from the approved brief, with stable requirement identifiers", should_trigger: true }
+  - { query: "update the PRD: add a requirement for exporting invoices", should_trigger: true }
+  - { query: "review the PRD and its requirement identifiers", should_trigger: true }
+  - { query: "write the product brief from my idea", should_trigger: false }
+  - { query: "turn the approved requirement list into stories", should_trigger: false }

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

@@ -0,0 +1,68 @@
+# 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.
+
+## 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.
+
+## Traceability
+
+- 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.
+
+## 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.
+
+- **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.
+
+## 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.