opencode-skills-collection 4.1.2 → 4.1.4

package/bundled-skills/idea-to-blueprint/assets/CLAUDE.md.template

@@ -0,0 +1,38 @@
+# {{PRODUCT_NAME}} — agent instructions
+
+You are building this product one epic per fresh session. Nothing is remembered between sessions; the repo is the memory.
+
+## Read in this order, every session
+1. `docs/PROGRESS.md` — where we are, evidence, deviations, preconditions
+2. `docs/BLUEPRINT.md` — sections 12–16 (architecture, stack, conventions, quality, edge cases, delivery plan), 18 (session protocol), 21 (glossary), and the epic you were asked to build in section 17 plus every flow/screen/copy ID it references
+3. `docs/DECISIONS.md` — why things are the way they are
+4. `docs/REVIEW-CHECKLIST.md` — the standard every story is reviewed against before it is DONE
+
+## Rules
+- Follow `docs/BLUEPRINT.md` §18 (session protocol) exactly: orient → verify preconditions → plan → build story by story with tests first → verify gates → update PROGRESS/DECISIONS → print handoff.
+- Quality gate: `{{CHECK_COMMAND}}` must be green before every commit and at handoff. It runs format, lint, typecheck, tests and the architecture fitness functions; it must exit non-zero on any failure. **Never weaken, skip or bypass a gate rule to make a change pass** — if it must change, that is a DR entry plus a follow-up story.
+- Self-review before handoff: walk the review checklist in `docs/REVIEW-CHECKLIST.md` (BLUEPRINT §14.4) over your own diff, story by story, reading the diff rather than your memory of writing it. Fix what fails. Report `reviewed: n items, n fixed, n accepted with reason` in the handoff — never a bare tick.
+- Search the repo for an existing implementation before writing a new helper, mapper or utility. Duplicated logic is the most common defect in agent-written code, and you cannot see what you did not read.
+- Every external symbol you use must trace to a pinned dependency in BLUEPRINT §13.1. If you are not certain a function, parameter or config key exists in the pinned version, check the docs — do not write it from memory.
+- Tests assert concrete expected values and observable behaviour, never internal call sequences. A test that only checks a type, a length or that nothing threw is not a test. Each one must be seen failing before the implementation.
+- Keep each story's diff within {{DIFF_LIMIT_LINES}} changed lines. If it will not fit, say so in the plan — the story is mis-sized and needs an amendment, not a bigger diff.
+- Copy strings come from the copy tables (`CP-*` IDs) in the blueprint. Never improvise user-facing text.
+- Acceptance criteria are the spec. If an AC is wrong, impossible or ambiguous: do not silently deviate — record an Amendment (BLUEPRINT §18) and, for user-visible/money/data/security changes, ask first.
+- Anything not in the blueprint or PROGRESS.md is a decision → `docs/DECISIONS.md` (DR-nn) in the same commit. New dependency = DR entry.
+- Stay inside the epic's scope. Ideas for later go to PROGRESS.md "Parking lot".
+- Re-check every `[VERIFY-AT-BUILD]` item your epic depends on before relying on it; record the result.
+- Commit format: `type(scope): message [E03-S02]`. Branch: `epic/E03` (or trunk if the blueprint says so).
+- Never mark a story or epic DONE without an evidence line per AC in PROGRESS.md.
+
+## Commands
+- Quality gate: `{{CHECK_COMMAND}}`
+- Tests only: `{{TEST_COMMAND}}`
+- Dev server: `{{DEV_COMMAND}}`
+- Migrate: `{{MIGRATE_COMMAND}}`
+- Deploy staging: `{{DEPLOY_STAGING_COMMAND}}` (see BLUEPRINT §13.8)
+
+## Conventions (summary — full text in BLUEPRINT §13)
+- Language/runtime: {{RUNTIME_AND_VERSION}} · Framework: {{FRAMEWORK_AND_VERSION}} · DB: {{DB_AND_VERSION}}
+- Strict typing on; no untyped escapes; typed errors; no swallowed exceptions; structured logs without PII.
+- Tests: unit next to code / integration in `{{INTEGRATION_TEST_DIR}}` / e2e in `{{E2E_DIR}}`; factories in `{{FACTORIES_DIR}}`.
+- Locale: {{LOCALE_RULES_ONE_LINE, e.g. "RTL, Persian digits in UI, Jalali dates in UI, UTC in storage, Toman with unit label"}}

