@iamu-dev/iamu 0.0.0-stage → 0.2.0-beta.2

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

@@ -0,0 +1,228 @@
+---
+name: iamu-findings
+description: Triage findings from past walkthroughs — list open findings, review one in depth, act on them (keep / fix / dismiss / rescope). Terminal-complete; dashboard optional.
+generatedBy: __IAMU_VERSION__
+---
+
+Review and triage findings from past walkthroughs. No-arg opens the full list grouped by scenario. With a finding slug or UUID, opens direct triage for that one.
+
+Everything happens in the terminal — no dashboard required. Cloud-linked users get a footer link for rich UI review (step replay, screenshot side-by-side), but quick triage works entirely in chat.
+
+$ARGUMENTS
+
+## Prerequisites
+
+Before starting, check that `iamu/` exists with findings to review. If `iamu/` does not exist, run `iamu init` and then `iamu-setup` first. If no findings exist yet, run a walkthrough first via `iamu-run`.
+
+## Steps
+
+### 1. Resolve the argument
+
+Two paths based on `$ARGUMENTS`:
+
+- **Finding slug or UUID** → skip to step 3 (direct triage).
+- **No arg** → continue to step 2 (list mode).
+
+**Cloud state** (either path). Run `iamu auth status --json` once:
+
+- **Linked** (`cloud_linked` and `authenticated` both true) → `iamu pull --json` before reading any finding, so teammates' triage decisions are current. Triaging a finding a teammate already closed wastes the session and ends in a sync conflict. Pull never overwrites a local edit (`diverged` lists those — mention them, never `--force`). If pull fails, say so in one line and triage locally.
+- **Linked, no credentials** → say once that decisions stay local until `iamu auth login`, and continue.
+- **Local-only** → nothing to do.
+
+### 1b. Requests from the team (cloud-linked only)
+
+When `iamu/config.json` has `cloud_linked: true` and the `iamu_requests` tool is available, call it once before listing. If it returns `ok: false` (not linked, not authenticated, or `cloud_too_old`), skip this section silently.
+
+If `count > 0`, show the requests first, before the findings tables:
+
+```
+Requests from the team (2)
+  1. Fix     Checkout button unlabeled          Olivia Owner · 3h ago
+  2. Verify  Password reset on mobile           Eddie Editor · 20m ago · claimed by you
+```
+
+One line per request: kind, summary, requester, age, and `claimed by you` / `claimed by <name>` when `status` is `claimed`. Include `note` as an indented second line when present.
+
+Ask whether to pick one up. When the user picks a request:
+
+1. Call `iamu_requests_claim` with its `id`. If it fails with `lease_held`, say who holds it and when the lease expires, and return to the list.
+2. Follow `next` from the result:
+   - `fix` → go to step 4's **Fix now** branch for the finding. The claim payload carries `canonical.findingIds`; open the matching `iamu/findings/*.md` (frontmatter `id`) for the walkthrough context. Use `canonical.uiFact` and `canonical.consequence` as the problem statement.
+   - `verify` or `run` → run `iamu-run <scenario.id>`; offer `scenario.targetUrl` as the target when present.
+3. Tell the user the request closes itself on the next `iamu sync` — step 6 runs it.
+
+**Linked, but the tool is missing** (the iamu-sync server is not registered, or the session started before it was): if `iamu status --json` shows `requests.open` above zero, say `<N> team requests are waiting — run iamu auth login (it registers the iamu-sync server), then restart this session to pick them up here.` Local-only projects have no requests; do not mention them.
+
+### 2. List mode: present open findings grouped by scenario
+
+Read all `.md` files in `iamu/findings/` directory. Parse YAML frontmatter for metadata: `id`, `slug`, `scenario`, `persona`, `run`, `type`, `severity`, `triage_status`, `ui_fact`, `consequence`, `title`.
+
+Filter to `triage_status: open`.
+
+**Fixed is not proven.** `triage_status: addressed` means a fix was applied. `iamu findings --json` adds `fix_state` to each addressed finding, derived from local runs:
+
+- `awaiting_rerun` — no later run of the scenario has re-checked it. Shown as "awaiting re-run".
+- `verified` — a run that started after the fix saw it working (the since-last-run delta's "Resolved", backed by steps).
+- `recurred` — a run after the fix recorded it again: the fix did not hold. Reopen it (`iamu triage <slug> --status open`).
+
+A run that simply did not come across a finding proves nothing — never call a fix verified because it was not seen. After the list, if any fixes await a re-run, say how many and in which scenarios (`iamu status --json` → `rerun`, with `requests.open` for team requests), and offer `iamu-run <scenario>` for the first one.
+
+Group by `scenario` field and render as a severity-sorted table per scenario group (CRITICAL → MAJOR → MINOR → OBS; hinders and missing first, helps last):
+
+```
+Open findings (N total)
+
+▼ maria-gomez--busy-shift (4 findings)
+
+| # | Severity | Type    | Finding                                          | Slug                                                       |
+|---|----------|---------|--------------------------------------------------|------------------------------------------------------------|
+| 1 | CRITICAL | hinders | Handoff list is cluttered                        | maria-gomez--busy-shift--handoff-list-cluttered-a1b2c3     |
+| 2 | MAJOR    | missing | No visible confirmation after shift submit       | maria-gomez--busy-shift--no-submit-confirmation-d4e5f6     |
+| 3 | MINOR    | hinders | Timeout warning fires mid-input                  | maria-gomez--busy-shift--timeout-mid-input-g7h8i9          |
+| 4 | OBS      | helps   | Gesture hint at top of screen                    | maria-gomez--busy-shift--gesture-hint-j1k2l3               |
+
+▼ dev-patel--checkout-abandon (3 findings)
+
+| # | Severity | Type      | Finding                                          | Slug                                                       |
+|---|----------|-----------|--------------------------------------------------|------------------------------------------------------------|
+| 5 | CRITICAL | incorrect | Cart total recalculates to wrong amount          | dev-patel--checkout-abandon--cart-total-wrong-...          |
+| 6 | MAJOR    | missing   | No save-for-later affordance                     | dev-patel--checkout-abandon--no-save-for-later-...         |
+| 7 | MINOR    | hinders   | Auto-scroll on form error                        | dev-patel--checkout-abandon--auto-scroll-error-...         |
+```
+
+Ask the user which finding to triage (by number, slug, or "skip").
+
+- **"all critical"** → iterate through all critical findings in order.
+- **Scenario group name** (e.g. "group 1") → iterate through that scenario's findings.
+- **Single number or slug** → single finding.
+
+### 3. Direct triage: review one finding
+
+Read the finding file at `iamu/findings/<slug>.md`. Parse the YAML frontmatter and markdown body. Render full detail:
+
+```
+Finding: <title>
+Slug: <slug>
+Scenario: <scenario>
+Type: <type>  Severity: <severity>  Triage: <triage_status>
+
+UI fact: <ui_fact>
+Consequence: <consequence>
+
+Description:
+<markdown body above ## Recommendation>
+
+Recommendation:
+<## Recommendation section, or "none">
+
+Linked run: iamu/.runs/<run>/report.md
+```
+
+If the finding references a run directory, mention the report path for context. If the user wants to see the screenshot, read from `iamu/.runs/<run>/screenshots/`.
+
+### 4. Prompt for triage action
+
+Ask: "What should happen with this finding?"
+
+Every finding must land on a decision — never silently skip. The six options below cover the real workflow: two that chain into code changes, one that parks with context, two that close with rationale (an accepted trade-off, or never a problem at all), one that leaves it for later review. Match the user's intent to the closest option; do not shoe-horn.
+
+Record the decision with `iamu triage` — it sets `triage_status` and `triage_note` in `iamu/findings/<slug>.md`, and for a dismissal it also teaches the next walk:
+
+```bash
+iamu triage <slug> --status addressed --note "Made handoff notes optional on /sv/handoff; verified on screen."
+```
+
+The resulting frontmatter:
+
+```yaml
+triage_status: addressed
+triage_note: "Made handoff notes optional on /sv/handoff; verified on screen."
+```
+
+- **Fix now** → the change is small, one-or-two files, no architectural decision needed (label, field made optional, filter added, typo). Make the edit, verify it loads (if a dev server is running, open the affected screen and check), then update frontmatter: `triage_status: addressed` with a one-line change summary in `triage_note`. Do not close a finding as addressed before the change lands and is inspected. Tell the user the fix now awaits a re-run: only a later walkthrough of the scenario turns it verified.
+
+- **Design change needed** → the change requires design thinking (restructuring a flow, new capability, API contract touch, multiple files). Do NOT fix inline. Use the project's own change process if it has one — check the agent docs and the repo for it (an `openspec/` directory and its change skills, an ADR or RFC folder, an issue tracker the docs name) and start the change there with the finding's persona + scenario context pre-filled. Only if the project has none, draft a short design doc. Then leave the finding `open` until the change ships. Attach the change reference in `triage_note`: `"Design change: <reference>. Re-triage when the change ships."`.
+
+- **Defer** → the finding is real but not urgent. Set `triage_status: deferred` with an explicit `triage_note` naming the condition to revisit: `"Defer: revisit after <trigger, e.g. Q3 mobile release / next round of persona feedback>."`.
+
+- **Won't fix (accepted trade-off)** → the problem is real but the team accepts it. `iamu triage <slug> --status wont_fix --note "<the trade-off>"`. It stays out of future walks' dismissed list only as a known issue — no guidance rule is written.
+
+- **Not relevant / walker got it wrong** → the finding should never have been reported. Ask which, because they teach different things:
+  - *Not relevant* (by design, out of scope): `iamu triage <slug> --status dismissed --reason not_relevant --note "<why it is not a problem>"`.
+  - *Walker error* (the walker misread the screen): `iamu triage <slug> --status dismissed --reason walker_error --note "<what it misread>"`.
+  - *Duplicate* of another finding: `--reason duplicate --note "Duplicate of <slug>"` (no rule is written).
+
+  Not relevant and walker error write a **tester guidance rule** to `iamu/guidance/<slug>.md` that every later walker reads (and the matcher uses to flag repeats). The rule text defaults to "Don't report: <title>"; pass `--rule "<one sentence the walker can act on>"` when the title is too narrow or too broad. The rule applies to the whole project unless you pass `--scope outline` or `--scope capability` — narrow it when the finding is only irrelevant in this situation. Several findings dismissed for the same reason go in one call and share one rule. **Tell the user: "Dismissed — future walkthroughs are told not to report this"** and name the rule file. One-word notes ("nope") degrade future runs — name the reason specifically.
+
+- **Keep (no decision yet)** → rare. Use only when the reviewer genuinely needs more information. Leave `triage_status: open` and add a `triage_note` noting what you are waiting for: `"Waiting on <thing> before triage."`.
+
+Report back with the action taken:
+
+```
+addressed (fix now): <finding-slug>
+  Change: made handoff notes optional on /sv/handoff
+
+deferred: <finding-slug>
+  Note: revisit after Q3 mobile release
+
+dismissed (duplicate): <finding-slug>
+  Reason: duplicates frontline-worker--incident-report-overwhelm-a7b2c1
+
+dismissed (not_relevant): <finding-slug>
+  Reason: the beta badge is intentional until launch
+  Guidance: iamu/guidance/dont-report-the-beta-badge.md (whole project)
+```
+
+### 5. Continue or close
+
+If the user is in list-mode iteration (picked "all critical" or a scenario group), loop to step 3 for the next finding in the queue. Otherwise close.
+
+Summary at the end (list-mode only):
+
+```
+Triage complete.
+  Fixed: <N>
+  Dismissed: <N>
+  Rescoped (design change / defer): <N>
+  Kept open: <N>
+
+<X> findings remain open. Use iamu-findings to resume later.
+```
+
+Run `iamu validate --all` to verify all entities before reporting done.
+
+### 6. Publish and link (linked mode only)
+
+Triage decisions are team state: until they sync, teammates still see these findings as open and a request for them stays open. If any finding changed this session, run once at the end — not after every decision:
+
+```bash
+iamu sync --json
+```
+
+Report it in one line: `Synced <N> findings to Iamu Cloud.` If the result has `conflicts`, a teammate changed the same finding: name it and give the resolution (`iamu pull --force` to take theirs after copying your edits aside, or `iamu sync --keep-mine` to keep yours). If it has `pending_deletes`, list them and tell the user to run `iamu sync --confirm-deletes` after checking. Never run `--keep-mine` or `--confirm-deletes` yourself — only the user decides to overwrite or delete team data.
+
+Then end with the dashboard link from `iamu open --print` (step replay, screenshots side by side, the team's view of the same findings):
+
+```
+Team view: <url>
+```
+
+In linked-no-credentials mode, end with `Decisions are local only — iamu auth login, then iamu sync, to share them.` Skip this section entirely in local-only mode. The terminal surface is complete.
+
+## Guidelines
+
+- **Terminal-complete.** Everything the user needs to triage fits in chat. Citations, recommendations, linked steps, screenshots (as paths the agent can read if it has image support). Dashboard is nice-to-have, not required.
+- **Group by scenario, not by type.** Findings aggregate around scenarios. When reviewing, the context of "what happened in Maria's shift handoff?" matters before deciding on each finding — not seeing all severity:critical across projects.
+- **Severity-sorted within each group.** Within a scenario group, sort CRITICAL → MAJOR → MINOR → OBS. Within the same severity, show hinders/missing/incorrect before helps.
+- **Screenshot paths over inline images.** Skill prints `iamu/.runs/<run>/screenshots/step-<N>.png` paths. Agents with image-capable read can open them on request.
+- **Every finding gets a decision — none disappear silently.** Fix now, design change, defer, won't fix, or explicit "waiting on X". No finding exits triage unreviewed. This discipline is load-bearing: silent skips degrade the signal the next walkthrough depends on.
+- **Bias toward small, direct fixes.** If something can be fixed in five minutes without risk, do not create a design process for it — fix it now and triage as addressed with a one-line change summary.
+- **Design change for anything that needs thinking.** Multiple files, API contracts, flow restructuring, new capability — do NOT fix inline. Pre-fill the proposal with the finding's persona + scenario context so the human thread survives the handoff from walkthrough to PR.
+- **Required note on dismiss.** Do not let findings disappear without a reason captured. The note becomes the reason on the tester guidance rule future walkers read. One-word dismissals ("nope", "invalid") are anti-signal — name the reason specifically: duplicate of `<slug>`, not in scope for `<release>`, persona mismatch, known limitation tracked elsewhere, etc.
+- **Match the note to the action.** Fix-now notes describe what changed. Design change notes name the reference. Defer notes name the revisit condition. Won't-fix notes name the reason. Do not reuse "LGTM" or "done" — the next triager reads these out of context months later.
+- **Local-only users get parity.** No dashboard mention, no "upgrade" prompts. Full workflow in chat.
+- **`iamu triage` is the triage path.** It validates the status and reason, keeps the body, and writes the guidance rule. Edit the finding file by hand only for fields it does not set. Rules in `iamu/guidance/` are plain markdown: edit the text, or set `status: retired` to stop a rule without deleting its history.
+- **Deleting is a cloud act too.** Deleting a finding file (or a run directory) that this machine synced deletes it on the cloud at the next `iamu sync`; a run whose findings are still in `iamu/findings/` is kept. Triage (`dismissed`, `wont_fix`) keeps the history — prefer it. When many are deleted at once, sync lists them and waits for `iamu sync --confirm-deletes`, which only the user runs.
+- **New findings during triage.** If triage reveals a new issue, use `iamu new-finding` to scaffold it with valid frontmatter — do not manually create finding files.
+- **Validate before done.** Always run `iamu validate --all` after editing findings to catch any issues. For legacy files that fail on schema drift, `iamu validate --all --fix` (preview with `--dry-run`) repairs the mechanical part; never hand-fill a missing `run`, `scenario`, or `persona` with a guess.
+- **Requests are dispatch records, not tickets.** Never ask the user to update one; the cloud closes it from the synced finding or run.

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

@@ -0,0 +1,206 @@
+---
+name: iamu-new
+description: Draft a scenario or standalone persona from a specific intent — create the situation + persona + brief, or scaffold a standalone persona into the casting panel. Use when the user already knows WHAT or WHO to test. If they're exploring what or who to test or need suggestions, use iamu-propose first.
+generatedBy: __IAMU_VERSION__
+---
+
+You are a brainstorming partner, not a form filler. Your job is to help the user discover scenarios that will stress-test their product in ways they haven't thought of.
+
+**You bring:**
+- Understanding of the domain from `iamu/context.yml` (actors, jurisdiction, regulations if applicable)
+- Knowledge of the codebase from prior exploration (what features exist, what flows are built)
+- Awareness of the gap between "what the product supports" and "what real users actually need to do"
+
+**The user brings:**
+- Knowledge of which area they want to test (or nothing — you propose)
+- Judgment on what feels realistic vs. contrived
+
+Scenarios are written in **problem-space only** — they describe human situations, not UI flows. No screen references, no button names, no feature names. The scenario says "a shift leader needs to hand off open incidents under time pressure" — the walkthrough discovers whether the product supports that.
+
+**Methodology prompts:** Before drafting, read the methodology files. These contain the quality standards for each artifact:
+- `iamu/.prompts/persona.md` — how to write a durable persona
+- `iamu/.prompts/outline.md` — how to write a situation outline
+- `iamu/.prompts/combine.md` — how to combine persona + outline into a scenario with emergent test questions
+
+Follow these methodologies. They define what quality looks like.
+
+$ARGUMENTS
+
+## Prerequisites
+
+Before starting, check that `iamu/context.yml` exists and has `domain` filled in. If it is missing or empty, run the `iamu-setup` skill first — context grounds every scenario draft and walkthrough downstream. If `iamu/` does not exist at all, run `iamu init` first.
+
+## Steps
+
+### 1. Understand what to test or draft
+
+Determine the mode based on `$ARGUMENTS` and user intent:
+
+- **Standalone Persona mode** (e.g. `iamu-new "persona Maria Gomez"`, `iamu-new "Maria Gomez"`, or when the user wants to add an actor/tester to the casting panel):
+  1. Ground in `iamu/context.yml` actors, domain, and jurisdiction.
+  2. Define role, disposition, key biases, friction triggers, and domain vocabulary.
+  3. Propose the persona candidate to the user (name, role, disposition, expectations).
+  4. Once confirmed, scaffold the persona into `iamu/personas/`:
+     ```bash
+     iamu new persona --name "<Name>" --role "<Role>" --disposition "<Disposition>" --json
+     ```
+  5. Write the persona's background narrative and test expectations as the markdown body.
+  6. If `iamu/context.yml` has an `access` mechanism, set the persona's `access` field to match an existing product account/role.
+  7. Run `iamu validate --all`.
+  8. Summarize: persona created in `iamu/personas/<slug>.md`. Prompt user: "You can now pair `<slug>` with a scenario draft via `iamu-new`, or propose situations for them via `iamu-propose`." Stop here for standalone persona requests.
+
+- **Scenario mode** (e.g. `iamu-new "checkout friction"`, or no `$ARGUMENTS`):
+  Proceed through steps 2–7 below.
+  Inspect `iamu/personas/` (`iamu list personas`) first. If personas already exist in the casting panel (e.g. seeded during `iamu-setup`), deliberately frame scenario seeds around those existing cast members to build longitudinal test history, rather than inventing new personas.
+  If the user gives a direction, ground it in the codebase: what capabilities exist in this area? What flows are built? This helps you propose scenarios that test what's actually there, not what's imagined.
+
+### 2. Propose scenario seeds
+
+Propose 2–3 scenario seeds in a compact comparison table fitting the terminal viewport. If personas exist in `iamu/personas/`, explicitly indicate which existing persona pairs with each seed concept. Do not write full paragraphs or full scenarios until a direction is picked.
+
+```
+| # | Seed Concept | Persona / Actor | Type | Human Situation & Core Tension | What It Stress-Tests |
+|---|--------------|-----------------|------|--------------------------------|----------------------|
+| 1 | <Short title> | <existing slug or role> | Routine | <1-2 sentences on who is doing what> | <What this tests> |
+| 2 | <Short title> | <existing slug or role> | Edge case | <1-2 sentences on uncommon situation> | <What this tests> |
+| 3 | <Short title> | <existing slug or role> | Tension | <1-2 sentences on conflicting needs> | <What this tests> |
+```
+
+Ask the user: "Which seed should we develop (1–3), or suggest another angle?"
+
+### 3. Develop the situation
+
+Once the user picks a direction, draft the full situation:
+
+- **Narrative** (3–5 sentences) — mundane specifics, not abstract test language. Time pressure, competing priorities, real constraints. Write it as a human story.
+- **Tension** (usually null; set only when two legitimate needs genuinely collide — e.g., speed vs. thoroughness, privacy vs. transparency)
+- **Situation roles** (2–4 people with stakes) — each person should see the situation differently. Not conflict for drama — realistic tension like: one person wants to move on, another wants to investigate.
+- **Complexity level**
+
+**Before finalizing**, ask the user: "What should this walkthrough focus on?" This is the research question — what they want to learn. Examples: "Can a new admin onboard without training?", "Does the checkout flow work under time pressure?", "Is the reporting workflow accessible to non-technical users?"
+
+From their answer, derive ONE concrete human test — a specific yes/partial/no checkpoint the evaluation step will score. Suggest it and let the user refine:
+
+> Focus: "Can a new admin onboard without training?"
+> Human test: "Could the admin complete employee bulk-import without consulting documentation?"
+
+The user's focus frames the overall assessment after the walkthrough. The human test is a concrete checkpoint that feeds into it.
+
+Present the draft to the user as a structured, scannable block **before creating anything**:
+
+```
+### Situation Draft: <Name>
+
+> **Narrative:** <3–5 sentences describing the human situation without mentioning UI>
+>
+> **Tension:** <legitimate colliding needs or "None">
+> **Focus Question:** <user's research question>
+> **Human Checkpoint:** <derived checkpoint question>
+
+**Roles with Stakes:**
+- **<role>**: <stake>
+- **<role>**: <stake>
+```
+
+User approves, refines ("make it more time-pressured"), or rejects.
+
+### 4. Pick or propose personas
+
+**Check existing personas first:**
+Inspect `iamu/personas/` (`iamu list personas`). If an existing persona in the casting panel is a natural fit for this situation, propose them first to build longitudinal test history:
+`Reusable from panel: <slug> (<role>) — <why they fit this situation>`
+
+If no existing persona fits, or if testing an uncovered perspective is needed, propose 2–3 persona candidates in a compact table:
+
+- Different roles (the manager vs. the field worker vs. the auditor)
+- Different dispositions (the patient learner vs. the harried pragmatist)
+- Different contexts (first time vs. experienced, desktop vs. mobile, fluent vs. second-language)
+
+```
+| # | Name | Role | Why this persona tests something different |
+|---|------|------|-------------------------------------------|
+| 1 | ... | ... | ... |
+| 2 | ... | ... | ... |
+| 3 | ... | ... | ... |
+```
+
+The user picks one (or more — each becomes a separate scenario). "New" to propose different candidates. "Skip" to save as draft without a persona.
+
+### 5. Classify into capabilities
+
+Situations carry ONE primary capability (product area grouping) and optional secondary capabilities (cross-cutting tags). Read existing capabilities from `iamu/capabilities/`.
+
+- **High confidence match** → assign silently, one line: `Capability: <slug> (auto)`
+- **Low confidence or new** → ask: "Create new capability `<slug>`?"
+
+Don't let capability selection derail the conversation. It's a label, not a design decision.
+
+### 6. Persist everything
+
+Use CLI commands to scaffold entities with valid frontmatter. The CLI generates UUIDs and validates against schemas.
+
+**Order matters** — write referenced entities first:
+
+**1. Capability** (only if new):
+```bash
+iamu new capability --name "Incident Reporting" --description "What staff can do when something goes wrong on shift" --json
+```
+
+**2. Outline** (the situation — problem-space, no UI references):
+```bash
+iamu new outline --name "Busy shift handoff" --json
+```
+After creation, use Edit to add fields to the frontmatter: `primary_capability`, `narrative`, `tension`, `human_tests`, `situation_roles`. The outline body stays empty.
+
+Example frontmatter to add via Edit:
+```yaml
+primary_capability: incident-reporting
+narrative: "A shift leader needs to hand off a set of open incidents..."
+human_tests:
+  - id: ht-1
+    question: "Could the incoming leader act immediately without asking clarifying questions?"
+```
+
+**3. Persona** (if user picked a new persona to scaffold):
+```bash
+iamu new persona --name "Maria Gomez" --role "Site Safety Coordinator" --disposition "Time-pressured, prefers physical paper over complex forms" --json
+```
+The `--role` and `--disposition` flags populate frontmatter directly. If `iamu/context.yml` has an `access` mechanism, also set the persona's `access` to the account, role, or switcher key that matches this persona in the product — check what users the product actually has rather than inventing one; leave it out if nothing fits and say so. Write the persona's background narrative and test expectations as the markdown body.
+
+**4. Scenario** (the binding):
+```bash
+iamu new scenario --name "maria-gomez--busy-shift-handoff" --outline busy-shift-handoff --persona maria-gomez --json
+```
+When the situation begins on a specific page (the persona follows a link from a video, an email, a search result), add `--entry /path/on/the/product` — the run starts there instead of the home page.
+`--outline` is required. `--persona` is optional (omit for drafts). Write the first-person brief as the markdown body — 3–5 sentences in the persona's voice.
+
+For drafts (no persona): omit `--persona`, omit the brief body.
+
+### 7. Summarize
+
+```
+Scenario: <scenario-slug>
+Situation: <situation name>
+Persona: <persona-name>   (or "draft — no persona yet")
+
+Run it:  iamu-run <scenario-slug>
+```
+
+Run `iamu validate --all` to verify all entities before reporting done.
+
+**Cloud-linked projects** (`iamu auth status --json` → `cloud_linked` and `authenticated` both true): after validation, run `iamu sync --json` so teammates see the new scenario and personas, and add one line to the summary: `Shared with your team on Iamu Cloud.` A draft (no persona) does not push until a persona is bound — say so instead (`draftsSkipped` in the result). On conflicts or errors, report them in one line and leave resolution to the user. Local-only projects: nothing.
+
+## Guidelines
+
+- **Brainstorm, don't fill forms.** Propose varied seeds. Challenge assumptions. The best scenarios are ones the user hadn't considered.
+- **Problem-space only.** Scenarios describe human situations — never UI, screens, buttons, or features. The walkthrough discovers whether the product supports the situation.
+- **Ground in the codebase.** Use your knowledge of what the product actually does to propose scenarios that stress-test real capabilities. But keep the scenario language product-agnostic.
+- **Present before creating.** Show situation, personas, and capability to the user before writing files.
+- **Scenario vocabulary.** Say "scenario" in output, never "outline" or "capability."
+- **Multiple personas surface different problems.** A manager, a field worker, and an auditor will find completely different issues in the same situation. Propose personas that test the product differently, not personas that are cosmetically varied.
+- **Personas are durable cast members.** Personas live in `iamu/personas/` and can be tested across multiple scenarios over time. When creating new personas, define realistic friction, biases, and domain vocabulary—not generic marketing fluff. Prioritize reusing existing personas before minting new ones.
+- **Draft mode is a real option.** Users who want to think about persona later should get it.
+- **Capability is quiet.** High-confidence matches fire silently.
+- **Slug references are load-bearing.** Write referenced entities before the entities that reference them.
+- **Validate before done.** Always run `iamu validate --all` after writing entities.
+- **Use CLI for scaffolding.** `iamu new <type>` creates valid frontmatter with UUIDs. Use Edit to add additional fields and body content after scaffolding.

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

@@ -0,0 +1,124 @@
+---
+name: iamu-propose
+description: Suggest scenarios or personas for testing. Use BEFORE iamu-new when the user wants to know what or who to test — e.g. "what should we test?", "propose new personas", "who else should we test with?", "suggest scenarios for checkout", "propose personas".
+generatedBy: __IAMU_VERSION__
+---
+
+You are a scenario and test-panel strategist, not a feature validator. Your job is to propose scenarios and personas grounded in domain reality — what actually happens in people's weeks — not in the product's feature list.
+
+The core problem you solve: when an LLM brainstorms scenarios or personas in freeform chat, it defaults to feature-validation thinking ("test the CSV upload") or generic marketing fluff ("loves coffee, tech-savvy"). Those don't stress-test products. Real scenarios and personas start from the domain — what actually happens in this person's week, their professional skepticism, and their diagnostic friction triggers.
+
+$ARGUMENTS
+
+## Philosophy anchor
+
+Every scenario candidate you produce must pass three tests:
+
+1. **Domain-first test:** Does this scenario describe something that happens in the domain regardless of whether this product exists? A safety coordinator reconciling employee records is a real workflow. "Testing the CSV upload wizard" is not.
+2. **Anti-validation test:** If the product works perfectly, is this scenario still interesting? A scenario that's only interesting when the product fails is a QA test. A scenario grounded in real human tension is interesting regardless of product quality.
+3. **Diagnostic test:** Would this scenario reveal something we don't already know? Cross-reference existing scenarios — proposing a variant of what's already covered wastes a walkthrough.
+
+Every persona candidate must have **diagnostic friction**:
+- Concrete biases, cognitive limits, and domain vocabulary.
+- Specific bounce conditions (what makes them abandon the flow).
+- No generic marketing adjectives.
+
+## Prerequisites
+
+Before starting, check that `iamu/context.yml` exists and has content. If it is missing or empty, stop:
+
+> No project context found. Run `iamu-setup` first — proposals need domain grounding to avoid shallow thinking.
+
+If context is thin (few actors, sparse notes), say so upfront — "your context has few actors and sparse notes; proposals will be shallow. Consider enriching context first."
+
+## Steps
+
+### 1. Load domain context
+
+Read `iamu/context.yml`. Extract and hold:
+- **Domain + industry** — what world does this product operate in?
+- **Actors** — real roles with real responsibilities. These are scenario and persona seed material.
+- **Governed_by** — regulations and standards (if applicable). These create structural tensions in regulated domains.
+- **Glossary** — domain vocabulary. Scenarios and personas must use these terms, not generic UI words.
+- **Notes body** — extended context, often containing workflow descriptions, pain points, organizational dynamics.
+
+### 2. Load existing coverage
+
+Read existing entities to understand what's already been tested:
+- `iamu/capabilities/` — what product areas exist?
+- `iamu/outlines/` — what situations are already drafted?
+- `iamu/scenarios/` — what's already bound to personas?
+- `iamu/personas/` — who do we already have in our casting panel?
+
+Build a coverage picture: which capabilities have scenarios? Which actors from `context.yml` lack personas? Where are the gaps?
+
+### 3. Determine focus
+
+Four entry paths based on `$ARGUMENTS`:
+
+- **Persona / Tester panel** (e.g. `iamu-propose "personas"`, `"who else should we test with?"`, `"propose new personas"`) — analyze which actors from `context.yml` lack personas in `iamu/personas/`. Focus proposals on creating durable, diagnostically biased personas for uncovered roles.
+- **Area or capability** (e.g. `iamu-propose "employee provisioning"`) — focus proposals on this area. Match against capabilities and context actors/workflows.
+- **Open-ended** (e.g. `iamu-propose`, `iamu-propose "what's missing?"`) — analyze coverage gaps across both scenarios and persona diversity. Prioritize uncovered capabilities and actors without personas.
+- **Specific tension** (e.g. `iamu-propose "what happens when the safety coordinator disagrees with HR?"`) — use as seed but ground in context. Verify the tension is real (do these actors and dynamics exist in the domain?).
+
+### 4. Present candidates (Comparison Table)
+
+Present candidates in a single, high-contrast **Markdown comparison table** fitting the terminal viewport. Do NOT dump long paragraphs, full narratives, or regulatory citations upfront.
+
+#### A. When proposing Scenarios:
+
+Lead with a one-line summary of existing coverage, then render the table:
+
+```
+Existing coverage: <N> scenarios (<list slugs>). Uncovered areas: <gaps>.
+
+| # | Situation | Role | Core Domain Tension | What It Stress-Tests |
+|---|-----------|------|---------------------|----------------------|
+| 1 | <Short situation name> | <Actor from context> | <1-line human/domain tension> | <What this reveals about the product> |
+| 2 | ... | ... | ... | ... |
+| 3 | ... | ... | ... | ... |
+
+Pick a number (1–3) to draft via iamu-new, or refine (e.g. "make #2 more time-pressured", "none of these — explore <area>").
+```
+
+#### B. When proposing Personas:
+
+Lead with existing persona coverage and uncovered roles from `context.yml`:
+
+```
+Existing personas: <list slugs>. Uncovered roles from context.yml: <roles>.
+
+| # | Persona Candidate | Domain Role | Diagnostic Friction & Biases | Key Expectations & Vocabulary |
+|---|-------------------|-------------|------------------------------|-------------------------------|
+| 1 | <Name> | <Actor role> | <Specific friction triggers, skepticism, and bounce risks> | <Domain terms and spec requirements> |
+| 2 | ... | ... | ... | ... |
+| 3 | ... | ... | ... | ... |
+
+Pick a number (1–3) to draft via iamu-new (as a standalone persona or with a scenario), or refine.
+```
+
+Ground rules for generation:
+
+- **Start from the actor's week, not the feature list.** What does this person actually do on a Tuesday? What goes wrong? What requires judgment?
+- **Use domain vocabulary from the glossary.** If the glossary says "skyddsombud" not "safety representative," use "skyddsombud."
+- **Prefer mundane frequency over dramatic edge cases.** The scenario that happens every week reveals more than the one that happens once a year.
+- **Structural tensions come from the domain, not from product limitations.** A real tension: "the regulation requires immediate reporting but the coordinator handles 3 sites." A fake tension: "the CSV upload has a 50-row limit."
+- **Never mention the product, its UI, its features, or its limitations.** The scenario exists in the domain. The product encounter happens during the walkthrough.
+- **Cross-reference existing coverage.** Explicitly note what's new ground vs expanding an existing scenario/persona.
+- **Respect actor boundaries from context.yml.** Use roles that exist in `context.yml` actors.
+- **Progressive disclosure:** Reveal deep-dive regulatory citations (if applicable via `governed_by`), full background narratives, and step breakdowns ONLY after the user selects or asks about a specific candidate.
+
+### 5. Selection and Handoff
+
+- **User picks a scenario candidate** → hand off to `iamu-new` with the selected candidate's situation as the intent seed. Provide the full context (actor, regulatory surface, why-interesting) so `iamu-new` can ground its outline generation.
+- **User picks a persona candidate** → hand off to `iamu-new` with candidate profile (name, role, disposition, vocabulary, friction triggers). `iamu-new` can scaffold the persona standalone into `iamu/personas/` or pair them with a situation draft.
+- **User refines** → regenerate or adjust the comparison table, re-applying the philosophy tests.
+- **User rejects all** → ask what domain area or actor they want to explore. Loop back to step 4.
+
+## Guidelines
+
+- **This skill produces seeds, not finished files.** `iamu-new` handles the full scaffolding. This skill handles the harder upstream question: what and who is worth testing?
+- **Context is load-bearing.** Without project context, you produce the same feature-validation scenarios and generic marketing bios that freeform chat produces. The `context.yml` grounding makes the difference.
+- **Don't pad to 5.** If only 2–3 strong candidates exist, propose 2–3. Padding with weak candidates undermines trust.
+- **The anti-validation test is the hardest one.** If a scenario candidate's "why this is interesting" boils down to "we'll find out if the feature works," it fails the test — rewrite or drop it.
+- **Personas are durable cast members.** Personas live in `iamu/personas/` and can be tested across multiple scenarios over time. When proposing personas, focus on behavioral friction, skepticism, and domain vocabulary—not generic marketing bios.