@clemrig/factory 0.19.0 → 0.21.0

package/templates/skills/issue/SKILL.md

@@ -19,18 +19,76 @@ description of the need. Once the operator agrees, save the issue (see Save).
 
 1. Read the repository's agent instructions (`AGENTS.md` at the root and in the directories concerned) and the
    relevant code. Change nothing.
-2. Ask the operator questions, a few at a time, until you can fill every section without inventing anything.
+2. When the operator built a prototype for this need (they say so, or the issue names one), it is what they
+   validated: write the spec from it, not from what you would design, and ask only about what it leaves open.
+   - It must be committed, its notes included (a `PROTOTYPE.md`, say), on a branch named with a slash, such as
+     `prototype/<slug>`, and pushed: if it is not, ask the operator to do it, or to let you do it there. The spec
+     names that branch and the full id of the commit they validated (see Format).
+   - Read it at that commit, before asking anything: its notes, what it changed (`git diff HEAD...<commit>`) and
+     its screens. To run it, add a working tree of that commit outside the repository
+     (`git worktree add --detach <folder> <commit>`, removed once done) and start it as the repository's
+     instructions say, or ask the operator where it already runs; never switch branches in the repository.
+3. Ask the operator questions, a few at a time, until you can fill every section without inventing anything.
    Do not ask what the code or the docs already answer. For each question, give its practical consequence
    and your recommendation.
-3. Ask whether the issue relies on another issue that must be delivered first: its spec assumes behavior that
+4. Ask whether the issue relies on another issue that must be delivered first: its spec assumes behavior that
    issue brings. List the issues of `.factory/issues/` that look related, with whether each is delivered (its
    `plan.md` is on the main branch), and record the operator's answer in Dependencies.
-4. Describe what and why, never how: the run that implements the spec plans the technical work itself.
-5. Propose the complete spec and wait for the operator's agreement, then save it (see Save).
+5. Describe what and why, never how: the run that implements the spec plans the technical work itself.
+   Where you chose between real alternatives, write the one you recommend: the presentation shows the others.
+6. Propose the complete spec and wait for the operator's agreement, then save it (see Save).
+7. Present it for the operator to validate it on its page (see Present).
 
 Other issues in `.factory/issues/` are history, not the current truth: rely on the code and the docs, and read
 them only to find the issues this one depends on.
 