package/bundled-skills/idea-to-blueprint/assets/DECISIONS.md.template

@@ -0,0 +1,14 @@
+# DECISIONS — {{PRODUCT_NAME}}
+
+> One entry per decision, newest last. Blueprint decision records are copied here in E00 so this is the single place to look.
+> Format: context → options → decision → consequences. Keep each under 15 lines.
+
+## DR-01 — {{Title, e.g. "Stack: <language/framework>"}}
+- Date: {{YYYY-MM-DD}} · Epic: E00 · Source: BLUEPRINT §4 / §13
+- Context: 
+- Options considered: 
+- Decision: 
+- Consequences / follow-ups: 
+- Evidence: [VERIFIED — S-nn, date]
+
+## DR-02 — 

package/bundled-skills/idea-to-blueprint/assets/PROGRESS.md.template

@@ -0,0 +1,47 @@
+# PROGRESS — {{PRODUCT_NAME}}
+
+> State file, not a diary. The agent reads this first in every session and updates it before handoff.
+> Source of truth for *what* to build: `docs/BLUEPRINT.md`. For *why*: `docs/DECISIONS.md`.
+
+## Current position
+- Active epic: E00 — Foundation
+- Last green `check` commit: (none yet)
+- Staging URL: (set in E00)
+- Blockers: none
+
+## Epic status
+| Epic | Title | Status | Started | Done | Notes |
+|---|---|---|---|---|---|
+| E00 | Foundation | NOT STARTED | | | |
+| E01 | {{EPIC_01_TITLE}} | NOT STARTED | | | |
+<!-- one row per epic from BLUEPRINT §16. Status values: NOT STARTED · IN PROGRESS · DONE · BLOCKED -->
+
+## Story status and AC evidence
+<!-- For each story: status + one evidence line per AC. Evidence = passing test name in `check`, or manual check with date and observation. -->
+### E00
+- E00-S01 — NOT STARTED
+  - AC-1: —
+  - AC-2: —
+
+## VERIFY-AT-BUILD results
+| Item | Needed by | Checked (date) | Result | Notes |
+|---|---|---|---|---|
+| {{e.g. INT-sms sandbox reachable}} | E02 | | | |
+
+## Deviations and amendments
+| # | Date | Epic/Story | What changed | Why | Amendment ID (BLUEPRINT §18) |
+|---|---|---|---|---|---|
+
+## Accepted risks (skipped edge cases / tests) — each needs an owner and a revisit trigger
+| # | Story | Edge case / test | Reason | Owner | Revisit when |
+|---|---|---|---|---|---|
+
+## Parking lot (ideas out of scope — do NOT build)
+- 
+
+## Preconditions for the next epic
+- (filled by the agent at handoff: env vars, accounts, credentials, manual steps the user must do)
+
+## Session log (one line per session)
+| Date | Epic | Outcome | Final commit |
+|---|---|---|---|

package/bundled-skills/idea-to-blueprint/assets/session-prompt.md

