opencode-skills-collection 4.1.2 → 4.1.3

package/bundled-skills/idea-to-blueprint/references/blueprint-template.md

@@ -0,0 +1,259 @@
+# Blueprint template
+
+Contents: 1 Conventions the linter relies on · 2 ID schemes · 3 Section skeleton with depth targets · 4 Table formats · 5 Writing order and chunking · 6 Self-review before lint
+
+The blueprint is one markdown file. Sections are numbered and appear in this order; drop a section only when it plainly does not apply (a CLI tool has no copy table for SMS templates) and say so in one line where it would have been.
+
+## 1. Conventions the linter relies on
+
+- Every top-level section heading contains its **English anchor** in parentheses when the prose language is not English: `## 5. پرسوناها (Personas)`. In English documents the heading itself is the anchor.
+- Epic headings: `## Epic 03 — <Title>` (two-digit number, em dash). Epic 00 is always "Foundation".
+- Story headings inside an epic: `### E03-S02 — <Title>`.
+- Inside each story these bold labels appear, in this order: `**Story**`, `**Context**`, `**Scope**`, `**Acceptance Criteria**`, `**Edge cases**`, `**Tests**`, `**Tasks**`, `**Story DoD**`.
+- Each epic ends with `**Definition of Done**` and `**Session handoff checklist**`.
+- Evidence tags exactly as defined in `research-protocol.md` §2. Unknowns route to `OQ-nn` entries that exist in the Open Questions section.
+- No placeholder text anywhere: no TODO, TBD, TBA, FIXME, XXX, "lorem", "???", "[insert", "to be defined". If something is undecided it is an `[UNKNOWN → OQ-nn]` with a proposed default.
+
+## 2. ID schemes
+
+| Thing | Pattern | Example |
+|---|---|---|
+| Source | `S-nn` | S-14 |
+| Persona | `P<n>` (anti-persona `AP<n>`) | P2, AP1 |
+| Goal / metric | `G<n>` / `M<n>` | G3, M3.1 |
+| Flow | `F-nn` | F-03 |
+| Screen / surface | `SCR-nn` (never `S-nn`, which is a source) | SCR-07 |
+| Copy line | `CP-<screen>-<n>` | CP-SCR07-3 |
+| Entity | `ENT-<Name>` | ENT-Order |
+| API endpoint | `API-nn` | API-12 |
+| Integration | `INT-<name>` | INT-payments |
+| Edge case (global register) | `EC-<cat>-nn` | EC-PAY-04 |
+| Epic | `E<nn>` | E03 |
+| Story | `E<nn>-S<nn>` | E03-S02 |
+| Acceptance criterion | `AC-<n>` (scoped to the story) | E03-S02 AC-4 |
+| Task | `E<nn>-S<nn>-T<n>` | E03-S02-T3 |
+| Test | `T-<story>-<n>` or the real test name once written | T-E03S02-2 |
+| Open question | `OQ-nn` | OQ-07 |
+| Decision record | `DR-nn` | DR-05 |
+| Risk | `R-nn` | R-03 |
+
+IDs never change once assigned; if a story is dropped, its ID is retired with a one-line note, not reused.
+
+## 3. Section skeleton with depth targets
+
+"Depth" is a floor, not a ceiling. Page estimates assume a whole product.
+
+### 0. Cover and how to use this document (How to use)  — 1 page
+Title, version, date, author, target agents (Claude Code / Codex), model/effort used for research. Then:
+- Who reads what: humans read 1–7, 19–21; build sessions read 12–18 plus the epic in play; both read the Glossary.
+- The language convention (prose vs machine text vs product copy).
+- The evidence legend (all five tags).
+- Status of this document: DRAFT / APPROVED, and the rule that changes go through the Amendments log (section 18).
+- Table of contents.
+
+### 1. Executive summary (Executive summary) — ½–1 page
+What it is, for whom, the outcome sentence, how it is delivered (platform), what makes it different (from positioning), what v1 includes, what it excludes, and the build plan in one line ("13 epics, ~13 sessions, first releasable milestone after E05").
+
+### 2. Idea interpretation and scope (Scope) — 1–2 pages
+The user's idea as written (quoted verbatim in their language, short). Your interpretation. In-scope capabilities for v1 (bulleted, each tied to a persona and later to epics). Explicitly out of scope with reason (Non-goals live here). Scale ceiling of v1 stated in numbers.
+
+### 3. Research findings (Research) — 4–10 pages
+3.1 Domain overview and how the job is done today. 3.2 Benchmark: feature matrix, per-competitor cards, best-in-class per flow table, anti-patterns to avoid. 3.3 Gap and positioning statement. 3.4 Regulatory and platform-policy flags (as OQ pointers). 3.5 UX benchmark observations. Every row and claim carries an evidence tag.
+
+### 4. Assumptions and decision records (Assumptions & Decisions) — 1–3 pages
+4.1 Assumptions table: `# | Assumption | Why | Impact if wrong`. 4.2 Decision records `DR-nn` in the format from `architecture-decisions.md` §9: status, drivers served, context, options, decision, consequences (including what the rejected option would have bought), **compliance** (the automated check that enforces it, or "manual — reviewed against checklist item X"), and **reversibility** (one-way / medium / cheap). One record per decision, short. Covers stack, architecture style, auth model, data model shape, design system, currency, calendar, hosting. A superseded record stays in the document with its status changed and a pointer forward — why the team changed its mind is often worth more than the current answer.
+
+### 5. Personas (Personas) — 2–5 pages
+For each `P<n>` (3–5 typical): name and one-line role; context (where/when/on what device/network they use it); goals and the outcome they want; jobs-to-be-done; current pains and workarounds; tech comfort and reading tolerance; language, register and formality expectation (drives copy voice); accessibility considerations; trust concerns; key scenarios (2–4 short narratives that later map to flows); success looks like (what they say when it works). Anti-personas `AP<n>`: who we do not design for and why. End with a persona × capability matrix (which persona needs what).
+
+### 6. Goals, non-goals and success metrics (Goals & Metrics) — 1–2 pages
+Goals `G<n>` as measurable outcomes tied to personas. Metrics `M<n.m>`: leading and lagging, definition, measurement method (event, query, survey), target with `[ASSUMED]` when hypothetical, and which epic instruments it. Non-goals with a one-clause reason each.
+
+### 7. User flows (Flows) — 3–8 pages
+See `design-minimal.md` §3 for the format. One `F-nn` per core job, per persona where they differ. Each flow: trigger, preconditions, numbered steps (screen, user action, system response, copy IDs), decision points, failure branches with recovery, exit, metric. Include first-run, core loop, payment (if any), recovery/re-authentication, admin flows, and account deletion.
+
+### 8. Information architecture and screen inventory (Screens) — 3–8 pages
+Navigation model; screen table `SCR-nn | purpose | personas | entry points | components | states (empty/loading/error/success/offline) | copy IDs | edge cases`. A one-paragraph description per screen of what is on it and what the single primary action is.
+
+### 9. Design direction (Design) — 2–4 pages
+Reference-based or chosen (say which, with reason). Design tokens (colour, type scale with Persian/Latin font stacks, spacing, radius, breakpoints), component list from the chosen system with the RTL notes, iconography direction, motion policy, dark-mode decision, accessibility baseline (standard and level, verified), do/don't list of patterns for this product (from `design-minimal.md` §2).
+
+### 10. UX writing guide (UX Writing) — 2–3 pages
+Voice, tone matrix per persona and moment, terminology rules and the product glossary of UI terms (Persian ↔ English), formatting rules (numbers, dates, currency, phone), Persian pack rules when applicable, message formulas (error, empty, success, confirmation, loading, notification). See `ux-writing-guide.md`.
+
+### 11. Copy tables (Copy) — 5–20 pages
+One table per screen and one per message channel (SMS, email, push, in-app notification, bot messages): `CP-id | element | copy (product language) | English gloss | persona intent | state/variant | max length | notes`. Every state of every screen in the inventory has a line. Error variants are enumerated, not "error message".
+
+### 12. Architecture (Architecture) — 6–12 pages
+Full procedure in `architecture-decisions.md`. Order matters: drivers, then shape, then technology — never the reverse.
+
+12.0 **Architecture drivers** `AD-n`: 5–8 quality attributes ranked, each with a measurable target and the reason for its rank, derived from personas, the scale ceiling, the failure cost of the core loop, regulatory flags and hosting reality. Then the **explicit non-drivers** with a reason each.
+12.1 **Architecture style decision**: 2–3 candidates scored against the ranked drivers (scoring table), the decision, what the runner-up would have bought and at what price, and the **exit triggers** — the observable conditions under which a future session may revisit the shape.
+12.2 **Module map and boundaries**: modules by business capability with owned entities and public interfaces; the dependency-direction rule; data ownership (one module owns each table); the plausible extraction seams; and a "where new code goes by default" line per common case.
+12.3 Component diagram (fenced ASCII or Mermaid) and one paragraph per component.
+12.4 Data model: `ENT-*` with fields (name, type, constraints, nullable, default), relations, indexes, ID scheme, money representation, time-zone storage rule, soft-delete/audit policy, retention and deletion policy, and the migration policy.
+12.5 API contracts: `API-nn | method path | purpose | auth | request | response | errors` (or the OpenAPI file it will live in, with the rule that the file is the source of truth), plus the versioning policy, the single error envelope, and the pagination convention.
+12.6 Auth and authorization model with the role × permission matrix and the object-level authorization rule.
+12.7 Integrations: one card per `INT-*` from research, each with its timeout, retry, idempotency key and fallback.
+12.8 Environments, configuration and secrets, with fail-fast validation at startup.
+12.9 Observability (logs without PII, metrics, error tracking, health checks), security baseline, performance budgets, and backup/restore with a stated restore procedure.
+12.10 **Fitness functions**: each architectural rule that can be enforced mechanically, the automated check that enforces it, and where it runs. A boundary with no fitness function is a boundary that will be gone in three sessions.
+12.11 The cross-cutting decision list from `architecture-decisions.md` §7, each item either a DR reference or one line saying why it does not apply.
+
+### 13. Tech stack and engineering conventions (Tech Stack) — 3–5 pages
+13.1 Stack table: every row answers *what* (pinned version), *why* (the deciding reason, tied to an `AD-n` driver or an agent criterion — never "popular" or "modern"), *what lost and what it would have bought*, and *evidence*. A row missing any of the four is unfinished.
+13.2 Forbidden choices with reasons (archived, unmaintained, license, unreachable from the market, superseded API). An agent that knows what is banned is safer than one that only knows what is blessed.
+13.3 Repository layout, matching the module map in 12.2.
+13.4 The `check` command, its components and expected runtime.
+13.5 Formatting/lint/type strictness settings, including which escape hatches are banned and how an exception is justified inline.
+13.6 Testing conventions (layout, naming, fixtures, factories, test DB strategy, e2e tooling).
+13.7 Git conventions (branches, commit format with story IDs, PR/merge rule).
+13.8 CI/CD and deployment procedure, plus rollback.
+13.9 Error handling, logging and configuration conventions.
+13.10 Dependency policy (adding a package requires a DR entry) and the version-drift rule: pinned versions are what this document was verified against; a session that finds a version has moved records it and re-verifies rather than silently upgrading.
+
+### 14. Quality strategy, review and metrics (Quality) — 4–8 pages
+Full procedure in `code-quality-and-review.md`. This section is what makes "done" mean the same thing in session 1 and session 14.
+
+14.1 **The two layers**: what the machine decides (the gate) versus what a human judges (the review), and the rule that anything objective a reviewer has to remember is a gate gap that gets a story.
+14.2 **The gate**: every component of `check` with its command and threshold — format, lint, types, tests, coverage floor, schema-drift check, dependency audit and secret scan, architecture fitness functions, budgets, accessibility and locale checks. State the expected runtime and the rule that the gate is never weakened to make a change pass (and if it is, that is a DR).
+14.3 **Test strategy**: pyramid shape, the 3–5 named critical e2e paths, and the test-*quality* rules — behaviour not implementation, concrete assertions, red-before-green, determinism, mutation testing on the critical modules where a maintained tool exists (name it, or say none exists). State explicitly that the coverage number is a floor against regression and never a story goal.
+14.4 **Review checklist**: the checklist from `code-quality-and-review.md` §11, embedded verbatim and adapted to this product. Both the agent's self-review and the human's review use this one list.
+14.5 **Reviewing agent-written code**: the specific failure profile (invented APIs, duplication of code the agent could not see, security defects behind clean syntax, volume outrunning review capacity), the rule that every external symbol traces to a pinned dependency, and the human-author-of-record rule.
+14.6 **Metrics table**: `M-id | metric | definition | data source | instrumented by (epic) | starting target | what a move in it would prompt`. Delivery metrics, review-process metrics, codebase-health metrics (rework/churn, duplication trend, revert rate, escaped defects, flaky count, `check` runtime). Every figure sourced or tagged `[ASSUMED]`.
+14.7 **Anti-metrics**: the explicit list of what this product will not measure and why (LOC, commit/PR counts, points as productivity, coverage as a goal), plus the rule that no metric here measures an individual.
+14.8 **Definition of green, definition of done**, and the manual verification policy — what a human checks by hand, when, and how it is recorded.
+
+### 15. Edge-case register (Edge Cases) — 3–8 pages
+Global, cross-cutting edge cases `EC-<cat>-nn` grouped by category from `edge-case-catalog.md`, each with: description, expected behaviour, which stories cover it (filled as stories are written), which copy lines it uses. Story-level edge cases reference these where they exist rather than restating them.
+
+### 16. Delivery plan — sprints and epic order (Delivery Plan) — 1–2 pages
+16.1 Epic order table: `Order | Epic | Goal | Depends on | Stories | Size (S/M/L) | Why now`. 16.2 Sprint table: `Sprint | Epics | Milestone (e.g., "closed beta") | Exit criteria`. One epic = one session by default; a sprint = 1–3 epics ending in something releasable or demonstrable. 16.3 Critical path and what can be reordered without risk.
+
+### 17. Epics and stories (Epics) — 20–60 pages
+Preceded by one line stating that everything from here is in English for the coding agent. Then `## Epic 00 — Foundation` through the last epic, each following the epic template in `stories-ac-tests.md` §5. Epic 00 always contains the repo bootstrap, tooling, `check`, CI, docs files (BLUEPRINT/PROGRESS/DECISIONS/AGENTS/CLAUDE), environment templates, a hello-world vertical slice with one unit, one integration and one e2e smoke test, and the deployment skeleton to staging.
+
+### 18. Session protocol for Claude Code / Codex (Session Protocol) — 2–4 pages
+The full per-session runbook from `session-protocol.md`, the PROGRESS.md and DECISIONS.md formats, the Amendments log (how the blueprint itself gets changed from a build session), termination rules, recovery from a crashed session, and the `[VERIFY-AT-BUILD]` re-check rule.
+
+### 19. Risks and mitigations (Risks) — 1–2 pages
+`R-nn | risk | likelihood | impact | mitigation | owner | trigger to revisit`. Only risks specific to this product and market. Legal/regulatory items point to OQs.
+
+### 20. Open questions (Open Questions) — ½–2 pages
+`OQ-nn | question | why it matters | owner (user/legal/vendor/design/engineering) | blocking? (which epic) | proposed default if unanswered`. Every `[UNKNOWN → OQ-nn]` in the document has a row here.
+
+### 21. Glossary (Glossary) — 1–2 pages
+Term | definition | Persian/English equivalent | where used. Includes UI terminology decisions (the *one* word used for each concept in the product).
+
+### 22. Sources (Sources) — 1–3 pages
+`S-nn | title | URL | accessed | supports`. Every `S-nn` referenced in the document appears; nothing appears that was not read.
+
+### Appendix A — Session prompts (Appendix Session Prompts)
+One copy-paste prompt per epic, generated from `assets/session-prompt.md`, with the epic ID and the section numbers filled in.
+
+### Appendix B — Files to create in Epic 0 (Appendix Epic 0 Files)
+The literal content of `docs/PROGRESS.md`, `docs/DECISIONS.md`, `AGENTS.md`, `CLAUDE.md`, `.env.example`, and the `check` script for this product, so Epic 0 copies rather than invents.
+
+## 4. Table formats (copy exactly)
+
+Assumptions
+```
+| # | Assumption | Why this was assumed | Impact if wrong |
+|---|---|---|---|
+```
+Stack
+```
+| Layer | Technology | Pinned version | Deciding reason (driver / agent criterion) | Runner-up — why it lost, what it would have bought | Evidence |
+|---|---|---|---|---|---|
+```
+Architecture drivers
+```
+| ID | Driver | Measurable target | Rank | Why this rank | Source (persona / scale ceiling / regulation / hosting) |
+|---|---|---|---|---|---|
+```
+Architecture style scoring
+```
+| Driver (rank) | <Candidate A> | <Candidate B> | <Candidate C> |
+|---|---|---|---|
+```
+Fitness functions
+```
+| ID | Architectural rule it enforces | Automated check | Where it runs | Fails the build? |
+|---|---|---|---|---|
+```
+Metrics
+```
+| ID | Metric | Definition | Data source | Instrumented by | Starting target | What a move in it would prompt |
+|---|---|---|---|---|---|---|
+```
+Copy
+```
+| ID | Element | Copy (fa) | English gloss | Persona intent | State / variant | Max length | Notes |
+|---|---|---|---|---|---|---|---|
+```
+Screens
+```
+| ID | Screen | Purpose | Personas | Entry points | Primary action | States covered | Copy IDs | Edge cases |
+|---|---|---|---|---|---|---|---|---|
+```
+Epic order
+```
+| Order | Epic | Goal | Depends on | Stories | Size | Why now, not earlier/later |
+|---|---|---|---|---|---|---|
+```
+Open questions
+```
+| ID | Question | Why it matters | Owner | Blocking? | Proposed default if unanswered |
+|---|---|---|---|---|---|
+```
+Sources
+```
+| ID | Title | URL | Accessed | Supports |
+|---|---|---|---|---|
+```
+
+## 5. Writing order and chunking
+
+Write in this order, one write operation per numbered item, appending to the same file:
+
+1. Cover, how-to-use, TOC (section 0)
+2. Sections 1–2
+3. Section 3 (research) — may need two chunks
+4. Sections 4–6
+5. Section 7 (flows)
+6. Sections 8–9
+7. Section 10
+8. Section 11 (copy tables) — one chunk per 3–5 screens
+9. Section 12 — **two chunks**: 12.0–12.2 (drivers, style decision, module map) first, then 12.3–12.11
+10. Section 13, then section 14 as its own chunk (the review checklist and metric table are long)
+11. Section 15
+12. Section 16
+13. Section 17 — **one chunk per epic**
+14. Section 18
+15. Sections 19–22
+16. Appendices
+
+Why this order: flows before screens, screens before copy, copy before stories (stories reference copy IDs), architecture before stack conventions, everything before epics (epics reference all of it). Writing epics last means every AC can point at an existing ID instead of inventing one.
+
+After each chunk, re-read the previous chunk's IDs you referenced; mismatched IDs are the most common defect in long documents.
+
+## 6. Self-review before lint
+
+Read as a stranger in a fresh session and check:
+
+- Could I build Epic 03 with only sections 12–18 and the Glossary? What did I have to guess?
+- Does every persona appear in at least one story, and does every story name a persona that exists?
+- Does every screen in the inventory have every state in the copy table?
+- Does every integration have a fallback and a sandbox statement?
+- Does every `[VERIFY-AT-BUILD]` appear in the session protocol's re-check list?
+- Is there any sentence where two options are left open? Decide it.
+- Are all numbers sourced or tagged `[ASSUMED]`?
+- Does the epic order respect every "Depends on"?
+- Could any architecture driver in 12.0 have changed the style decision in 12.1? If not, the drivers are decoration — rewrite them with real targets.
+- Does every stack row name what the runner-up would have bought? A row with no cost stated is a row that was not decided.
+- Does every boundary rule in 12.2 have a fitness function in 12.10, or an explicit line saying why it cannot be enforced?
+- Does every component of `check` in 14.2 name a tool that was verified to exist for this stack this session?
+- Is the review checklist in 14.4 present verbatim, and does the Story DoD require it?
+- Does any metric in 14.6 measure an individual? Remove it.
+
+Then run the linter.