+## Present
+
+The spec page of `factory ui` (`spec?issue=<slug>`, linked from the issue's card) shows the spec as a deck of
+cards the operator answers one by one. Write its presentation, in the spec's language and in plain words, as a
+JSON draft outside the repository, then save it with `--kind page` (see Save):
+
+```json
+{
+  "need": "<the problem and why it matters, for someone who has not read the spec>",
+  "changes": [{ "title": "<a few words>", "text": "<what changes, for whom, why>", "mockup": <optional> }],
+  "decisions": [{
+    "id": "<id>", "title": "<the question>", "why": "<what the answer changes>",
+    "options": [{ "id": "<id>", "title": "<a few words>", "text": "<what it does, what it costs>" }],
+    "chosen": "<the id of the option the spec takes>"
+  }],
+  "criteria": [{ "title": "<what they check together>", "criteria": [
+    { "id": "AC1", "plain": "<the criterion in plain words>", "check": "<how it will be checked, on what>" }
+  ] }],
+  "outOfScope": ["<what the spec leaves out, in plain words>"]
+}
+```
+
+- One change per part of the scope a person would judge on its own; `text` in a few sentences, `**bold**` and
+  `` `code` `` allowed.
+- A mockup only for a change that brings or changes an interface. When the spec's prototype shows it, capture it,
+  never draw it: the operator validated that screen. Run the prototype at the spec's commit (see Specify), open the
+  state the change describes in a browser (`.factory/node_modules/.bin/playwright-cli`, which `factory init`
+  installs: run it with `--help` first, or the browser tools you have) and save a screenshot (PNG, JPEG or WebP,
+  2 MiB at most) beside the draft, outside the repository; give its absolute path,
+  `{ "caption": "…", "image": "<path>" }`, and `issue-save` keeps the image beside the spec. When you cannot run
+  the prototype or take the screenshot, ask the operator for it. Capture again whenever the spec names another
+  commit. Only an interface the prototype does not show is drawn:
+  `{ "caption": "…", "html": "<a whole HTML document>", "width": <320–1600>, "height": <200–4000> }`, shown in a
+  frame without script, network or anything but its own HTML and inline styles: no `<script>`, no link to a
+  stylesheet, a font or an image (draw them, or use `data:` images); under 256 KiB. Reproduce the application's
+  existing pages and components from its code and styles and mark what is new; invent no component, text or state
+  that neither the application nor the spec has.
+- A decision for each choice where the spec took one of real alternatives (2 to 5 options), the one it took as
+  `chosen`; none when there was nothing to choose. An `<id>` starts with a lowercase letter, then lowercase
+  letters, digits or hyphens, 40 characters at most.
+- Every acceptance criterion of the spec exactly once, grouped by what a person checks together.
+
+`factory run issue-save` checks the draft against the saved spec and keeps it with the spec it presents: once
+the spec changes, the page says it is stale, so save a new presentation after saving a new spec. When the
+operator brings back the page's message (the cards they sent back, their notes, the options they took instead),
+update the spec with them, save it, then present it again.
+
 ## Fix a refused spec
 
 When `factory run implement` refuses to start because of the spec (a missing section such as Dependencies, a
@@ -71,29 +129,43 @@ delivered is either delivered first or removed from the spec, as the operator de
 
 ## Dependencies
 - <slug of an issue that must be delivered first>
+
+## Prototype
+- Branch: <the prototype's branch>
+- Commit: <the full id of the commit the operator validated>
 ```
 
-- Exactly these six sections, in this order, with nothing between the title and the first one.
+- Exactly these six sections, in this order, with nothing between the title and the first one; then Prototype,
+  only when the spec draws on a prototype, and left out otherwise.
 - No section is empty: write `None.` when there is nothing to say.
 - Acceptance criteria contains only `- AC<n>: <criterion>` items, numbered from AC1 without gaps; an indented
   line continues the criterion above it. Each criterion is a fact that a user, an API client or an operator
   can check, not an implementation detail.
 - Dependencies contains only `- <slug>` items, each an issue of `.factory/issues/` other than this one, or
   `None.`: the run refuses to start until each of them is delivered.
+- Prototype contains `- Branch: <branch>` then `- Commit: <full commit id>`: the commit the operator validated,
+  as `git rev-parse` prints it, on a branch named with a slash, which no run takes, and which origin holds. The
+  runs read the prototype at that commit and refuse to start without it: keep the branch until the issue is
+  delivered, and never rewrite it (commits added on top are fine). To draw on another commit, have the operator
+  validate it, then save the spec and its presentation again.
 - Headings stay in English; the content may be in any language.
 
 ## Save
 
 1. Write the draft to a new file outside the repository, for example in a directory created by `mktemp -d`.
 2. From the repository, run
-   `factory run issue-save --issue <slug> --kind issue --file <absolute path>` for `issue.md`, or
-   `--kind spec` for `spec.md`.
-3. `Saved .factory/issues/<slug>/<kind>.md` means it is done. Otherwise the command lists every problem: fix
-   the draft and run it again. It refuses a spec whose issue does not exist yet, and a
-   dependency that is no issue of the repository.
+   `factory run issue-save --issue <slug> --kind issue --file <absolute path>` for `issue.md`,
+   `--kind spec` for `spec.md`, or `--kind page` for the spec's presentation (`spec-page.json`).
+3. `Saved .factory/issues/<slug>/<file>` means it is done. Otherwise the command lists every problem: fix the
+   draft and run it again. It refuses a spec whose issue does not exist yet, a dependency that is no issue of the
+   repository, a prototype origin does not hold, and a presentation that does not present the saved spec or whose
+   capture is no image. Each saved file is named, the captures folder included.
 
 ## Boundaries
 
-Never write in `.factory/issues/` directly, never commit, and never run `factory run implement`. When the spec
-is saved, tell the operator the next steps: review it, commit it and push it on the main branch, then run
-`factory run implement --issue <slug>`.
+Never write in `.factory/issues/` directly, never commit in the repository (a prototype is committed on its own
+branch, by the operator or with their leave), and never run `factory run implement`. When the spec and its
+presentation are saved, tell the operator the next steps: validate it on its page in `factory ui` (the Spec link
+of the issue's card), commit the spec, its `spec-page.json` and its captures (`spec-page/`) and push them on the
+main branch, then run `factory run implement --issue <slug>`. A prototype's branch stays until the issue is
+delivered; its pull request then says whether it can be removed.