@@ -0,0 +1,23 @@
+# Session prompt template (one per epic — Appendix A of the blueprint)
+
+Fill the placeholders per epic and paste as the FIRST message of a fresh Claude Code / Codex session opened in the repo root.
+
+---
+
+You are starting **Epic {{EPIC_ID}} — {{EPIC_TITLE}}** of {{PRODUCT_NAME}}. This is a fresh session: you remember nothing from previous sessions. The repo is the memory.
+
+Read, in order: `AGENTS.md` (or `CLAUDE.md`), `docs/PROGRESS.md` (all of it), then `docs/BLUEPRINT.md` sections 12, 13, 14, 15, 16, 18, 21 and **Epic {{EPIC_ID}}** in section 17, plus every flow (F-*), screen (SCR-*), copy (CP-*), entity (ENT-*), API (API-*), integration (INT-*) and edge case (EC-*) ID that epic references, and `docs/REVIEW-CHECKLIST.md`.
+
+Then follow the session protocol in BLUEPRINT §18 exactly:
+
+1. **Orient** — confirm preconditions: previous epics DONE in PROGRESS.md; clean `git status` on main; `{{CHECK_COMMAND}}` green; required env vars present; every `[VERIFY-AT-BUILD]` item this epic depends on re-checked and recorded. If anything fails, stop and report — do not build.
+2. **Plan** — restate the goal and stories in ≤ 15 lines; list the tests you will write per story and the tasks; flag any AC that is ambiguous or references a missing ID (treat as a blueprint defect, do not guess). {{APPROVAL_MODE: "Wait for my 'go' before building." | "Do not wait — plan, then build without stopping unless a precondition fails or an amendment needs my approval."}}
+3. **Build** — story by story in order: tests first (they must fail), implement, keep `{{CHECK_COMMAND}}` green, copy only from CP-* IDs, one commit per story with `[E{{EPIC_ID}}-Snn]` in the message, PROGRESS.md evidence line per AC, DR-nn in DECISIONS.md for every decision the blueprint does not make.
+4. **Verify** — full `check`, epic-level flow tests, regression of all previous epics, CI green, staging deploy + smoke if the DoD requires it. Then **self-review**: walk `docs/REVIEW-CHECKLIST.md` (BLUEPRINT §14.4) over the epic's diff, story by story, reading the diff rather than recalling what you wrote — check correctness against each AC, module boundaries, failure paths, test meaning (would a test fail if the logic were wrong?), authorization per object, behaviour at 100x data, observability, copy IDs, and diff size. Fix what fails; do not batch it. Walk the epic's Definition of Done line by line with evidence.
+5. **Handoff** — update PROGRESS.md (status, evidence, deviations, accepted risks, VERIFY-AT-BUILD results, next epic preconditions, session log line), DECISIONS.md, and the Amendments log if anything changed; final commit; then print the ≤ 20-line handoff summary from BLUEPRINT §18 and tell me it is safe to terminate.
+
+Rules that override everything: never mark DONE without evidence; never improvise user-facing text; never silently change an AC; never touch scope outside this epic; never weaken the quality gate to get to green; never use an API you have not verified exists in the pinned version; when in doubt, record and ask.
+
+---
+
+Notes for the human: set the model to the strongest available and the effort/thinking level to maximum if the tool exposes it. Terminate the session after the handoff summary, then open a new one for the next epic.

package/bundled-skills/idea-to-blueprint/references/architecture-decisions.md

