@celsoft/coordinator 0.0.0 → 0.1.0

package/skills/extra/skills/plugin-authoring/SKILL.md

@@ -0,0 +1,317 @@
+---
+name: plugin-authoring
+description: "MUST READ before creating or restructuring a skill collection, a Claude Code plugin, or a marketplace; before adding a skill to one; or when deciding whether a rule belongs in your own collection or upstream in a base one. Covers the two distribution models (portable skills collection vs Claude Code plugin) and how to choose, portability rules, structure, naming, the base-layer/modifier model, the two authoring disciplines (no preflighting the happy path, shell in bundled scripts), local development, and version bumps. For the format of an individual SKILL.md file, read `skill-maintenance`."
+---
+
+# Skill collection, plugin, and marketplace authoring
+
+These are the conventions for packaging skills for distribution. They live in a **skill**,
+not a repo's `CLAUDE.md`, on purpose: a `CLAUDE.md` is only visible inside its own repo, so
+conventions kept there get restated (and then drift) in every other repo. A skill is visible
+everywhere it is installed.
+
+Companion: **`skill-maintenance`** owns the format and lifecycle of an individual
+`SKILL.md`. This skill owns everything around it.
+
+## Pick a distribution model first
+
+| | **Skills collection** (default) | **Claude Code plugin** |
+| --- | --- | --- |
+| Layout | `skills/<skill>/SKILL.md` at repo root | `plugins/<plugin>/skills/<skill>/SKILL.md` |
+| Install | `npx skills add <owner>/<repo> -g` | `/plugin install <plugin>@<marketplace>` |
+| Reaches | Claude Code, Cursor, Codex, and 70+ others | Claude Code only |
+| Carries | skills | skills, commands, agents, hooks, MCP servers |
+| Versioning | none; installs current `HEAD` | semver in `plugin.json`, version-keyed cache |
+| Org push | none; each person installs | managed scope via server settings |
+
+**Default to a skills collection.** Choose a plugin only when you need something a
+`SKILL.md` cannot carry (commands, agents, hooks, an MCP server) or you need managed-scope
+org rollout. Everything from [Naming](#naming) onward applies to both.
+
+A repo can be both: put `skills/` at the root and add `.claude-plugin/` alongside it with a
+plugin whose `source` is `./`. One layout, both install paths, no conditionals.
+
+### The bootstrap plugin pattern
+
+Use this when an org must push skills to everyone automatically **and** some of those people
+want the skills in other agents too.
+
+**What this is not for.** A managed-scope plugin *can* be updated: members pick up a new
+version through `/plugin` in Claude Code. Do not reach for this pattern because you believe
+managed delivery is frozen; it is not. (`claude plugin update` does refuse at managed scope,
+erroring *"not installed at scope user"*, which is easy to misread as a hard limit. `/plugin`
+is the control.)
+
+**What it is for:** a plugin reaches Claude Code and nothing else. When part of your audience
+works across Cursor, Codex, or anything else reading the Agent Skills spec, that half needs a
+portable collection. So ship a small plugin that installs the collection and hands off.
+
+```
+.claude-plugin/marketplace.json     # catalogs one plugin
+plugin/                             # pushed by managed settings
+  skills/<trigger-skill>/           # installs the collection, then hands off
+skills/                             # the portable half; updates by pushing
+  <prefix>-<topic>/
+```
+
+Split by **who needs portability**, not by topic. Content that only ever runs in Claude Code
+can live in the plugin; anything an engineer might want in another agent belongs in the
+collection.
+
+Rules:
+
+1. **The bootstrap names no individual skill** beyond one fixed probe per collection, pins no
+   version, and holds no list. Installing is `--skill '*'`.
+2. **Keep the plugin half small.** Everything in `skills/` updates by pushing; the plugin half
+   needs a version bump and a `/plugin` update on each member's machine.
+3. **Mark every plugin skill `metadata.internal: true`**, or the skills CLI will also install
+   it flat, colliding on its bare name and duplicating the copy the plugin provides.
+4. **Probe for a SKILL, never for a plugin.** A plugin can be present while providing
+   pre-rename names, so "the plugin is installed" proves nothing about what is usable.
+5. **Probe the plugin cache too**, so a legitimately plugin-provided skill suppresses the flat
+   install rather than producing a second copy.
+6. **No transition-era cleanup in the plugin.** Migration notes belong in a doc you can edit.
+
+**Changing an executable file in the plugin** makes the admin console flag the marketplace
+with *"Review it before members use it"*. That is advisory: it offers only a read-only
+**View files**, there is no approve button, and nothing needs clearing.
+
+If the collection is in a **private** repo, order matters: install the public base layer
+first, verify git can read the private one (`git ls-remote`), and only then install it.
+Signal "not authenticated yet" with a distinct exit code so the caller can route through the
+GitHub setup skill and resume.
+
+## Portability rules (both models)
+
+A skill that assumes Claude Code silently breaks everywhere else. These are not style
+preferences:
+
+1. **Strict YAML frontmatter.** Claude Code's parser is lenient; every other agent's is not,
+   and an unparseable skill is *silently skipped*. Quote any description containing `: `.
+   See `skill-maintenance` for the rule and the check.
+2. **Cross-reference by the skill's full directory name.** Write
+   `` the `secrets` skill ``, never `toolkit:secrets`: that `<plugin>:<skill>`
+   form is a Claude Code plugin namespace and means nothing to any other agent. The
+   reference is prose the model resolves, not a link.
+3. **No `${CLAUDE_PLUGIN_ROOT}`.** Reference bundled scripts relative to the skill: "run this
+   skill's `scripts/zsh-fragment`".
+4. **`name` must equal the directory name.** Installers install by directory.
+5. **Claude-only features must degrade.** `context: fork` and hooks are Claude Code only;
+   `allowed-tools` is portable.
+
+## Structure (plugin model)
+
+```
+.claude-plugin/
+  marketplace.json            # catalog: names the marketplace, lists plugins by relative path
+plugins/
+  <plugin>/
+    .claude-plugin/
+      plugin.json             # this plugin's manifest
+    skills/
+      <skill>/
+        SKILL.md
+        scripts/              # bundled executables, run in place
+```
+
+1. **Manifests only in `.claude-plugin/`.** *Only* `marketplace.json` and `plugin.json` go
+   there. Everything else (`skills/`, `commands/`, `agents/`, `hooks/`, `.mcp.json`) sits at
+   the plugin root and is auto-discovered.
+2. **`source` paths are repo-relative** (`./plugins/toolkit`). Relative sources are what let
+   one manifest serve both a local-path install and a hosted one.
+3. **Validate before publishing:** `claude plugin validate <plugin-or-marketplace-path>`.
+
+**Contracts to keep in sync.** Each of these names appears in more than one place, and all
+copies must agree:
+
+| Name | Appears in |
+| --- | --- |
+| Marketplace name | `marketplace.json`, every `<plugin>@<marketplace>` reference, install commands |
+| Plugin name | its `plugin.json`, its `marketplace.json` entry, install/uninstall commands |
+| Relative source | `marketplace.json`, and must resolve from the marketplace root |
+
+## Naming
+
+- **Namespace the plugin.** A plugin name carries its owner or org as a prefix. That prefix
+  is the collision-avoidance mechanism, so never publish a bare, unprefixed plugin name.
+- **Split plugins by audience, not by topic.** Who installs it is the axis; a topic is a
+  skill inside a plugin, not a plugin of its own. Add a new plugin only when a distinct
+  group needs a distinct install set.
+- **In a collection, prefix every skill directory with the collection's name**
+  (`<prefix>-deploy`, `<prefix>-git-workflow`). A flat install shares one global namespace
+  across every collection the user has, and installing a same-named skill from anywhere
+  else **silently overwrites** the existing one: no warning, no prompt, and `skills list`
+  records no provenance to trace it afterwards. The prefix is the whole defence.
+- **In a plugin, the plugin supplies the namespace.** Skills are invoked as
+  `/<plugin>:<skill>`, so name a skill for what it covers (`git`, `deploy`) rather than
+  repeating the plugin. Split into topic-qualified names (`git-commit`, `git-clone`) only
+  when a skill actually splits.
+- **Name a modifier after the skill it modifies**, so the pairing is obvious at a glance.
+
+## Layered marketplaces: base layers and modifiers
+
+A marketplace often sits **on top of** another one: a company marketplace over a personal
+toolkit, a team's over the company's. When it does, name the base layer explicitly and
+follow these rules.
+
+**The base layer wins every conflict.** If a base skill and an overlay skill disagree, the
+base is right and the overlay is the bug. An overlay that quietly contradicts its base is
+worse than no overlay, because both look authoritative.
+
+**Never fork a base skill.** A copy drifts, and then the two contradict each other while
+each looks maintained. Two legitimate options only:
+
+- The behavior is **generic** (it would be just as correct anywhere else): it belongs in the
+  base layer. Contribute it upstream.
+- The behavior is **specific** to your context: keep it, as a modifier.
+
+**Apply the rule/fact test.** This is the question that decides where something goes:
+
+- A **rule** is how work gets done: commit conventions, install methods, safety
+  requirements, file layouts. Rules are almost always generic. They belong upstream, even
+  when you discovered the need for them locally.
+- A **fact** is a value that is true of your context and false elsewhere: an org name, an
+  email domain, an account, a vault, a repo list, a provisioning step.
+
+An overlay marketplace should trend toward **facts only**. If yours is accumulating rules,
+they are candidates for upstream, not for local special-casing.
+
+**A modifier is a modifier, not a replacement.** It names its base skill, defers to it for
+the procedure, and states only what changes. Restating the base procedure *is* forking it.
+
+```markdown
+---
+name: <topic>
+description: <Context>-specific <topic> rules. Read AFTER <base>:<skill>, which owns the
+  procedure; this only adds the deltas. <when to load>
+paths:
+  - "**/<Org>/**"
+---
+
+# <Topic> deltas
+
+**Base skill: `<base>:<skill>`.** Follow it for the full procedure. This file records only
+where things differ. If the two conflict, the base wins and this file is the bug.
+```
+
+**Scope repo-specific guidance with `paths`.** It is a supported frontmatter field taking a
+list of globs; the skill auto-loads only when the work touches a matching path. Use it for
+guidance that is **repo-scoped** (project conventions, per-repo layouts). Do **not** use it
+on **machine-scoped** setup skills (onboarding, installing a CLI, signing into an account):
+those run once, often from a home directory with no repo in sight, and a glob would stop
+them loading exactly when needed. Gate those on their `description`.
+
+**Install the base layer first.** If an overlay's skills defer to a base, nothing else is
+meaningful until the base is installed. An onboarding flow should install it as its first
+real action.
+
+## Setup versus day-to-day: do not preflight the happy path
+
+**Prerequisites are handled during setup. Day-to-day operations assume setup is done and
+just run the command.** A skill must not gate everyday work behind a
+verify/preflight/connectivity check "before every command": that friction is the thing to
+avoid.
+
+- **Setup flows** own installs, logins, connectivity, and the idempotent repairs for them.
+- **Day-to-day usage** just runs the command. A new shell has already sourced the profile,
+  so the tool is on `PATH`. No pre-check.
+- **On failure, then diagnose.** Only when a command actually fails (not found, not
+  authenticated, session unavailable) run the skill's `doctor` and repair, then retry. Frame
+  a diagnosis script as the failure path, never the default path.
+- **The one exception is a silent-correctness guard with no failure signal**, such as
+  checking commit identity before committing, where a wrong value does not error. Keep those
+  only when the check is instant and nothing else catches the mistake.
+
+So a skill's `description` should trigger it for *setup* or *on failure*, not "before every
+`X` command".
+
+## Shell goes in bundled scripts, not in SKILL.md
+
+Keep complex shell **out** of the markdown. Anything beyond a trivial one-liner (preflights,
+installs, config writes, verification, key generation) lives as an executable in the skill's
+`scripts/` directory, and the `SKILL.md` tells the model to run it by name. A named script
+keeps the permission prompt a clean "run `scripts/<name>`", makes the logic reviewable and
+testable, and stops the model re-emitting variable ad-hoc bash that trips approval
+classifiers.
+
+- **Shape:** `skills/<skill>/scripts/<name>`, no extension, `#!/usr/bin/env bash`,
+  `set -euo pipefail`, `chmod +x`.
+- **Invocation:** refer to it as "this skill's `scripts/<name>`" and let the model resolve
+  the path. Do not hardcode a path that breaks either plugin mode or local dev.
+- **Idempotent:** check before installing or writing, and skip work already done, so
+  re-running a skill is always safe. Report `NOCHANGE` when there was nothing to do.
+- **Read-only diagnosis:** a `doctor` script prints one `KEY: VALUE` fact per line so the
+  caller can branch without parsing prose, and changes nothing.
+- **Protected-path writes** (`~/.zshrc`, `~/.ssh/config`) still go in a script, but keep the
+  "announce the write before running it" prose in the `SKILL.md` so the approval prompt is
+  expected rather than surprising. Do not try to engineer around a denial: in auto-accept
+  mode a classifier stands in for the absent human, and that denial is the guardrail working.
+- **Trivial contextual one-liners** (a single `git config`, `op --version`) stay inline. Do
+  not over-script.
+- **Target bash 3.2.** macOS still ships it, so no `mapfile`, no associative arrays, no
+  `${var^^}`. A script that only runs under bash 4 fails on the most common target.
+- **Scripts run in place.** Do not install a skill's internal scripts to `~/.local/bin`: a
+  plugin-owned script that also sits on `PATH` has two owners, and the `PATH` copy goes stale
+  the moment the plugin updates. The exception is a genuinely **user-facing command**, one a
+  person types in a terminal, since a version-keyed plugin cache path is not typeable. Such a
+  command is then owned by the plugin, so a dotfile manager must not manage it too.
+
+## Local development
+
+For a **skills collection**, install straight from the working copy: a local path source
+needs no commit, push, or version bump:
+
+```
+npx skills add "$PWD" --skill '*' -g -y
+```
+
+The symlink approach below also works, and is what to use inside the collection's own repo.
+
+For a **plugin**, skills under `plugins/` are only discovered once the plugin is installed from a marketplace,
+which would mean publishing on every edit. Instead, symlink each skill into `.claude/skills/`
+so Claude Code discovers it straight from the working tree:
+
+```
+.claude/skills/<skill> -> ../../plugins/<plugin>/skills/<skill>
+```
+
+Use **relative** link targets so a fresh clone stays valid, keep the directory **gitignored
+and generated** (never hand-edited or committed), and rebuild it with a script that scans
+`plugins/*/skills/*` (or `skills/*` in a collection). Locally these resolve to the bare
+`/<skill>` command; a plugin's installed form is `/<plugin>:<skill>`, and the two coexist
+without collision.
+
+This tests a skill's **content**, the same `SKILL.md` the plugin ships. It does **not**
+exercise the namespaced command, plugin-bundled hooks or MCP, or the install flow. For those,
+test the plugin somewhere it is not force-enabled by managed settings.
+
+> A `--plugin-dir` dev copy cannot override a plugin that managed settings force-enable; the
+> CLI errors instead. Project-skill discovery is a separate mechanism and is unaffected. The
+> exception is the managed setting `strictPluginOnlyCustomization`, which blocks user and
+> project skills entirely; where it is set, local dev needs a skills-directory plugin or an
+> admin exception.
+
+## Bump the version on every change (plugin model only)
+
+**Bump the plugin's `version` in `plugin.json` in the same commit as the change.** The plugin
+cache is version-keyed, so `claude plugin update` is a no-op when the version has not moved:
+an unbumped change simply never reaches anyone. Patch for fixes and docs, minor for a new or
+removed skill.
+
+A **skills collection has no version and no cache:** an install resolves current `HEAD`, so
+there is nothing to bump and no way for an edit to go stale.
+
+## Adding a skill
+
+**Step 0 is a gate.** If you are working in an overlay marketplace, check the base layer
+first: list its skills and read any that touch the same topic. If it already covers this,
+use its skill. If it *should* cover this because the behavior is generic, contribute it
+upstream. Only a genuine context-specific delta continues.
+
+1. Create the `SKILL.md` (see `skill-maintenance`): `skills/<skill>/SKILL.md` in a
+   collection, `plugins/<plugin>/skills/<skill>/SKILL.md` in a plugin.
+2. Add `paths` if the guidance is repo-scoped; omit it for machine-scoped setup.
+3. Regenerate the local-dev symlinks.
+4. Verify it parses for a strict reader: `npx -y skills add "$PWD" --list`.
+5. Plugin model only: bump the plugin version, then `claude plugin validate` the plugin and
+   the marketplace.

package/skills/extra/skills/project-conventions/SKILL.md

@@ -0,0 +1,64 @@
+---
+name: project-conventions
+verified: 2026-10-31
+description: "MUST READ whenever a new project or repo is created or scaffolded, and whenever the user asks for a project to follow good code conventions. Ensures the project has a CLAUDE.md and that it carries the standard conventions section, creating the file if missing and merging into it if present."
+---
+
+# Project Conventions
+
+This skill makes sure a project's `CLAUDE.md` exists and carries the standard
+[conventions](#the-conventions), so every later session in that project follows them.
+
+## When to apply
+
+- **New project.** Right after creating or scaffolding a repo or project directory, before
+  the first commit.
+- **On request.** The user asks for a project to follow good conventions, best practices,
+  or "our conventions".
+
+Do it without asking: the user wants the file in place, not a discussion of it.
+
+## Apply it
+
+1. **Find the project root.** The git toplevel if there is one, else the directory just
+   created.
+2. **No `CLAUDE.md`.** Create it with a `# CLAUDE.md` heading, one line saying what the
+   project is (from the conversation, or the directory name if there is nothing else), then
+   the conventions section below verbatim.
+3. **`CLAUDE.md` exists.** Read it first. Then:
+   - No `## Code conventions` section: append the section below.
+   - Section present: add only the bullets it is missing. Never reword, reorder, or delete
+     what is already there, since the repo may have deliberately diverged.
+   - A rule in the file contradicts one below: keep the file's rule and tell the user about
+     the conflict in one line.
+4. **Commit.** Follow the `git-workflow` skill. In a new project, fold `CLAUDE.md`
+   into the first commit rather than a separate one.
+
+Re-running this skill on a project that already has every convention changes nothing.
+
+## The conventions
+
+Copy this section into the project's `CLAUDE.md`:
+
+```markdown
+## Code conventions
+
+- **Design:** design and change code as deep modules: small interfaces hiding a lot of
+  behavior, each with one responsibility, no logic written twice.
+- **Commits:** commit each finished change as you go, without asking; push only after
+  showing every unpushed commit and getting approval, per the `git-workflow` skill.
+- **Tools:** pin every tool version in this project's `mise.toml` and run tools through
+  mise, following the `mise-usage` skill. Install nothing globally (`brew`,
+  `npm -g`, `pip --user`, `uv tool`, `go install`) unless mise cannot provide the tool, and
+  then say why.
+- **Tasks:** write automation as mise file tasks under `mise-tasks/`, never as tasks in
+  `mise.toml` and never as standalone shell scripts unless a mise task cannot do the job.
+  Group related tasks into folders, so `mise-tasks/db/migrate` runs as `mise run db:migrate`.
+- **Running things:** at the start of a session run `mise tasks` to learn every task, and
+  use a task over the equivalent raw command whenever one exists. Never run `mise exec`;
+  when a command needs the mise environment
+  (tools, env vars, `.env`), write a mise task for it and run that.
+```
+
+The `Commits` line is the opt-in the `git-workflow` skill looks for. Keep its
+wording exact.

package/skills/extra/skills/questions/SKILL.md

@@ -0,0 +1,156 @@
+---
+name: questions
+description: "MUST READ whenever you and the user are working toward a decision about one specific topic and there are many things to consider: several questions, concerns, findings, options or tradeoffs you would otherwise list in chat. A single question stays in chat. Not for planning. Publishes the items to a Claude artifact where the user weighs each one's pros and cons, then approves or comments, reads the answers back, and removes each item once it is settled and recorded."
+verified: 2026-10-28
+---
+
+# Questions
+
+When you are working toward a decision about one specific topic and have many things for the
+user to consider, put them on a page instead of listing them in chat:
+
+- **Use it for:** several questions, concerns, findings, options or tradeoffs that each need the
+  user's call, including the ones you turn up while answering something else.
+- **Not for one question:** a single question stays in chat.
+- **Not for planning:** plans follow their own process.
+
+Each item is a panel with its proposal, a Pros and a Cons section, an Approve checkbox, and a
+comment box to change it or ask about it. One page per topic, kept for as long as the topic has
+open items.
+
+The page is a Claude artifact made of two files:
+
+1. **`index.html`:** this skill's `assets/index.html`, a renderer that never changes.
+2. **`questions.json`:** the open items, which you write and rewrite.
+
+Answers live in the artifact's database, collection `responses`, one document per item id:
+`{ approved, comment, updatedAt }`.
+
+## questions.json
+
+```json
+{
+  "title": "Auth Decisions",
+  "problem": "Sessions expire mid-task, and people lose unsaved work.",
+  "intro": "Tick to approve as written; comment to change it or ask.",
+  "groups": [
+    {
+      "title": "Sessions",
+      "note": "Optional text under the group heading.",
+      "items": [
+        {
+          "id": "session-length",
+          "title": "Sessions last 30 days",
+          "proposal": "Keep a session for `30` days, renewed on use.",
+          "why": "Why this question is being asked at all: the problem or event that raised it.",
+          "versus": "What it is weighed against: today's behavior, or the option it competes with.",
+          "pros": ["Each point one short sentence."],
+          "cons": ["An empty list shows None."],
+          "reply": "Optional: which comment this item came from, and your answer."
+        }
+      ]
+    }
+  ]
+}
+```
+
+- **`problem`:** required; the one problem the whole page exists to solve, in the user's terms,
+  shown above every item. Keep it current: when settling shrinks or changes what is left, rewrite
+  it to the problem the remaining items still solve, so the user never loses the plot.
+- **`id`:** kebab-case, unique, and never reused for a different question, since answers are
+  keyed by it.
+- **Text:** plain text, plus `` `code` `` and `**bold**`; nothing else is rendered.
+- **One concern per item:** break the topic into every separate question, concern, finding or
+  option, and give each its own item with its own proposal. Never fold several concerns into
+  one item as its pros and cons.
+- **One decision per item:** a proposal the user can approve with one tick. Split anything
+  that needs two answers.
+- **Why it came up:** every item has `why`, saying which part of `problem` it solves, and the
+  finding or request that raised it, so the user never wonders why it is being considered. It sits
+  above the proposal. An item that solves no part of `problem` belongs on another page, or nowhere.
+- **A concrete example:** every `why` walks through one short, specific scenario drawn from the
+  topic itself, showing what happens without the proposal, so the user can catch up without
+  knowing the details. Explain any term the user may not know in plain words inside it, never
+  by name alone.
+- **Compared with something:** every item has `versus`, naming what it is weighed against: how
+  things work today, or the option it competes with.
+- **Pros and cons are differences:** each one says how the proposal is better or worse than
+  `versus`, never something true of both. A different concern is a different item, not a con.
+- **Real cons only:** a con is a lasting cost or risk of the outcome. One-time work to build it
+  is not a con, and neither is a command the user only meets in an error message that names it.
+- **Alternatives:** `versus` is the main alternative, so the user knows what approving rules out.
+- **Suggestions in chat too:** when the user suggests another way while a page is open, add it
+  as a new item to weigh instead of acting on it.
+- **Settled items:** removed, never marked done. A page left with no open items is deleted;
+  see [Settle](#settle).
+
+## Publish
+
+1. **Stage:** run this skill's `scripts/stage <out-dir>`, with `<out-dir>` a folder for this
+   topic in the session's scratch directory, such as `<scratch>/questions/<topic>`. It prints:
+   ```
+   PAGE: <out-dir>/index.html
+   QUESTIONS: <out-dir>/questions.json
+   ```
+2. **Write** the items into `questions.json`.
+3. **Publish** with the Artifact tool:
+   - `file_path`: the `PAGE` path.
+   - `files`: `{"questions.json": "<QUESTIONS path>"}`.
+   - `capabilities`: `{"db": {}, "comments": {}}`, on the first publish only.
+   - `icon`: `checklist`, on the first publish only.
+4. **Link:** give the user the artifact link.
+
+## Read answers
+
+The page has a **Done, tell Claude** button. It posts a comment on the page and sends it to
+this session, which wakes you while the publish's watch has comment auto-replies armed.
+
+1. **Woken by "Done answering":** list the `responses` collection with the `ArtifactData`
+   tool, ignoring documents whose id is no longer in `questions.json`, then settle them.
+2. **Close the loop:** reply in that comment's thread with one line on what changed, then
+   resolve it with `ArtifactComments`.
+3. **No button:** it hides when no session can receive it; the user then tells you in chat.
+
+## Settle
+
+For each item with an answer:
+
+1. **Approved, no comment:** record the decision where the topic's decisions live (a design
+   doc, a plan, the code), then remove the item.
+2. **Approved, with a comment:** the comment refines the approval, never voids it. Record the
+   decision as the proposal changed by the comment, then remove the item. Only when the
+   comment raises something still to be answered (a question, a choice it leaves open) add a
+   new item for just that, with a `reply` saying which approval it came from.
+3. **Commented, not approved:** the commented item never stays. Remove it, and roll the comment into new
+   items with new ids; carry forward whatever part of the original is still live, such as its
+   proposal becoming the `versus` of a new item.
+   - **A change:** a new item with the revised proposal.
+   - **A question:** a new item whose `reply` answers it, with the proposal revised if the
+     answer changes it.
+   - **A suggestion** ("why not this", "let's do it like that"): never just adopt it; a new item
+     proposing it, with its own alternative, pros and cons.
+   - **Settled by the comment:** record it, and add nothing.
+   - **`reply`:** on each new item, say in one sentence which comment it came from and what changed.
+4. **Removed items:** delete their `responses` documents in one `batch`.
+5. **Republish:** publish again with the same `file_path` and the `questions.json` entry in
+   `files`.
+6. **Nothing left open:** instead of republishing an empty page, close the loop on the "Done
+   answering" thread first, then stop watching the artifact (`ArtifactComments`, `action:
+   "watch"`, `on: false`) and delete it (`Artifact`, `action: "delete"`). Tell the user the page
+   is gone and where its decisions were recorded.
+
+Never remove an item before its decision is recorded somewhere lasting; the page is for open
+items only.
+
+## Later sessions
+
+The scratch folder is gone. Read the artifact with `action: "read"` and fetch
+`questions.json` with `action: "read"` and `path: "questions.json"`, run `scripts/stage` into a
+fresh folder, put the fetched `questions.json` there, then publish with the artifact's `url`.
+
+## Comments on the page
+
+The comment box on each item is the answer field, not a notes system; the artifact's
+built-in comments still work for anything else. See the `artifacts` skill.
+
+Change the renderer only in this skill's `assets/index.html`.