@celsoft/coordinator 0.0.0 → 0.1.0

package/skills/default/skills/plan-page/SKILL.md

@@ -0,0 +1,300 @@
+---
+name: plan-page
+description: "How to make a plan page, the page the plan skill requires (a document of its issue on the coordinator's bus, else a Claude artifact): a plan that reveals a design in order of importance, its approach, then its data model and mockups, then only what they leave unclear, revisited as planning goes back and forth, with a live, clickable mockup of any UI it changes, built from the repo's real UI code. Plans are written as data, plan.json, and published with this skill's renderer. Read it with the plan skill whenever you publish a plan."
+---
+
+# Plan page
+
+The `plan` skill says every change gets a plan the user approves, published as a page: on the
+coordinator's bus, one of its issue's documents; elsewhere, a Claude artifact. This skill is how that
+page is made: what a good plan says, and the page that shows it.
+
+## How a plan is built
+
+A plan reveals a design carefully. Whoever has a clear idea of the work lays it out in order of
+importance, getting each part right before spending words on the parts after it. The order is a
+priority, not a gate: planning goes back and forth, and when details show an earlier part is wrong,
+fix that part first, then return to the details. No template fixes the sections: the work decides
+them.
+
+1. **The approach first:** the title and gist state the approach, the working theory of how to do
+   the work. It stays a theory: rewrite it whenever something learned changes it, and revise
+   what rests on it to match.
+2. **Then what is not working:** today's behavior, each line saying what it costs or breaks. Leave
+   it out when the approach already makes it plain.
+3. **Then the proof:** the data model, the mockups, or both, whichever the work needs. They are
+   authoritative: every other part stays inside the boundaries they set, and when something does not
+   work inside them, change them rather than writing an exception around them. When the work
+   changes the data model, it comes first, since everything else rests on it. Get these right before the
+   details, and revisit them whenever the details show they are wrong.
+4. **Then only what is still unclear:** a behavior the data model and mockups do not make plain.
+   No section after the proof is required; stopping at the mockups is right when they say it all.
+5. **Never what the user will get:** a good design shows its own result, so a section describing
+   it only repeats the design.
+
+The smallest plan is the approach and one mockup, such as for a rename or a layout change.
+
+## Rules, then exceptions
+
+Every section, whatever it is for, states a few simple rules first, then the exceptions, each an edge
+case of the rule it bends, the way a journey shows its main line and folds its edges. Never write a
+table or grid that mixes rules and exceptions into one heuristic for the reader to work out. A design
+that needs many exceptions is a design to rethink, not to tabulate.
+
+## The data model
+
+What "data model" means depends on the work. Show only the kinds the work changes, usually one or two,
+each in its one form, so the same kind always looks the same. Show only what is new or changed, in
+plain words, and leave out what a reader would assume; never a JSON or database schema.
+
+1. **Folder structure:** a tree, one nested line per folder or file the change adds or moves, its
+   name in code and a few words on what it holds.
+2. **Where data lives:** one labelled line per place (a machine, a repo, memory, a service), saying
+   what is kept there and how it changes.
+3. **How things relate,** stored or in memory: a `diagram`, boxes for the things and an arrow for
+   each relationship, labelled with what it is and how many (`holds many`, `refers to by name`,
+   `read from`).
+4. **Data types:** one labelled line per type, its fields nested under it in plain words (`a list
+   of orgs and repos`), only the fields the change is about.
+5. **States:** a `diagram` of the states and what moves a record between them.
+
+Each form gives its rules first, then its exceptions: a tree's layout, then a short line under the
+folder an exception bends; a diagram's boxes and arrows that always hold, then each exception a
+dashed box or arrow (`exception: true`) with its note; a list's lines, then a last `Exceptions` line
+with the cases nested under it. Mark what is new or changed.
+
+## Terms
+
+1. **One term per idea:** use exactly the same term for an idea every time; no synonyms, short
+   forms, or new wording for variety.
+2. **The repo's terms as written:** where the repo defines a term (its `CLAUDE.md` or design
+   docs), use it, and never define it again; restating what the reader knows hides what is new.
+3. **Define only what is new or changing:** a new term once, where first used, marked new; a
+   changed term marked changed, saying only what changes. A shipped new term goes into the repo's
+   terms with the work.
+4. **Bold is for terms:** bold only an official term, the repo's or one the plan defines
+   (`**Profile**`), and write a word that modifies it in italics (`**Profile** *kept in a Repo*`,
+   `*shared* **Event Handler**`), so each term stands clear of its modifiers. Nothing else is bold.
+5. **Capitalized:** a term for a defined thing has every word capitalized wherever it appears,
+   prose included (`Event Handler`, `Skill Group`, `Repo`), even where the repo writes it otherwise;
+   ad hoc wording stays lowercase. Ad hoc wording is fine; the case tells the reader which is which.
+6. **Everywhere the same:** the mockups, diagrams, and captions use the plan's terms exactly as the
+   plan writes them, capitals included; a mockup's own wording that differs is changed to match,
+   never left for the reader to reconcile.
+7. **Check:** before publishing, every noun is a term the repo defines, a term the plan defines as
+   new, or plain English.
+
+## Write less
+
+1. **Plain words:** one sentence per line, no dashes, and the user's own style rules wherever they
+   have some.
+2. **Short sections:** a few lines each; cut any line that restates what the plan already shows.
+3. **Terms where used:** say what a term means in the line that first uses it, never in a glossary.
+4. **Fold** what the user can approve without.
+5. **Publish early:** publish as soon as the first parts are right, before the rest exists, and
+   republish as the plan changes.
+
+## Questions
+
+A Questions section holds only what the `plan` skill's Questions allow: specific issues that came up
+on a path the user already chose. When the user settles one, fold the answer into the part of the
+plan it changes and remove the question; the section shrinks until it is gone. A plan is how the
+work will be, never a history: no record of what was decided, asked, or ruled out.
+
+## Tools earn their place
+
+The journey, mockups, screenshots, nesting, and term rows are aids: use one when it shows what prose
+cannot.
+
+1. **Journey:** when the work moves between places (Web Page, an agent's session, GitHub) or
+   branches; a short sequence in one place reads better as labelled lines, one per step.
+2. **Mockups and screenshots:** whenever the work changes something a person sees (see Mockups).
+3. **Nesting:** when a line has parts, options, cases, fields, or a folder's contents.
+4. **Term rows:** when several new ideas are best taught side by side.
+
+## Check before publishing
+
+Read the plan top down, as the user will, and ask:
+
+1. **Stop here:** read alone, is the approach a correct picture of the work?
+2. **Order:** does the data model come before anything that leans on it, and the proof before
+   anything written after it?
+3. **Rules first:** does every section give its rules before its exceptions, with no table of both?
+4. **Earned:** does every section and line say something the plan does not already show?
+5. **Terms:** is every term the repo's own or defined here as new, used the same way throughout?
+
+Fix what fails, then publish.
+
+## The page
+
+A plan is a page made of two files, published as a document (or an artifact):
+
+1. **`index.html`:** this skill's `assets/index.html`, the renderer. Change it only here.
+2. **`plan.json`:** the plan, which you write and rewrite.
+
+```json
+{
+  "title": "Agent approval gates",
+  "eyebrow": "acme/api#agent-approval-gates",
+  "status": "Waiting for your approval",
+  "gist": "Gated agents stop and ask you before they build or land, on a prompt in their own session.",
+  "marks": {
+    "in": { "icon": "check", "color": "ok", "label": "In scope" }
+  },
+  "sections": [
+    {
+      "title": "What is not working",
+      "summary": "The lines below as one true sentence: what a reader knows if they stop here.",
+      "lines": [
+        { "label": "Plan", "text": "The agent builds as soon as it reads its task, so a wrong approach costs a whole build.", "lines": [] },
+        { "mark": "in", "text": "A plain line, led by its mark's icon, or a bullet without one." }
+      ]
+    },
+    { "title": "Choices", "summary": "...", "fold": true, "lines": [] }
+  ]
+}
+```
+
+1. **Gist:** `gist` is the approach, a string or a list of up to three strings, drawn large under the title.
+2. **Fold:** `fold: true` on a section shows its heading and summary, with its lines and journey
+   behind a toggle; `more` replaces the toggle's text. Fold what the user can approve without.
+3. **Summaries:** every section has a `summary`, one sentence saying what its lines add up to,
+   true on its own. Whenever a line changes, rewrite its summary to match.
+4. **Text:** plain text, plus `` `code` ``, `**bold**` for terms, and `*italics*` for their modifiers
+   (see Terms). Labels are set apart by color, not bold.
+5. **Nesting:** a line's own `lines` show one step further in with a rule down their left.
+6. **Marks:** a line may name a `mark`, drawn as a colored icon before its text, such as in scope,
+   out of scope, or a constraint, instead of words like "In:". Define every mark in `marks`: an
+   `icon` (`check`, `x`, `shield`, `alert`, `question`, `dot`, `arrow`, `link`, `file`, `layers`,
+   `plus`, `sparkle`, `book`, `pencil`), a `color` (`ok`, `bad`, `warn`, `info`, `muted`), and a
+   `label`; the section shows their legend. Mark every line of a section or none.
+7. **Labels:** a short `label` (one to three words, sentence case) where it helps a line scan,
+   such as choices and questions; the text says the rest without restating it.
+8. **Terms:** a line with `term` shows as three columns, its mark, the term, and its meaning, in
+   every word capitalized (`Closing Issue`, `Message [Type]`). Mark terms `new`, `changed`, or `existing` when
+   that helps: `plus`/`ok`, `pencil`/`warn`, `book`/`muted`, and removed `x`/`bad`; never `sparkle` for new.
+9. **Files:** a plan says what the user gets, never which files change; a line with `files` (paths
+   beside `text`) is for the rare plan where a file is the point. Once they approve, say in chat in
+   a few lines which layers and files you expect to touch, then build.
+10. **Diagram:** a line's `diagram` draws boxes in rows, top to bottom, with labelled arrows:
+    `{ "nodes": [{ "id", "label", "note"?, "row"?, "new"?, "exception"? }], "edges": [{ "from", "to",
+    "label", "exception"? }] }`. A node's row is its `row`, else one below whatever points to it;
+    an arrow between boxes in one row runs sideways. `exception: true` draws it dashed.
+11. **Header:** `status` is one line saying what the user is asked to do. Mark the
+    section of questions they must answer with `"ask": true`; the header adds its count and a link.
+
+## Journey
+
+A section's `journey` draws a swimlane: one lane per place the user moves between, steps running down
+in order, each a card in its place's lane.
+
+```json
+"journey": {
+  "places": [{ "id": "web", "name": "Web Page", "icon": "globe" }],
+  "steps": [{
+    "id": "plan", "title": "Plan", "place": "session", "who": "Agent",
+    "via": "the agent reads, then",
+    "does": "Stops on an approval prompt with its approach.",
+    "sees": "Approve, Change, or type a reply.",
+    "edges": [{ "title": "Free agent", "text": "Skips this prompt.", "rejoin": "build" }]
+  }]
+}
+```
+
+1. **Main line:** the steps are the path that usually happens; a step headline is a verb.
+2. **Places:** two to four lanes; icons `globe`, `phone`, `terminal`, `chat`, or any mark icon.
+3. **Cards:** `who` acts, `does` is one plain sentence, `sees` is what the user sees; no internals.
+4. **Hops:** `via` labels the move into a step, most of all when the place changes.
+5. **Branches:** an edge folds under the step it leaves from, with `rejoin` naming the step it
+   returns to, or `null` when it ends there.
+6. **Edge cases:** when the journey's edges do not make them plain, a folded section after it
+   covers what can go wrong: failure, retry, concurrency, permission, restart, and partial state, each with what the user
+   sees and how it recovers. There is no cap; leave out only what cannot happen.
+
+## Mockups
+
+Any plan whose work changes something a person sees shows the change as a live mockup: the repo's
+real UI, run on mock data, built into one HTML file the plan page frames, so the user clicks through
+what they approve instead of reading about it.
+
+1. **Real code:** build the mockup from the repo's own UI, edited in the worktree to show the
+   change, or written with the design system's kit where the UI does not exist yet. Write it as
+   real, reusable code: iterating during the plan is cheap, and that code becomes the build.
+   Keep the edits in a commit on a side branch (`<track>-mockup`) so the build starts from them;
+   the plan's branch stays untouched until the user approves.
+2. **Mock at the network:** answer the page's requests (its `fetch` calls, a socket) from mock
+   data, never by changing a component to take it. Actions need no answers by default, since the
+   flow can be assumed; answer one only when the plan is about the response itself, such as a
+   validation message or a specific behavior.
+3. **One per starting page:** a mockup covers a change and everything reached from it by
+   clicking, such as a new button's dialog or the page it opens. Make a second mockup only for a
+   change that starts on a different page, so the same page never shows twice.
+4. **One file:** inline the built page's scripts and styles with this skill's
+   `scripts/inline <page.html> <out.html>`, and save it under `mockups/` beside `plan.json`.
+5. **Each repo's recipe:** look at how the repo's UI is built and take the cheapest way that
+   fits, then write the recipe in the repo's `CLAUDE.md` so the next plan follows it:
+   1. **Bundled app** (Svelte, React, Vue on Vite or similar): build the app's real entry with a
+      small stub that answers its requests from a JSON file, then inline the build, such as a
+      repo task `mockups/build <out.html>` that the repo's `CLAUDE.md` names.
+   2. **Server pages:** render the real template on mock data, save the page, and inline it;
+      clicks do what its own scripts do.
+   3. **Not practical** (a terminal, a native app, UI that cannot draw without a live service):
+      use screenshots of the proposed screen instead (see Screenshots).
+6. **Where:** on the line of the step that teaches the change, its `mockups` a list of
+   `{ "src": "mockups/<name>.html", "kind": "after", "caption", "width": "phone" | "desktop" }`.
+   `src` may carry the page's own route (`mockups/page.html#i=...`) to open on the changed screen;
+   `width` is where it starts. Each is drawn in a frame with Phone (390px), Desktop (1280px,
+   scaled to the column), and Full size, and is commentable on its own.
+7. **A set:** put every screen of one change on one line, each with a short `label` (the screen)
+   and `text` (what to try there); the page shows them settings-style, a list of screens beside
+   the one chosen, so the user switches between them instead of scrolling a series. Full size opens
+   the whole set in the window, its list beside the screen, Desktop at the window's real width.
+
+## Screenshots
+
+A plan shows only what is proposed, never the screen as it is now: the user knows their own app. A
+screenshot is the fallback for a change where no live mockup is practical.
+
+1. **What:** the changed screen as proposed: a static copy using the app's own stylesheet, or the
+   real page edited in place and undone before building.
+2. **Widths:** phone and desktop where the layout differs.
+3. **Taking them:** Playwright in Chrome, or whatever the repo already drives its page with; save
+   each as a PNG under `screens/` beside `plan.json`.
+4. **Where:** on the line of the step that teaches the change, its `screens` a list of
+   `{ "src": "screens/<name>.png", "kind": "after", "caption" }`, each tappable full size and
+   commentable on its own.
+
+## Comments
+
+A document has no comment threads yet; the user comments in chat or on the issue. In an artifact,
+comments are the artifact's own threads; the page builds no comment UI of its own. In comment mode a tap on any line comments on it. The page anchors threads itself
+(`customAnchors`): a labelled line to `line:<section>/<label>`, so it survives reordering; a
+journey step to `step:<id>`; a screenshot to `screen:<src>`; a mockup to `mockup:<src>`; any other line by its place on the
+page. Going to a thread on a folded line opens its fold. A thread whose line is gone is left
+unplaced, in the shell's comment list.
+
+## Publish
+
+1. **Stage:** run this skill's `scripts/stage <out-dir>`, with `<out-dir>` a folder for this plan
+   in the session's scratch directory. It prints the `PAGE` and `PLAN` paths.
+2. **Write** the plan into `plan.json`, then run Check before publishing.
+3. **Publish as a document** on the bus: put each screenshot under `screens/` and each mockup under
+   `mockups/` in the stage folder, beside `index.html` and `plan.json`, and send `doc_publish` with
+   the issue, a name for this plan (`store-design`), its title, and `path` the stage folder. The
+   reply gives the link and the folder the version was kept in. The renderer reads `plan.json` beside
+   it, and the coordinator frames the page under a live header of the issue and its approval.
+   **Off the bus, publish an artifact** with the Artifact tool: `file_path` the `PAGE` path, `files`
+   `{"plan.json": "<PLAN path>"}` plus each screenshot as `"screens/<name>.png": "<its path>"`
+   and each mockup as `"mockups/<name>.html": "<its path>"`,
+   and on the first publish only `capabilities` `{"comments": {"customAnchors": true}}` and
+   `icon` `checklist`.
+4. **Link:** give the user the link; for an artifact, also say Done, tell Claude sends the comments
+   to you.
+5. **Record and ask:** record the link and ask for approval as the `plan` skill says.
+6. **Another plan:** stage a fresh folder and publish under a new name (a document) or without
+   `url` (an artifact), so a new plan gets its own link.
+7. **Later sessions:** to revise a document, copy the `folder` that `issues` lists for it into a
+   fresh stage folder, revise `plan.json`, and publish under the same name. To revise an artifact
+   after `/clear` or a resume, read the artifact, fetch
+   `plan.json` with `path: "plan.json"`, stage into a fresh folder, put the fetched `plan.json`
+   there, and publish with the artifact's `url`.