package/bundled-skills/idea-to-blueprint/references/code-quality-and-review.md

@@ -0,0 +1,216 @@
+# Code quality, review and delivery metrics
+
+Contents: 1 Why this exists · 2 The two layers · 3 Layer 1 — automated gate · 4 Layer 2 — the review dimensions · 5 Test quality (not coverage) · 6 Reviewing agent-written code · 7 Delivery and codebase metrics · 8 Anti-metrics · 9 What to research and cite each run · 10 Where this lands in the blueprint · 11 Review checklist to embed verbatim
+
+## 1. Why this exists
+
+Every story in this blueprint is written by a coding agent in a fresh session and reviewed, usually once, by one human who did not write it and may not read every line. That is the exact condition under which quality problems become invisible: the code compiles, the tests are green, the demo works, and the defects are in the parts nobody looked at.
+
+So the blueprint does not say "write good code". It specifies, before any code exists:
+
+- what a machine checks on every change (Layer 1 — objective, non-negotiable, in `check`),
+- what a human looks for and in what order (Layer 2 — judgement, a fixed checklist),
+- how the system's health is measured over time (metrics that diagnose the *process*, never rank people),
+- and what is deliberately not measured, because measuring it makes the codebase worse.
+
+A reviewer who has to invent the standard at review time applies a different standard every time. A written standard is what makes "approved" mean something across ten sessions.
+
+## 2. The two layers
+
+Keep them strictly separated. It is the single highest-leverage rule in this file.
+
+| | Layer 1 — the gate | Layer 2 — the review |
+|---|---|---|
+| Who | CI / `check` | A human (and optionally an AI reviewer) |
+| What | Anything objectively decidable: format, lint, types, tests, coverage floor, schema drift, dependency audit, secret scan, bundle/query budgets, architecture rules | Design fit, boundaries, reversibility, failure behaviour, test *meaning*, security reasoning, copy and locale, naming |
+| Failure mode it prevents | Reviewers spending attention on things a machine decides better | Rubber-stamping, because the human has nothing specific to look for |
+| Rule | If a human is arguing about it and a machine could decide it, it belongs in Layer 1 by the next epic | If a machine could not decide it, it is never "fixed" by adding a linter rule |
+
+Anything objective that a reviewer has to remember is a Layer 1 gap, and it gets a story. Formatting arguments in a PR thread are a defect in the process, not in the code.
+
+## 3. Layer 1 — the automated gate
+
+`check` is one command, runs locally and in CI identically, and is the definition of "green". Specify in the blueprint, with the actual command and the expected runtime:
+
+1. **Format** — a formatter with zero configurable opinions left open; check mode in CI.
+2. **Lint** — strict rule set; warnings are errors in CI. Include correctness rules, not only style (unused results, floating promises/unawaited futures, exhaustive switch, no implicit any-equivalents).
+3. **Types** — the strictest mode the language offers, escape hatches banned by lint (`any`, `unwrap`, `!`, `# type: ignore`) or requiring an inline justification comment.
+4. **Tests** — unit + integration; e2e on the critical paths. Fast enough to run per-change (state the target, e.g. unit under 2 minutes).
+5. **Coverage floor** — a *floor to stop regressions*, not a target to chase (see §5 and §8).
+6. **Migration/schema drift check** — the schema in the repo matches what migrations produce; no divergence.
+7. **Dependency and secret checks** — vulnerability audit at a stated severity threshold, license check, lockfile committed and verified, secret scanning on the diff.
+8. **Architecture fitness functions** — the module-boundary and dependency-direction rules from the architecture section, enforced as tests (see `architecture-decisions.md` §6). Without these, boundaries erode silently across sessions.
+9. **Budgets** — whatever performance budget the product declares, asserted where it can be: query count per endpoint (N+1 guard), payload size, bundle size, p95 on a seeded dataset.
+10. **Accessibility and locale checks** where a UI exists — automated a11y rules on key screens, and a check that no user-visible string is hardcoded outside the copy/i18n catalogue.
+
+Two rules about the gate itself: **it never gets weakened to make a change pass** (weakening it is its own DR entry with a reason), and **a flaky test is a broken gate** — quarantine it in the same session with a story to fix it, never re-run until green.
+
+## 4. Layer 2 — the review dimensions
+
+In this order. The order is the point: it is roughly the cost of being wrong, and a reviewer who runs out of attention should run out of it at the bottom, not the top. Google's own review guidance leads with design for the same reason — a bug is cheap to fix relative to a wrong boundary.
+
+**D1. Does it do the specified thing?** Every AC of the story, checked against observable behaviour, not against the author's summary. Anything built that no AC asked for is scope leak: either an AC is missing (amend the blueprint) or the code is.
+
+**D2. Design and boundaries.** Does the change sit in the right module? Does it create a dependency the architecture forbids (fitness function should have caught it — if it did not, the rule is missing)? Is logic duplicated that already exists elsewhere? Is it the framework's blessed path or an invention? Cheap to fix in code, expensive to fix in structure.
+
+**D3. Reversibility.** Flag one-way doors explicitly: schema changes on populated tables, public API contracts, event formats, a new external dependency, anything that writes data in a shape that will be hard to migrate. One-way doors get more scrutiny and a DR entry; everything else gets less. Treating both the same is how teams end up slow *and* fragile.
+
+**D4. Failure and edge behaviour.** Walk the story's edge-case list against the code: empty, one, many, maximum, boundary; null/absent vs zero/empty-string; duplicate submission and idempotency; concurrent modification; dependency timeout, 5xx, partial response, slow response; offline mid-action; retry policy and whether retries are safe. The happy path is not where defects live.
+
+**D5. Test meaning.** See §5. Does the test fail if the behaviour breaks? Does it test behaviour or implementation? Would it survive a refactor?
+
+**D6. Security.** Input validated at the trust boundary; authorization checked per *object*, not just authentication at the door (an ID in a URL is not a permission); parameterised queries; output encoded for its sink; secrets not in code, logs or error payloads; PII not logged; upload type/size validated; rate limits on anything that costs money or sends messages; dependency added is one a human recognises (typosquat check). This dimension is non-optional on AI-written code — see §6.
+
+**D7. Behaviour at real scale.** Not "is it fast" but "what happens at 100× the current data". Query per loop iteration (N+1), missing index on a filtered/sorted column, unbounded result set with no pagination, whole-table load into memory, an operation that is O(n²) on something that grows.
+
+**D8. Observability.** Can this be diagnosed at 3am by someone who did not write it? Structured log at the decision points with a correlation ID, no PII; a metric for the outcome; errors reaching error tracking with enough context; health of any new dependency visible.
+
+**D9. Copy, locale and accessibility.** Strings come from the copy table by ID, not improvised; every state of the screen has its line; digits, dates, currency and direction follow the locale rules; focus order, labels, contrast, touch targets.
+
+**D10. Readability.** Naming that a stranger reads correctly; comments that explain *why*, not *what*; complexity that could be reduced without loss. Last on the list on purpose — it is real, but it is where review attention gets spent when the reviewer has no better checklist.
+
+**D11. Size and shape of the change.** Reviews of 200–400 changed lines are where defect detection is strongest; past roughly 400 lines detection falls off, and past 60–90 minutes of continuous reviewing it falls off again. This is a claim about the reader, not the author, so it survives the fact that an agent can produce 2,000 lines in a minute. If a story routinely produces more than that, the story is too big — split it in the blueprint.
+
+**The standard for approval** is not perfection: approve when the change definitively improves the system and carries no unacceptable risk, and file the rest as follow-ups. A review that blocks on preference is as expensive as a review that catches nothing.
+
+## 5. Test quality, not test coverage
+
+Coverage tells you a line executed. It does not tell you a test would notice if that line were wrong. The check that matters: *if I deliberately break this logic, does a test go red?* A test that passes against broken code is worse than no test, because it also blocks the refactor that would have removed it.
+
+Specify in the blueprint:
+
+- **Behaviour over implementation.** Tests assert observable outcomes (returned value, stored row, emitted event, rendered state, HTTP response), never internal call sequences or private structure. Heavy mocking of the unit's own collaborators is the usual tell.
+- **Real assertions.** A test that only asserts a type, a length, or "no exception thrown" is not a test. Enumerate the specific expected values.
+- **Red before green.** The story's tests are written to fail against the unimplemented behaviour and pass after; the session records that they were seen red. This is the cheapest possible mutation test.
+- **Mutation testing on the critical modules** where the stack has a maintained tool: pricing, permissions, validation, money, state machines. Mutation score on those modules is a far better signal than global coverage, and unlike coverage it does not reward padding. Verify tool availability for the chosen stack; if none exists, say so and rely on red-before-green plus targeted boundary tests.
+- **Determinism.** No wall-clock, no real network, no shared mutable fixtures, no ordering dependence, seeded randomness. Time and randomness are injected.
+- **Fixtures over inline literals** for anything reused, so a schema change breaks one file.
+- **The critical e2e paths are named** (3–5, no more) and kept green; everything else is unit and integration.
+
+Coverage still appears — as a floor in `check` that prevents silent regression, with the explicit note that raising the number is never a story goal.
+
+## 6. Reviewing code the agent wrote
+
+This blueprint's whole premise is that most code is machine-authored, which changes the defect profile rather than removing it. The published evidence is consistent enough to design around: security performance of generated code has stayed roughly flat while volume exploded — Veracode's 2026 report puts the security pass rate near 56% across 100+ models even as syntax correctness sits near 100%; GitClear's longitudinal analysis of hundreds of millions of changed lines shows duplication and short-term churn climbing while refactoring/code-reuse ("moved" code) collapses; and DORA's 2025 research finds AI raising throughput while delivery stability still degrades, with review capacity becoming the bottleneck. Verify the current figures each run (§9) — the shape of the finding matters more than the exact number, and the numbers move.
+
+Practical consequences to encode in the blueprint:
+
+1. **Syntactic confidence is not correctness.** The code will look idiomatic and be wrong about *your* system: a stale API signature, an invented parameter, a plausible library that does not exist, a config key that was renamed two versions ago. Every external symbol used in a story must trace to a version-pinned dependency listed in the stack section; anything else is a review stop.
+2. **Security is the first-class review dimension, not the last.** Assume generated code is untrusted input until checked. SAST/dependency scanning in `check` catches the mechanical classes; D6 catches authorization logic, which tooling cannot.
+3. **Duplication is the default failure.** The agent cannot see the helper you already have. Before writing, the session searches the repo for an existing implementation; the review asks "have I seen this function before?" A duplication detector in `check` is worth its cost.
+4. **Churn is the honesty metric.** Track what share of code is rewritten within ~2 weeks of merge. It is the number that tells you whether extra output is actually delivering, and it is the one that AI-assisted teams most often never look at.
+5. **A human is the author of record.** "The model wrote it" is not an explanation. Whoever merges owns it and must be able to explain the non-obvious decisions in it. If they cannot, the change is not ready — and that is the honest test of whether review is happening at all.
+6. **Annotate before review.** The session's handoff summary states what changed, what was deliberately not done, which ACs each part satisfies, and every deviation from the blueprint. Author-annotated changes review far better than raw diffs.
+7. **Review load is the real constraint.** More generated code does not mean more shipped value if it queues behind one reviewer. This is why stories are sized for a 200–400 line diff in the first place.
+
+## 7. Delivery and codebase metrics
+
+These diagnose the system, at team level, over time. Every one of them is a way of generating a *question*, never a verdict. Put in the blueprint only the ones the product will actually instrument, each with definition, data source, the epic that instruments it, and a starting target tagged `[ASSUMED]` when it is a guess.
+
+**Delivery (DORA).** The four keys — deployment frequency, lead time for changes, change failure rate, failed-deployment recovery time — plus rework rate, which DORA added in recent research, and reliability as a quasi-metric tied to stated SLOs. They earn their place by being counterbalanced: speed and stability cannot both be gamed at once. Confirm the current formulation and the current benchmark bands each run rather than quoting last year's.
+
+**Review process.** Time to first review (target: same working day), review cycles to merge (1–2 for ordinary work; more usually means the requirement was unclear, not that the code was bad), median diff size, reviewer distribution (concentration is a bus-factor and a bottleneck at once), and the share of changes merged with no substantive comment.
+
+**Codebase health.** Rework/churn rate (share of lines rewritten within ~2 weeks), duplication trend, revert and hotfix rate, escaped defects (found in production ÷ found by gate+review), flaky-test count, dependency vulnerabilities open by severity, `check` runtime (when it crosses the annoyance threshold people stop running it locally, and that is a leading indicator of everything else).
+
+**Experience.** For anything with a team: whether people can get a change to production without friction. The DX Core 4 framing — speed, effectiveness, quality, impact — exists to keep speed from being read alone, and its effectiveness dimension is deliberately survey-based because dashboards cannot see friction. For a solo builder plus agents this collapses to two honest questions per epic: what slowed this session down, and what did I have to guess?
+
+**Reading them.** Look at trends, not points. A metric moving is the start of an investigation, and the cause is almost always in the system — unclear requirements, an unrealistic staging environment, a slow gate, absent ownership — rather than in a person. Pair every number with one qualitative note; the number says something changed, the note says what it felt like.
+
+## 8. Anti-metrics — never in the blueprint
+
+Lines of code, commit count, PR count per person, story points as productivity, and coverage percentage as a goal. Goodhart's law is not a caveat here, it is the predicted outcome: each one is trivially satisfied in a way that makes the codebase worse — padded diffs, split commits, assertion-free tests written to touch lines.
+
+Two harder rules:
+
+- **No metric in this document is a measure of an individual.** DORA-style metrics are explicitly system- and team-level; applying them to a person converts a diagnostic into a target and destroys it. For a solo builder the same rule applies to self-flagellation: the metrics exist to find where the process leaks, not to grade the week.
+- **Self-reported speed is not speed.** Perceived productivity and measured productivity have been found to diverge, sometimes in the opposite direction, in AI-assisted work. If the blueprint claims a time saving, it has to be measured, or it is `[ASSUMED]`.
+
+If a stakeholder wants a single number, give them change failure rate next to deployment frequency, and refuse to reduce it further.
+
+## 9. What to research and cite each run
+
+Do not paste this file's figures into a blueprint. Verify, then cite with `S-nn` and a date:
+
+1. **The stack's actual quality tooling** — formatter, linter and rule set, typechecker strict flags, test runner, coverage tool, mutation-testing tool (does a maintained one exist for this language?), SAST/dependency audit, a11y checker, architecture-rule/fitness-function library, duplication detector. Current versions, maintained status, the exact commands. This is the single highest-value part of this track: it is what makes `check` real instead of aspirational.
+2. **Language and framework conventions** — the official style guide and the community-standard config, so the agent is not inventing conventions.
+3. **Security baseline for the category** — the current OWASP Top 10 (and API or mobile equivalents if relevant), plus category-specific requirements (payments, health, minors, personal data).
+4. **Current delivery-metric definitions and benchmarks** — the latest DORA formulation and performance bands; whether the four keys are still four where you are quoting them.
+5. **Current evidence on AI-authored code quality** — the most recent security-pass-rate and maintainability/churn figures, if the blueprint states any. State them with the year, or state none.
+6. **CI capability of the chosen host** — runners, cache, secrets, required checks, branch protection, and what a "required" gate can actually block on the plan the user has.
+
+## 10. Where this lands in the blueprint
+
+- **Section 13 (Tech Stack)** — the concrete tools and the `check` command, versions pinned, each with evidence.
+- **Section 14 (Quality)** — this file, made specific: the gate contents and runtime, test-quality rules, the named critical e2e paths, the review checklist (§11) verbatim, the metric table, the anti-metric list, the definition of "green" and of "done".
+- **Section 12 (Architecture)** — the fitness functions that enforce the boundaries.
+- **Epic 00** — stories that build the gate: every item in §3 that applies, plus the review checklist committed into the repo so it is present in every future session's context.
+- **Story DoD** — extended so a story is not done until the review checklist has been applied and the ACs each have a test that was seen red.
+- **Section 18 (Session Protocol)** — the agent self-reviews against §4 and §6 before handoff and reports the result in the handoff summary; the human then reviews with the same checklist. Two passes with one checklist beats two different standards.
+
+## 11. Review checklist to embed verbatim
+
+Put this in the blueprint (section 14) and in `AGENTS.md`/`CLAUDE.md` so both the agent and the human use the same list. Adapt the bracketed items to the product; do not shorten the list.
+
+```
+REVIEW CHECKLIST — apply to every story before it is marked DONE.
+Stop at the first unanswered item and fix it; do not batch.
+
+Gate
+[ ] `check` green on the whole repo, not just the changed files
+[ ] No gate rule weakened, skipped or ignored to make this pass (if it was: DR entry, reason)
+[ ] No new flaky test; any flake seen is quarantined with a follow-up story
+
+Correctness
+[ ] Every AC of this story is demonstrably met, verified against behaviour not description
+[ ] Nothing implemented that no AC asked for
+[ ] Every listed edge case is covered by a test or explicitly accepted with a reason
+
+Design
+[ ] Change sits in the module the architecture assigns it to; no forbidden dependency direction
+[ ] No logic duplicated from elsewhere in the repo (searched before writing)
+[ ] Framework's documented path used, not an invention
+[ ] One-way doors (schema on populated tables, public contracts, event formats, new dependency)
+    identified and recorded as a DR
+
+Tests
+[ ] Each AC maps to a named test; each was seen failing before implementation
+[ ] Tests assert concrete expected values, not types/lengths/no-throw
+[ ] Tests assert behaviour, not internal calls; they would survive a refactor
+[ ] Deterministic: no wall clock, no network, no order dependence, seeded randomness
+[ ] [Mutation score on <critical modules> not reduced]
+
+Failure behaviour
+[ ] Empty / one / many / max / boundary all specified and covered
+[ ] Dependency timeout, 5xx and partial response each have defined behaviour
+[ ] Repeat submission is idempotent where it must be; retries are safe
+[ ] Nothing is left in a half-written state on failure
+
+Security
+[ ] Input validated at the trust boundary
+[ ] Authorization checked per object, not only authentication
+[ ] Queries parameterised; output encoded for its sink
+[ ] No secret or PII in code, logs, error payloads or fixtures
+[ ] Rate limits on anything that costs money, sends a message, or can be brute-forced
+[ ] Every external symbol traces to a pinned dependency in the stack table; no invented APIs
+[ ] Any new dependency: recognised, maintained, license-compatible, DR entry written
+
+Scale
+[ ] No query inside a loop; no unbounded result set; indexes exist for filtered/sorted columns
+[ ] Behaviour at 100x current data is stated and acceptable
+
+Observability
+[ ] Decision points logged, structured, correlation ID present, no PII
+[ ] Outcome metric emitted; errors reach error tracking with context
+[ ] This change is diagnosable by someone who did not write it
+
+Copy, locale, accessibility [UI stories]
+[ ] All strings from the copy table by ID; every screen state has its line
+[ ] Digits, dates, currency, direction follow the locale rules
+[ ] Focus order, labels, contrast, touch targets checked
+
+Shape
+[ ] Diff is within [200–400] changed lines, or the story is split
+[ ] A human can explain every non-obvious decision in this change
+[ ] Handoff summary written: what changed, what was skipped, deviations, ACs satisfied
+```