@@ -0,0 +1,202 @@
+# Architecture and technology decisions
+
+Contents: 1 Why this is a separate track · 2 Step 1 drivers · 3 Step 2 candidate styles · 4 Step 3 the default and its exit triggers · 5 Step 4 boundaries · 6 Step 5 fitness functions · 7 Step 6 the cross-cutting decision list · 8 Step 7 technology selection · 9 Decision record format · 10 What to research and cite · 11 Anti-patterns · 12 Output into the blueprint
+
+## 1. Why this is a separate track
+
+A stack table answers "what will we use". It does not answer the two questions a fresh build session actually needs: **what shape is this system** and **why is it that shape rather than the obvious alternative**. Without the second answer, the first agent that hits friction re-decides — and now the codebase has two architectures.
+
+Architecture here means the decisions that are expensive to reverse: the module boundaries, what talks to what and how, where state lives, how the system fails. Everything else is code, and code is cheap. So the ordering rule for the whole track is: **derive the drivers from the product, choose the shape from the drivers, choose the technology from the shape** — never the reverse. Picking a framework first and reverse-engineering a justification is the most common way a blueprint goes wrong, and it is invisible in the finished document unless you look for it.
+
+## 2. Step 1 — Derive the architecture drivers
+
+Before naming any technology, write the drivers: the quality attributes that this specific product must have, ranked, each with a *measurable* target. Vague drivers ("scalable", "secure", "fast") produce vague architectures.
+
+Derive them from what you already know, not from a generic list:
+
+| Source | Yields |
+|---|---|
+| Personas' context (device, network, patience) | latency and offline targets, payload budgets |
+| Scale ceiling of v1 (stated in Scope, in numbers) | concurrency, data volume, throughput targets |
+| The core loop and its failure cost | availability target, consistency requirements, recovery time |
+| Money, identity, health, minors, personal data in scope | security and auditability requirements, data-residency questions |
+| Market and hosting reality | deployability constraints, dependency on reachable services |
+| Team shape (solo + agents, or a real team) | operability ceiling — how much system one person can run at 3am |
+| Regulatory flags from research | audit trail, retention, consent, export/delete |
+| The business's likely next 12 months | which axes must stay open (new channel, new market, new tenant model) |
+
+Write 5–8 drivers, ranked, in this form:
+
+```
+AD-1 Operability by one maintainer  — target: full local run with one command; one deploy unit; any
+     production issue diagnosable from logs + error tracking without attaching a debugger. Rank 1
+     because [solo builder with agent sessions; nobody is on call].
+AD-2 Correctness of money handling  — target: no partial writes; every payment state transition
+     idempotent and auditable; reconciliation possible from stored events alone.
+AD-3 p95 under 400 ms on the core read path at [stated ceiling] rows, on mid-range Android over 3G.
+...
+```
+
+Then state the **explicit non-drivers** — the attributes you are deliberately not optimising for, each with a reason. "Not multi-region. Not sub-100ms. Not 1000 concurrent writers. Not multi-tenant." This is what keeps the architecture from growing to meet imaginary requirements, and it is the section future sessions will thank you for.
+
+Ranked drivers with targets and named non-drivers are the contract the rest of this track is scored against.
+
+## 3. Step 2 — Candidate architecture styles
+
+List 2–3 realistic candidates for the shape of the system and score them against the ranked drivers. Realistic means: appropriate to the scale ceiling and buildable by the team that exists. Candidates typically come from — modular monolith; layered monolith; monolith plus a small number of extracted workers; serverless functions; service-oriented split; client-heavy with a thin backend (BaaS); bot/worker plus queue; CLI/local-first with sync.
+
+Score explicitly:
+
+```
+| Driver (rank) | Modular monolith | Monolith + worker | Services |
+|---|---|---|---|
+| AD-1 operability (1) | 3 | 3 | 1 |
+| AD-2 correctness (2)  | 3 | 3 | 1 — needs sagas |
+| ... | | | |
+| Total (weighted) | 27 | 25 | 14 |
+```
+
+Then write the decision as a DR, including what the loser would have bought you and at what price. A candidate that scores lower can still be chosen if a driver demands it — say so explicitly rather than letting the table decide silently.
+
+## 4. Step 3 — The default, and the triggers that would change it
+
+For nearly everything this skill produces — a v1 built by an agent, one deploy target, a scale ceiling in the thousands not millions — the answer is a **modular monolith**: one deployable unit, strict internal module boundaries, one database, one `check`, one deploy. The current industry discussion has converged on this as the sane starting point, with distributed architectures justified by *organisational* scale far more often than by traffic, and a visible movement of teams consolidating back after paying for complexity they did not need. Verify the current state of that discussion rather than asserting it.
+
+The reason it is the default here is narrower than the general argument: a fresh-session agent is far more reliable inside one repo with one command and local function calls than across a distributed system where a failure could be in any of four places and the reproduction requires orchestration.
+
+But "default" is not "always", and a blueprint that says only "we chose a modular monolith" has not done the work. Write the **exit triggers**: the specific, observable conditions under which this decision should be revisited, so a future session knows whether it is allowed to change the shape.
+
+```
+This decision holds until one of:
+- a module needs independent scaling with a measured >5x load difference on the core path
+- a module needs a different runtime/language for a capability the main stack cannot provide
+- more than [n] people work on the codebase and merge contention is measured, not felt
+- an availability requirement appears that one deploy unit cannot meet
+Until then, extraction is out of scope, and the module boundaries in §5 are what make extraction
+cheap if it ever becomes necessary.
+```
+
+The corollary: because extraction is not planned, boundaries are enforced *now* (§5, §6). A modular monolith without enforced boundaries is just a monolith, and it degrades into one within a few sessions.
+
+## 5. Step 4 — Module boundaries
+
+This is the part that most affects what an agent produces, because it decides where new code goes. Specify:
+
+1. **The modules**, each with: the business capability it owns, the entities it owns, its public interface (the functions/types other modules may call), and one sentence on what it must never know about.
+2. **The dependency rule**, stated as a direction, e.g. "feature modules may depend on `core` and `shared`; `core` depends on nothing internal; no feature module imports another feature module's internals — only its public interface"; and where the composition happens.
+3. **Data ownership** — one module owns each table; cross-module reads go through the owner's interface, not through a join into someone else's tables. Where that rule is relaxed (reporting, admin), say so explicitly.
+4. **The seams that matter later** — which boundaries are the plausible extraction points, and what makes them cheap (no shared transaction, no direct table access, an interface that could become an HTTP call).
+5. **Where new code goes by default**, in one sentence per common case, so an agent does not have to decide: "a new endpoint goes in the feature module that owns the entity; a helper used by two features goes in `shared` only after the second use, never on the first."
+
+Derive the modules from the domain (bounded contexts from the research and flows), not from technical layers. Modules named `controllers`, `services`, `utils` are layers, and they let anything depend on anything.
+
+## 6. Step 5 — Fitness functions
+
+A decision written down and never enforced is documentation, and it decays. For each architectural rule that can be checked mechanically, specify the automated check that enforces it — an architecture test in `check`, failing CI when violated. This is what makes the boundary real across many sessions.
+
+Typical set:
+
+- Dependency direction: no import from `core` into a feature module; no feature-to-feature internal imports.
+- Layer rules: no database access outside the data layer of the owning module; no HTTP framework types in domain code.
+- Public interface: only the module's index/public file is importable from outside.
+- Entity ownership: no query against a table your module does not own.
+- Contract: API responses match the OpenAPI/schema file; a breaking change without a version bump fails.
+- Whatever else the DRs decided: "every state change emits an event", "no synchronous call to a third party inside a request handler".
+
+Name the library or technique per language and verify it exists and is maintained (§10). Where no tool exists, write the rule as a test using the language's own module system, or as a lint rule with an explicit path pattern, and say which.
+
+Every ADR that can be enforced carries a **Compliance** line saying how — this is the practice from Richards & Ford's addition to Nygard's original format, and it is the difference between an architecture and a wish.
+
+## 7. Step 6 — The cross-cutting decisions list
+
+Walk this list explicitly. Each item is either a DR or one line saying "not applicable, because…". Silence on any of them is a decision the first agent will make for you, differently each time.
+
+**Data** — relational vs other, and why; the ownership model; identifiers (sequential vs UUID/ULID, and whether IDs are exposed); soft delete vs hard delete and the audit trail; timestamps and time zone storage rule; money representation (integer minor units, never floats) and currency; migration policy (forward-only, reviewed, reversible how); seed and fixture strategy; retention and deletion (a real requirement when personal data is in scope).
+
+**Time and correctness** — synchronous vs queued work and where the boundary is; idempotency strategy for anything externally triggered (payment callbacks, webhooks, retries) and the key it uses; transaction boundaries; what is allowed to be eventually consistent and what is not; concurrency control (optimistic version column vs locking) on contended records; scheduled jobs and how a missed run is handled.
+
+**Interfaces** — API style and the contract file as source of truth; versioning policy and what counts as breaking; error shape (a single documented error envelope with codes, not ad-hoc strings); pagination convention; validation location; whether the client is thin or holds state.
+
+**Identity and access** — authentication mechanism and session/token lifetime, refresh, and revocation; the role × permission matrix; the object-level authorization rule; how the admin surface is separated; how a session ends everywhere.
+
+**Failure** — timeout, retry and backoff policy per external dependency; circuit-breaking or its explicit absence; what degrades vs what blocks; the fallback per integration; what is queued for later vs dropped; how a partial failure of a multi-step operation is recovered.
+
+**Operations** — environments and how they differ; configuration and secret loading with fail-fast validation at startup; logging format and levels and the PII redaction rule; metrics and health endpoints; error tracking; backup and restore (including a stated, tested restore procedure — an untested backup is not a backup); deploy and rollback steps; where state lives that is not in the database (uploads, caches) and its durability.
+
+**Frontend, when there is one** — rendering strategy (server-rendered / SPA / hybrid) and why, tied to the personas' devices and network; state management approach; data fetching and caching; form/validation approach shared with the backend contract; asset and font loading (a real decision when a locale needs a specific font and a CDN may be unreachable); offline behaviour.
+
+## 8. Step 7 — Technology selection, and how to justify it
+
+Only now name technologies. Each choice is scored against the criteria in `research-protocol.md` §6 (weighted for a coding agent as the primary author) **plus** the architecture drivers from §2 — a stack that scores well generically but cannot meet AD-2 loses.
+
+Every row of the stack table answers four things, and a row missing any of them is not finished:
+
+1. **What** — the exact package/runtime, with a pinned version, verified this session.
+2. **Why** — the *deciding* reason, tied to a driver or an agent criterion. Not "popular", not "modern". "Chosen for AD-1: single binary deploy, no runtime to manage" is a reason; "great developer experience" is not.
+3. **What lost, and what it would have bought** — the runner-up in one clause, and the thing you gave up. This is what stops a future session re-litigating it, and it is the honest part: every choice costs something.
+4. **Evidence** — `[VERIFIED — S-nn, date]` for the version, maintenance status, license, and any capability claim ("supports RTL", "has a maintained Jalali library", "sandbox available").
+
+Also write, because they are the parts that actually prevent hallucination:
+
+- **Forbidden choices** — packages and services explicitly not to use, with the reason (archived, unmaintained, license, unreachable from the target market, superseded API). An agent that knows what is banned is much safer than one that only knows what is blessed.
+- **The dependency policy** — adding a package requires a DR entry; the bar for what justifies one; where the boundary is between "use a library" and "write 30 lines".
+- **Version drift rule** — the pinned versions are what the blueprint was verified against; a session that finds a version has moved records it and re-verifies rather than silently upgrading.
+
+## 9. Decision record format
+
+One record per decision, in the blueprint's section 4 for cross-cutting decisions and inline in section 12 for architectural ones. Short — a record nobody reads is worse than none. Based on the widely used Nygard/MADR shape plus the compliance line:
+
+```
+### DR-07 — Idempotency keys on all payment callbacks
+**Status** Accepted — 2026-09-06 · Supersedes: none
+**Drivers** AD-2 (correctness of money handling), AD-5 (recoverability)
+**Context** The gateway may deliver a callback more than once and does not guarantee ordering
+  [VERIFIED — S-12, 2026-09-06]. Duplicate processing would double-credit an order.
+**Options** (a) dedupe on gateway transaction ID at the DB level; (b) application-level lock;
+  (c) accept duplicates and reconcile nightly.
+**Decision** (a). A unique constraint on `payment.gateway_txn_id` plus an upsert; the handler is
+  a pure function of the callback payload.
+**Consequences** Callback handling becomes safe to retry, and replays are free. Cost: the gateway
+  transaction ID becomes part of our schema and a gateway change would require a migration.
+  Rejected (c) because reconciliation needs a human and this product has none.
+**Compliance** Integration test `payments/callback_replay_test` sends the same callback 3x and
+  asserts one payment row and one ledger entry. Runs in `check`.
+**Reversibility** Medium — one-way once production rows exist; migration path noted.
+```
+
+Rules: one decision per record; IDs never reused; a superseded record stays in the document with its status changed and a pointer to the new one, because the record of *why we changed our mind* is often more valuable than the current answer.
+
+## 10. What to research and cite
+
+Nothing in this file is a fact about the world; it is a procedure. The facts come from this session's searches, each tagged and logged:
+
+1. **Version, maintenance and license** of every component named — and whether the project is archived, in maintenance mode, or has a deprecation notice on the exact feature you plan to use. Read the page; snippets lie about archived projects.
+2. **Capability claims** — the specific one you are relying on, from the official docs: RTL support, the locale/calendar library, the driver for your database, the ORM's support for the relation shape your data model needs, the framework's support for the rendering strategy you chose.
+3. **Framework's recommended architecture** — the official "how to structure a project" guidance for the framework, because the blessed path is where the documentation and the agent's reliability are. Deviating from it is itself a DR.
+4. **Fitness-function tooling** for the language — a maintained architecture-testing library, or the lint mechanism that will stand in for one.
+5. **Hosting and runtime reality** — supported runtime versions on the chosen host, build and start commands, database and object-storage options, region reachability from the target market, and what the plan the user can actually buy includes.
+6. **The current state of the architecture-style discussion** if the blueprint asserts anything about it (the modular-monolith default in §4, service-decomposition thresholds, any "most teams" claim). Cite the year, or drop the claim.
+7. **Category-specific architectural requirements** — payments (callbacks, reconciliation, PCI-adjacent constraints), messaging platforms (bot API limits, webhook vs polling), mobile stores, anything with an audit requirement.
+
+Where a claim cannot be verified, it is `[ASSUMED — reason]` or `[UNKNOWN → OQ-nn]` with a proposed default. Never an unmarked assertion — an unmarked wrong version number in a stack table produces an entire session of code against an API that does not exist.
+
+## 11. Anti-patterns to avoid in the document
+
+- **Technology-first justification.** The stack chosen before the drivers, then rationalised. Detect it by asking whether any driver in §2 could have changed the answer; if not, the drivers are decoration.
+- **Resume architecture.** Complexity that serves the builder's interest rather than the product's — a queue with one job, a cache with no measured hot path, services for a single-person team.
+- **"Scalable" as a driver.** Unquantified, so unfalsifiable, so it justifies anything. Replace with numbers from the scale ceiling.
+- **Boundaries with no enforcement.** Modules described in prose and violated in week two.
+- **Deferred decisions.** "We'll decide the auth model when we get there" hands the decision to whichever agent gets there first. Decide, record reversibility, move on.
+- **Both-options prose.** "We could use X or Y" is not a decision. If the choice genuinely depends on an unknown, it is an OQ with a proposed default, not an open sentence.
+- **Copying a reference architecture wholesale** from a blog post for a system three orders of magnitude larger than this one.
+
+## 12. Output into the blueprint
+
+- **Section 12.0** — Architecture drivers `AD-n` with targets and ranks, plus the explicit non-drivers.
+- **Section 12.1** — Style decision: candidates, the scoring table, the decision, the exit triggers.
+- **Section 12.2** — Module map, boundaries, dependency rule, data ownership, where-new-code-goes.
+- **Section 12.3–12.9** — Component diagram, data model, API contracts, auth model, integrations, environments/config/secrets, observability, security baseline, performance budgets (as in the template).
+- **Section 12.10** — Fitness functions: the rule, the check, where it runs.
+- **Section 4.2 and inline** — DRs in the §9 format, each naming drivers, losers, consequences, compliance and reversibility.
+- **Section 13** — The stack table where every row carries what/why/loser/evidence, plus forbidden choices and the dependency policy.
+- **Epic 00** — Stories that create the module skeleton and the fitness functions, so the boundaries exist before there is any code to violate them.

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.