@iamu-dev/iamu 0.6.0-beta.0 → 0.7.0-beta.0

package/dist/templates/skills/iamu-design.md

@@ -1,6 +1,6 @@
 ---
 name: iamu-design
-description: Use when recording where the project's design docs are, reviewing the design of a page (interaction, layout, look and feel), deciding proposed edits to the design docs, pointing agents at the docs, or fixing a finding with a visual check.
+description: Use when recording where the project's design docs are, starting a design doc from a template when there is none, reviewing the design of a page (interaction, layout, look and feel), deciding proposed edits to the design docs, pointing agents at the docs, or fixing a finding with a visual check.
 generatedBy: __IAMU_VERSION__
 ---
 
@@ -19,6 +19,7 @@ Run `iamu design status --json`. It lists the recorded design files (`files`, ea
 Pick the mode from the user's words, or from the status when they asked generally:
 
 - no files recorded → **A. Record the design docs**;
+- no design doc recorded and none found, or "write us a design doc" → **E. Start a design doc from the template**;
 - a legacy `iamu/design.md` not yet migrated → **A3. Migrate the legacy doc** (offer it once);
 - "review this page / the request form / this finding's page / this direction" → **B. Review a surface**;
 - open proposals, or "what should change in our design docs" → **C. Decide proposed edits**;
@@ -37,7 +38,7 @@ Show the candidates once as a short list (kind, path, why) and ask once which to
 - a kind detection got wrong: `--kind design | product | tokens | components`;
 - in a monorepo, the part of the product a doc covers: `--applies-to /app` (URL path prefixes) or `--applies-to apps/dashboard` (an app's folder). Runs, reviews and fixes then use the right doc.
 
-If nothing is found, say so in one line. Walks and reviews run without design docs; iamu does not write one for the team.
+If no design doc is found (only tokens and components, or nothing), say so in one line and offer **E** once, as a question the user may skip. Walks and reviews run without design docs.
 
 ### A2. Point agents at the docs
 
@@ -82,6 +83,29 @@ Fix by looking, not by hoping. For one finding:
 3. If the change that meets the need breaks a design rule, stop and report it (the rule, the need, both screenshots) and propose a challenge: never ship either side silently.
 4. If fix-brief says the finding has no known page, take the page from the finding's step and still screenshot it before you edit.
 
+## E. Start a design doc from the template
+
+Only when no design doc is recorded: `iamu design template` refuses otherwise, and a recorded doc changes only through proposals (**C**). The template is filled in from the code, never by a model: the token values in the frontmatter (light theme), the token groups by name, the contrast clashes the tokens have, each component with the props it takes, and the roles people come in (from the personas and situations, never their names). Everything a person decides is a `<placeholder>`. You and the user fill those in together, and the result becomes the team's doc.
+
+1. **Template.** Run `iamu design template --out iamu/.analysis/design-draft.md --json`. It is for the app the recorded tokens and components apply to, else the root; add `--dir <app>` when the user names another app, and pass the same `--dir` to the later commands. If it answers `out_exists`, a draft is in progress: ask whether to continue it (step 2 with that file) or start over (delete the file and run it again). Tell the user in two lines what came from the code (`sources`, the components, `roles`, `clashes`) and where the doc will go (`target`).
+2. **Fill it in with the user, one placeholder at a time.** Go through the `placeholders` in this order, one question per message, and edit the draft after each answer. Each question carries a suggested answer drawn from what is known: `iamu/context.yml`, the roles and situations, what runs and findings showed of the screens, the components and tokens. The user accepts it, changes it, or skips it (the placeholder stays; a decision still open also goes under Open Questions).
+   1. **Who it is for:** by role, and what they come to do. Suggest it from the roles and situations the Overview lists, then replace that list with the agreed words. Roles only, never a persona's name.
+   2. **How it should feel:** a few words (calm and plain, dense and fast). Suggest from the domain and the roles' dispositions.
+   3. **Accessibility target:** suggest WCAG 2.2 AA, or more when the domain asks for it (a public service, long reading).
+   4. **Look:** what each token group is for, and for each contrast clash, how to keep the two apart or where one may not be used.
+   5. **States:** how forms report errors, loading, failure, empty. Suggest from what the runs saw and the components that exist (an empty-state component, a field with an error prop). Only the states the product has.
+   6. **Content and voice:** the product's words for its things, tone by role, and date and number formats (suggest from the locale and what the screens show).
+   7. **Checks:** yes/no questions a reviewer answers by looking at one screen, where yes is a pass. Suggest them from the answers so far.
+   8. **Not in the library yet**, then **Open Questions:** components screens need that do not exist, and policy decisions still open.
+
+   Write a policy value (a notice period, a limit, a percentage) only when the user gives it as the product's rule; otherwise it stays a placeholder and an open question. Name tokens, never raw colours or lengths.
+3. **Check.** Run `iamu design draft-check --file iamu/.analysis/design-draft.md --json`. Fix each of its `errors` in the draft (a value or path the code does not have, a prop a component lacks, a persona's name) and check again; ask the user only when the fix is a choice.
+4. **Show it once.** Show the whole draft, then the remaining `warnings` in one list (line and message). Ask once: **adopt it**, or **edit** (what to change; edit, check again, and show it once more).
+5. **Adopt.** Run `iamu design adopt --file iamu/.analysis/design-draft.md --json` (`--to <path>` when the user wants it elsewhere). It refuses only when the target already exists: then ask for another path. It writes the doc and records it, with `applies_to` for its app. From then on it is the team's doc: iamu changes it only through proposals a person accepts.
+6. Offer **A2** (point agents at the doc).
+
+When the user declines the template outright ("no", not "later"), run `iamu design template --decline`: runs stop offering it.
+
 ## Guidelines
 
 - **Links a terminal can open.** Terminals open only what they can see. Write web addresses in full (`https://…`), never hidden behind link text, and files as absolute paths (the project root plus the path), never relative. Name scenarios, personas and findings by slug in backticks; they need no link.

package/dist/templates/skills/iamu-run.md

@@ -429,7 +429,7 @@ Nothing waits for it: the advisor never waits for the designer, and D and E go a
 iamu designer-record <run-id> --data '<raw_designer_json>'
 ```
 
-Never run two record commands at the same time: `match-record`, `evaluate-record` and `advise-record` keep their order, and `designer-record` runs between them when its answer arrives. It re-derives the report and never touches the persona's finding files. If the subagent fails or its answer is rejected, retry once, then continue without it and record `iamu designer-record <run-id> --skipped "the designer failed"`. If `designer-record` says `rederive_failed`, run the `fix` it prints. On a host without subagents, answer the prompt yourself after C2 and record with `iamu designer-record <run-id> --by-orchestrator --data '<raw_designer_json>'`; the report then says the review was not written by a separate agent. Keep the result's `proposals` for step 5.
+Never run two record commands at the same time: `match-record`, `evaluate-record` and `advise-record` keep their order, and `designer-record` runs between them when its answer arrives. It re-derives the report and never touches the persona's finding files. If the subagent fails or its answer is rejected, retry once, then continue without it and record `iamu designer-record <run-id> --skipped "the designer failed"`. If `designer-record` says `rederive_failed`, run the `fix` it prints. On a host without subagents, answer the prompt yourself after C2 and record with `iamu designer-record <run-id> --by-orchestrator --data '<raw_designer_json>'`; the report then says the review was not written by a separate agent. Keep the result's `proposals`, and `offer_template` from `iamu designer`, for step 5.
 
 **D. Read the completed canonical.** Read `iamu/.runs/<run-id>/canonical.json` for the final data including the verification delta (if a prior run exists) and `analysis.directions` (if the advisor ran). Use this for step 5 presentation.
 
@@ -505,6 +505,7 @@ Reach is a prediction until those scenarios run again.
 
 If `summary.designer` is set, add the **Designer's review**: the designer's judgement of these screens, never the persona's experience. Give its count apart from the persona's ("2 designer findings"), never one total.
 - One line on what it was judged against: the design docs in `summary.designer.design_files`, or, when `judged_against` is `general-craft`, `Judged against general craft: recording the project's design docs makes this review sharper`, followed by the `hint` command `iamu designer` printed. Say so when `dispatch` is `inline` ("written by the orchestrator, less independent").
+- When the designer's result (C3) had `offer_template: true` (no design doc recorded or found, and the offer not declined), add one line: `No design doc yet: I can start one from your code (tokens, components, the roles you test with) and fill in the rest with you. Say "start it", or "no" and I won't offer it again.` On "start it", after triage, follow the `iamu-design` skill, mode E. On "no", run `iamu design template --decline`. Never offer it when the result does not say so.
 - The rule breaks (`summary.designer.rules_broken`), one line each: `"<rule>" (<file>) on <screen>, step <n>`, then `<rules_held> rules held`.
 - The major and critical designer findings that are not a design cause (`summary.designer.issues` with no `design_cause_of`), one line each: `<id> · designer · <severity> · <basis> · <screen> · <title>`, with `breaks "<rule>"` when it breaks one; then the count of minor and nit ones in one line.
 

package/dist/templates/skills/iamu-setup.md

@@ -233,15 +233,16 @@ iamu set context \
 
 ---
 
-### 4b. Optional: design docs (quick, skippable)
+### 4b. Design docs (quick; the user may skip it, you may not)
 
-The team's design docs are part of the product's context, like the domain. Iamu reads them wherever they are and never edits them on its own. Run `iamu design detect --json`.
+The team's design docs are part of the product's context, like the domain. Iamu reads them wherever they are and never edits them on its own. Run `iamu design detect --json` and always show the user its result, even when every candidate looks unrelated. Never drop a candidate yourself: one in a spike, sandbox or example folder is listed with that note, unticked, and the user decides.
 
-- **Found docs** (a `DESIGN.md` in any format, design-system, brand, voice or interaction docs, design sections of `CLAUDE.md` or `AGENTS.md` shown as `CLAUDE.md#<heading>`, a `PRODUCT.md`, token files, a component library): list them once, one line each (kind, path). Show a candidate with a `note` (tokens in a template, export or fixture folder) with its note, unticked. Ask once whether to record them; the user may drop some or add others. On yes, `iamu design sources <paths…>` (in a monorepo, `--applies-to` with the URL prefix or the app's folder each doc covers).
+- **Found docs** (a `DESIGN.md` in any format, design-system, brand, voice or interaction docs, design sections of `CLAUDE.md` or `AGENTS.md` shown as `CLAUDE.md#<heading>`, a `PRODUCT.md`, token files, a component library): list them once, one line each (kind, path). Show a candidate with a `note` (anything in a sample, export, fixture or spike folder) with its note, unticked. Ask once whether to record them; the user may drop some or add others. On yes, `iamu design sources <paths…>` (in a monorepo, `--applies-to` with the URL prefix or the app's folder each doc covers).
 - **A legacy `iamu/design.md`** (`iamu design status --json` shows `legacy.doc` and no `legacy.migrated_at`): fold it into the same single question. Run `iamu design migrate --json` first, and offer three answers next to the files: **move it** to a plain `DESIGN.md` the team owns (`iamu design migrate --move-to DESIGN.md --apply`), **keep** `iamu/design.md` as it is (`iamu design migrate --apply`, which records the choice so it is not offered again), or **not now** (run nothing; it is offered again next time). Only an explicit "keep" runs `--apply` without a move.
-- **Nothing found:** say so in one line and continue. Walks run without design docs.
+- **Nothing found:** say so in one line: "No design docs found. The designer reviews each run by general craft until you record some (`iamu-design`)."
+- **No written design doc** (detection found only tokens or components, or nothing, and no design doc is recorded): after the question above, or in its place when there was nothing to record, ask one question the user may skip: "There is no design doc yet. Shall I start one from your code? I fill in your tokens, components and contrast clashes, then ask you a few short questions (who it is for, how it should feel, an accessibility target, states, formats). **Yes** / **not now** / **no**." Yes: follow the `iamu-design` skill, mode E, then carry on with setup. No: run `iamu design template --decline`, so runs stop offering it. Not now: run nothing; it is offered again after the first run.
 
-Do not assess or draft design docs here. Never block setup on this step.
+Do not assess design docs here, and never write one without the user filling it in (mode E). Never block setup on this step.
 
 ---
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@iamu-dev/iamu",
-  "version": "0.6.0-beta.0",
+  "version": "0.7.0-beta.0",
   "type": "module",
   "description": "Test your product as realistic personas — scenario-driven development CLI",
   "license": "UNLICENSED",
@@ -58,8 +58,8 @@
     "tsup": "^8.5.1",
     "typescript": "^5.8.0",
     "vitest": "^4.1.11",
-    "@iamu-dev/protocol": "0.1.0",
     "@iamu-dev/local-store": "0.1.0",
+    "@iamu-dev/protocol": "0.1.0",
     "@iamu/tsconfig": "0.1.0"
   },
   "scripts": {