package/bundled-skills/idea-to-blueprint/references/design-minimal.md

@@ -0,0 +1,96 @@
+# Design direction, flows and screens — minimal by default
+
+Contents: 1 Reference vs chosen direction · 2 Minimal pattern catalog (do / don't) · 3 User flow format · 4 Screen inventory format · 5 Design tokens format · 6 RTL rules · 7 Accessibility baseline · 8 Persona-driven design decisions
+
+## 1. Reference vs chosen direction
+
+**User gave a reference** (Figma, screenshots, a product, a brand kit): extract and document — colours, type, spacing rhythm, component shapes, navigation model, tone of imagery. Keep what serves the personas; note every deviation you make and why (usually usability, RTL, contrast, or minimalism). The build sessions need the tokens, not a link to a Figma they cannot open.
+
+**No reference**: choose, don't defer. Default direction unless research says otherwise:
+- Mobile-first, single-column, generous spacing, one primary action per screen.
+- Standard components from a well-documented, actively maintained design system verified this session (RTL support and accessibility documented), themed lightly — no custom component library in v1.
+- Neutral palette with one accent for primary actions and semantic colours for states; high contrast; no gradients or decorative illustration in v1 unless the category demands warmth (then one illustration style, used sparingly).
+- Typography: one Persian/Latin-capable font family, 4–5 sizes, two weights.
+- Motion: functional only (state transitions ≤ 200 ms), respects reduced-motion.
+State the chosen direction in the Decision brief in one line so the user can object once.
+
+## 2. Minimal pattern catalog
+
+Do (default choices):
+- **List → detail** for any collection; no dashboards in v1 unless the persona's job *is* monitoring.
+- **One primary action per screen**, sticky at the bottom on mobile; secondary actions as text buttons or in an overflow menu.
+- **Progressive disclosure**: show the 3–5 fields most people need; "advanced" behind one toggle.
+- **Forms**: single column; labels above fields; inline validation on blur and on submit; the submit button disabled only for *impossible* states, otherwise enabled and showing errors; numeric keyboards for numeric fields; phone-first auth where the market expects it.
+- **Wizard only when a form exceeds ~7 fields or has dependent steps**; show progress; allow back without loss.
+- **Optimistic UI + Undo** for reversible actions; **consequence-stating dialog** for irreversible ones.
+- **Empty, loading, error, offline states designed for every list and screen** — they are screens, not afterthoughts.
+- **Search + 1–2 filters** rather than complex filter panels; recent items where it saves a search.
+- **Bottom sheet** on mobile for pickers and short actions; full screen for anything that needs more than one decision.
+- **Tabs ≤ 4**, otherwise a list.
+- **Onboarding = do the first real task**, with inline guidance; no multi-screen tour; ask for permissions (notifications, location) at the moment they are needed, with the reason.
+- **Skeletons** for < 1 s loads; text status for longer.
+- **Consistent destructive colour and placement**; destructive actions never the default focus.
+
+Don't (in v1 unless a persona demands it): carousels for content that matters, hover-only affordances, custom gestures, infinite settings screens, modal-on-modal, disabled buttons without explanation, icons without labels for primary actions, confirmations for reversible actions, sign-up before showing value, dark patterns of any kind (pre-checked upsells, hidden cancel).
+
+## 3. User flow format
+
+```
+### F-03 — <Flow name> (P1)
+**Job** — what the persona is trying to get done, in one line.
+**Trigger** — how they arrive (deep link from SMS, home screen, notification).
+**Preconditions** — logged in? has data? feature flag?
+**Steps**
+| # | Screen | User does | System responds | Copy | Notes |
+|---|---|---|---|---|---|
+| 1 | SCR-03 | enters phone | validates, sends code | CP-SCR03-1,4 | ≤ 11 digits |
+| 2 | … | | | | |
+**Decision points** — at step n: if <condition> → branch A (steps …) else → branch B.
+**Failure branches** — for each step: what can fail (from edge cases), what the user sees (copy IDs), how they recover, what is persisted.
+**Exit** — where the flow ends and what state the system is in.
+**Success metric** — M-x.y; time-to-complete target `[ASSUMED]` if hypothetical.
+**Benchmark note** — which best-in-class behaviour this adopts (S-nn) and what we do differently.
+```
+
+Flows to include for most products: first run / onboarding, sign-in and re-authentication, the core loop (per persona), money flows (pay, refund, receipt), recovery flows (forgot/lost access, offline, session expired), notifications and their deep links, account settings and deletion, admin/back-office core tasks, error and empty first-use states as flows where they are non-trivial.
+
+Keep flows to the **minimum number of steps** that still respects the persona's decision points; count steps and taps and state them — that number becomes an acceptance criterion.
+
+## 4. Screen inventory format
+
+```
+| ID | Screen | Purpose (one line) | Personas | Entry points | Primary action | States covered | Copy IDs | Edge cases |
+```
+Then one paragraph per screen: layout summary (what is above the fold on a 360-px-wide phone), components used (from the design system by name), the single primary action, secondary actions, what changes per persona/role, and what the screen looks like in each state (empty / loading / error / offline / success / permission-denied where relevant).
+
+Screens are counted: a product with 40 screens in v1 has a scope problem — revisit section 2 before writing copy for all of them.
+
+## 5. Design tokens format
+
+```
+Colour: bg, surface, text-primary, text-secondary, accent, accent-text, success, warning, danger, border, focus-ring — as hex, with contrast ratios noted against their usual backgrounds.
+Type: font families (Persian, Latin, mono) with self-hosted files and license; scale (display, h1, h2, body, small, caption) with size/line-height/weight; Persian line-height factor.
+Spacing: base unit and scale (4/8/12/16/24/32/48).
+Radius, elevation/shadow levels, border widths.
+Breakpoints: mobile ≤ 600, tablet ≤ 1024, desktop.
+Component list: from the design system, with the props/variants allowed in v1 (e.g., Button: primary/secondary/text/danger; sizes md/lg).
+Iconography: set name and license; which icons flip in RTL (arrows, back, send) and which do not (clock, search, play).
+Motion: durations, easing, reduced-motion behaviour.
+```
+
+## 6. RTL rules (when the product language is RTL)
+
+- The document direction is `rtl` at the root; layout mirrors via logical properties (start/end), never left/right.
+- Directional icons flip; symmetric and semantic icons do not; media controls follow platform norms (verify).
+- Numbers and Latin tokens are isolated (bidi) inside RTL text; phone numbers and codes render LTR as a unit.
+- Progress and sliders fill from the start (right) side; back buttons point right; carousels (if any) advance to the left.
+- Test every screen with long Persian strings (Persian runs ~20–30 % longer than English in many labels) and with mixed content.
+- Fonts: confirm the chosen font covers Persian digits and the ZWNJ renders as zero width in the target browsers.
+
+## 7. Accessibility baseline
+
+Reference the current accessibility standard and level after verifying its version this session. Non-negotiables for every UI story's AC-7: text contrast ≥ 4.5:1 (3:1 for large text and UI components), touch targets ≥ 44×44 px, visible focus ring, full keyboard operability on web, labels for every input and icon button, live regions for async errors/success, no information by colour alone, `prefers-reduced-motion` respected, text resizable to 200 % without loss, meaningful page titles and headings order, form errors associated to fields. Screen-reader language attribute set to the product language so pronunciation is right.
+
+## 8. Persona-driven design decisions
+
+For each persona sheet trait, write the design consequence in section 9 (the same way §2 of the UX writing guide does for copy): low-end device → lightweight pages, no heavy media, offline tolerance for reads; poor network → optimistic UI, retry with backoff, small payloads; busy shop floor → large targets, high contrast, two-tap core action; older or low-vision users → larger base font, simpler navigation; admin power user → dense tables, keyboard shortcuts, bulk actions. These consequences become acceptance criteria (performance budgets, tap counts, target sizes) rather than adjectives.