opencode-skills-collection 4.1.2 → 4.1.4

package/bundled-skills/idea-to-blueprint/references/intake-questions.md

@@ -0,0 +1,105 @@
+# Intake — asking the right questions once
+
+The intake exists for one reason: a hundred-page blueprint built on a wrong assumption about the users, the platform, the money or the constraints is a hundred wasted pages. The intake is *not* an interview; it is one well-prepared batch of questions, each with a default, that the user can answer in two minutes or wave through with "defaults".
+
+## Rules
+
+1. **Warm up before asking.** Run 2–5 searches on the idea first (category name, "<idea> app", "<idea> Iran" if the market looks Iranian, the closest known product). You will ask sharper questions ("closest to Snapp Food's model or to a QR-menu like Menu.ir?") and you will not ask things the market already answers.
+2. **Mine the message first.** Anything stated or clearly implied is not asked again. Language, currency, city, named services, named stack, named platform, named users — all count as answered.
+3. **One batch.** All questions in a single message, grouped under short headers, numbered, each with `(default: …)`. End with one line: "Answer what you like; 'defaults' accepts all the defaults." Where a tappable-options tool exists, put the closed questions in it and the open ones in prose right below.
+4. **Only architecture-, persona- or scope-changing questions.** If the answer would only change a detail you can put in the Assumptions table, don't ask — assume and tag `[ASSUMED]`.
+5. **Size the batch to the idea.** Whole product: 10–15 questions. Feature or internal tool: 3–6. Never more than 15; if you have more, the leftovers become assumptions.
+6. **Defaults must be the choice you would actually make**, not a placeholder. If you would pick phone-OTP login for Iranian consumers, the default says so.
+7. **Ask in the user's language.** Keep each question to one line; put the reason in a half-line only when it isn't obvious.
+
+## Market detection cues (decide the working hypothesis, then confirm)
+
+Iranian users are likely when the message has any of: Persian text, تومان/ریال/IRR, Iranian place names, Iranian services (Snapp, Digikala, Tapsi, Shaparak, Zarinpal, IDPay, Kavenegar, Bale, Eitaa, Rubika, Bazaar, Myket…), `.ir`, Jalali dates (۱۴۰۴/…), کد ملی, "کاربر ایرانی", or a Persian product name. Then the question is a one-line confirmation:
+
+> کاربرهای اصلی داخل ایران هستن؟ (default: بله — RTL، تقویم جلالی، پرداخت داخلی، ورود با شماره موبایل)
+
+Do the same for any other market the message reveals (Arabic → Gulf/MENA?, Turkish → Turkey?, mentions of GDPR → EU?). If nothing reveals a market, ask.
+
+## Question bank
+
+Pick from these groups. Skip any group the message already covers. The defaults shown are the ones to use unless the warm-up research says otherwise.
+
+### A. Product and scope
+- One sentence: what outcome does the user get that they can't get today? (default: your own reading from the message — state it and ask them to correct it)
+- Which of these is in v1, which is later? List 3–6 candidate capabilities you inferred; ask them to strike/mark. (default: the smallest set that delivers the outcome)
+- Platform: web app / PWA / native iOS / native Android / Telegram (or Bale/Eitaa) bot / desktop / CLI / API only / several. (default: whatever the benchmark shows the market uses; for Iranian consumers usually PWA or Android-first web)
+- Is this a standalone product, a feature inside an existing product, or an internal tool? (default: standalone)
+
+### B. Users and market
+- Primary users in one line each — you propose 2–4 based on research; ask them to confirm/rename/remove. (default: your proposal)
+- Market/country and language(s) of the UI. (default: detected market; Persian UI with English fallback if Iranian)
+- B2C, B2B, or B2B2C? Who pays vs who uses? (default: inferred)
+- Device and network reality: low-end Android / poor connectivity / desktop office / mixed. (default: mid-range Android on unstable mobile data for Iranian consumers; desktop Chrome for internal tools)
+- Accessibility requirements beyond a sane baseline (screen readers, low vision, motor)? (default: WCAG AA baseline, no special mandate)
+- Products they admire or want to beat. (default: the benchmark leaders you found)
+
+### C. Business and compliance
+- Monetization: free / one-off / subscription / commission / ads / internal (none). (default: inferred from benchmark; "none" for internal tools)
+- Payments needed in v1? Which gateway, if they have one? (default: yes if money changes hands; Iran → a Shaparak-licensed gateway to be verified in research; abroad → to be verified)
+- Regulated domain (health, finance, minors, personal data at scale)? (default: no; if yes, a Legal/Compliance open question is created, never answered)
+
+### D. Technical constraints
+- Preferred or forbidden languages/frameworks/databases/clouds. (default: none — the stack is chosen by the agentic-engineering criteria)
+- Hosting: inside Iran (which provider?) / foreign VPS / managed cloud / on-prem / don't know. (default: Iranian users → hosting reachable without VPN from Iran, to be verified; otherwise a mainstream managed platform)
+- Existing systems or APIs to integrate (CRM, ERP, Google Workspace, Telegram, existing DB)? (default: none)
+- Login model: phone OTP / email + password / social / SSO / none (single user). (default: phone OTP for Iranian consumers; email for B2B abroad; SSO for internal tools)
+- Data sensitivity and retention needs. (default: personal data present → encryption at rest, PII in logs forbidden, deletion on request)
+- Expected scale in year one (users/day, records, media volume). (default: small — single region, single DB; note the scale ceiling in Non-goals)
+- Offline or real-time requirements? (default: neither)
+
+### E. Design
+- Do you have a design reference (Figma, screenshots, a product to mimic, brand colours/fonts)? (default: none → the skill chooses a minimal, mobile-first direction and names it in the Decision brief)
+- Dark mode required? (default: no in v1 unless the platform norm requires it)
+
+### F. Delivery and document
+- Who builds and with what: solo + Claude Code / solo + Codex / small team / mix. (default: solo with a coding agent)
+- One epic per session is the working model — are sessions short (≈1–2 h) or long (half-day)? This sets epic size. (default: half-day → epics of 3–7 stories)
+- Deadline or milestone (closed beta, public launch, demo)? (default: none — order by dependency and value)
+- Document language: prose in your language + English for stories/AC (default) / all English / all Persian.
+- Test rigour: unit + integration only / plus end-to-end for critical flows / plus performance & security gates. (default: unit + integration everywhere, e2e on the 3–5 critical flows)
+- Deployment target for v1 (staging + prod? CI/CD required?). (default: one staging, one production, CI running `check` on every push)
+
+### G. Content and data
+- Seed content or migration from an existing system? (default: none beyond fixtures)
+- Admin/back-office needs in v1 (manage users, content, refunds)? (default: a minimal admin for whatever the core loop creates)
+
+## After the answers
+
+- Restate each answer as a decision in your notes with `[STATED]`.
+- Each skipped question becomes an `[ASSUMED — <one-clause reason>]` row.
+- Anything the user said that contradicts the warm-up research is *not* silently overruled: note it, and raise it in the Decision brief with the evidence.
+- Do not ask follow-ups unless an answer is self-contradictory or blocks the architecture (e.g., "native iOS only" plus "no Apple developer account"). One follow-up message at most; then move to research.
+
+## Example intake (Persian, whole product, market detected)
+
+```
+چند سوال کوتاه قبل از ریسرچ عمیق — هر کدوم رو خواستی رد کن، «پیش‌فرض» یعنی همه‌ی پیش‌فرض‌ها قبول.
+
+**محصول**
+1. خروجی اصلی برای کاربر رو این‌طور فهمیدم: «…». درسته؟ (پیش‌فرض: بله)
+2. کدوم‌ها توی نسخه‌ی اول باشه؟ الف) … ب) … ج) … د) … (پیش‌فرض: الف، ب، ج)
+3. پلتفرم: PWA وب / اپ اندروید / بات بله‌–تلگرام / همه (پیش‌فرض: PWA موبایل‌محور)
+
+**کاربرها**
+4. کاربرها داخل ایران هستن؟ (پیش‌فرض: بله → RTL، تقویم جلالی، پرداخت داخلی، ورود با شماره موبایل)
+5. دو پرسونای اصلی که پیدا کردم: «…» و «…». پرسونای دیگه‌ای هست؟ (پیش‌فرض: همین دو)
+
+**کسب‌وکار**
+6. مدل درآمد: … (پیش‌فرض: کمیسیون)
+7. درگاه پرداخت مشخصی دارید؟ (پیش‌فرض: یکی از درگاه‌های دارای مجوز شاپرک — در ریسرچ بررسی می‌شه)
+
+**فنی**
+8. زبان/فریم‌ورک/دیتابیس ترجیحی یا ممنوع؟ (پیش‌فرض: هیچ — انتخاب با معیارهای Agentic Engineering)
+9. هاست داخل ایران یا خارج؟ (پیش‌فرض: داخل ایران / قابل‌دسترس بدون VPN)
+10. سیستم موجودی هست که باید وصل بشیم؟ (پیش‌فرض: خیر)
+
+**دیزاین و تحویل**
+11. رفرنس دیزاین (فیگما، اسکرین‌شات، محصول نمونه)؟ (پیش‌فرض: هیچ → خودم مینیمال و موبایل‌فرست انتخاب می‌کنم)
+12. هر سشن Claude Code/Codex چقدر طول می‌کشه؟ کوتاه (۱–۲ ساعت) یا نیم‌روز؟ (پیش‌فرض: نیم‌روز → اپیک‌های ۳–۷ استوری)
+13. زبان سند: نثر فارسی + استوری/AC انگلیسی (پیش‌فرض) / همه انگلیسی / همه فارسی
+```

package/bundled-skills/idea-to-blueprint/references/research-protocol.md

@@ -0,0 +1,196 @@
+# Deep research protocol
+
+Contents: 1 Setup · 2 Evidence tagging · 3 Source tiers · 4 Track A understand · 5 Track B benchmark · 6 Track C architecture drivers and shape · 7 Track D stack for agentic engineering · 8 Track E quality bar and tooling · 9 Track F integrations & locale · 10 Track G UX benchmarks · 11 When research fails · 12 Research summary format · 13 Iran verification list
+
+Run the tracks in order. C before D is not cosmetic: the shape of the system constrains which technologies can serve it, and choosing the technology first means the architecture gets reverse-engineered to fit a decision that was never tested against the product's requirements. D before E for the same reason — the quality tooling that exists depends on the language you picked.
+
+## 1. Setup
+
+- Confirm web search and page-fetch tools exist. Without them, stop and tell the user (see SKILL.md, Phase 1).
+- Start a **source log** immediately: `S-01 | title | URL | accessed YYYY-MM-DD | what it supports`. Append as you go. The Sources section of the blueprint is this log, cleaned. Reconstructing sources afterwards is how fabricated citations happen.
+- Budget: breadth first (short queries, 1–4 words, scan many results), then depth (fetch the 10–20 pages that matter: official docs, changelogs, pricing pages, store listings). A whole product typically needs 20–60 searches and 10–25 fetches; a feature needs a third of that. Stop a track when new searches stop changing decisions.
+- Use the current year in queries about "latest", "current", "best" — stale year terms return stale pages.
+- Read pages, don't trust snippets. A snippet that says "v3 recommended" may sit above a banner saying the project is archived.
+
+## 2. Evidence tagging (used everywhere in the blueprint)
+
+| Tag | Meaning | Example |
+|---|---|---|
+| `[VERIFIED — S-07, 2026-09-05]` | You read a primary or strong secondary source that states it | "Framework X current stable is 15.2 [VERIFIED — S-07, 2026-09-05]" |
+| `[STATED]` | The user said it | "Users are Tehran restaurants [STATED]" |
+| `[ASSUMED — reason]` | Your choice where nothing was stated or found; reason in one clause | "Single currency (Toman) [ASSUMED — all benchmarked local competitors price in Toman]" |
+| `[UNKNOWN → OQ-04]` | Could not verify; routed to Open Questions with an owner | "Whether gateway Y supports refunds via API [UNKNOWN → OQ-04]" |
+| `[VERIFY-AT-BUILD]` | True now but volatile (service availability, sanctions, prices); the building session must re-check | "SMS provider Z reachable from EU hosting [VERIFIED — S-12, 2026-09-05] [VERIFY-AT-BUILD]" |
+| `[UNVERIFIED]` | Only when web tools were unavailable for the whole run: a claim from memory that could not be checked. The cover carries a warning and the first build session re-verifies every such tag | "ORM X supports composite keys [UNVERIFIED]" |
+
+Rules: every version number, every "X supports Y", every competitor claim, every market or price figure, every "available in Iran" carries one of these. Numbers with no source are not written. A claim you *remember* but did not read this session is `[ASSUMED]` at best.
+
+## 3. Source tiers
+
+1. Official documentation, changelogs, release pages, standards bodies, regulators, the vendor's own pricing/status pages.
+2. Primary product pages and store listings of competitors (for what they do and charge), GitHub repos (for activity, license, archived status).
+3. Reputable independent reports and well-known technical publications — corroborate with a tier-1 source when the claim drives a decision.
+4. Reviews, forums, app-store comments — only for *user pain and expectations*, paraphrased, never quoted, never as fact about features.
+5. Blogs and listicles — leads only; never cite as the sole support for a decision.
+
+Prefer the newest tier-1 source. When sources conflict, record both and pick with a stated reason.
+
+## 4. Track A — Understand the idea
+
+Goal: describe the problem space better than the user did, in their vocabulary and the market's.
+
+- Domain concepts and terms → start the **Glossary** (term, plain definition, Persian/English equivalents when bilingual, notes on ambiguity).
+- How the job is done today without this product (manual, spreadsheets, competitor, workaround). This becomes the "today vs with product" framing in the executive summary and the personas' current pains.
+- Adjacent regulation or platform policy that shapes scope (payments licensing, data protection, app-store rules, messaging platform bot policies, content rules). Flag as Open Questions for a professional; never write legal conclusions.
+- Analogous products in other domains whose flows solve the same shape of problem (a queue-ticketing pattern, a two-sided marketplace pattern). Note the pattern, not the brand, unless benchmarking it.
+- Outcome definition: write the single sentence "After using this, <persona> can <outcome> in <time/effort> instead of <today>". Every goal and metric derives from it.
+
+## 5. Track B — Benchmark
+
+Goal: know who exists, what the best of them do per flow, where they fail, and where this product wins.
+
+1. **Identify 5–10 players**: direct competitors, indirect substitutes (including "spreadsheet + WhatsApp"), and 1–2 best-in-class products from adjacent categories. For an Iranian market include local players found via Persian queries; global players still matter as UX references even if unavailable locally.
+2. **Feature matrix** (Competitor × capability): ✔ / partial / ✘ / unknown, each cell traceable to a source. Only capabilities relevant to the idea's outcome.
+3. **Per-competitor card**: what it is; platforms; pricing model (figures only if sourced); onboarding shape; the 2–3 things it does best; the 2–3 recurring complaints (paraphrased from reviews, tier 4); what we adopt, what we avoid.
+4. **Best-in-class per key flow**: for each core flow of *our* product (e.g., onboarding, first-order, payment, recovery), name which benchmarked product handles it best and what exactly they do (steps, defaults, copy behaviour). This feeds the flows and UX writing sections directly.
+5. **Gap and positioning**: one paragraph — the unmet need or under-served persona, and the positioning statement: "For <persona> who <need>, <product> is a <category> that <benefit>, unlike <alternative> which <limitation>."
+6. **What not to copy**: anti-patterns observed (dark patterns, 6-screen tours, mandatory sign-up before value) with one line why.
+
+Never quote review text or marketing copy; describe it. Keep pricing figures to what a pricing page states, with the date.
+
+## 6. Track C — Architecture drivers and shape
+
+Full procedure in `architecture-decisions.md`; read it before starting this track. What the research phase owes it:
+
+1. **Drivers, not adjectives.** Derive 5–8 ranked architecture drivers `AD-n` with measurable targets from the personas, the stated scale ceiling, the failure cost of the core loop, the regulatory flags and the hosting reality. Then write the explicit non-drivers. A driver without a number is not a driver.
+2. **Shape before technology.** Score 2–3 candidate architecture styles against those drivers. Record the scoring table; it becomes a DR. The default for this skill's output is a modular monolith with enforced boundaries — but "default" means it must still be argued against the drivers and given explicit exit triggers, not asserted.
+3. **Verify the architectural claims you rely on.** The framework's officially recommended project structure; whether the data-access layer supports the relation shape your model needs; whether the chosen runtime can do the concurrency model you assumed; whether the host supports the deploy unit you chose. Read the docs page, tag it.
+4. **Verify fitness-function tooling** for the candidate languages — a maintained architecture-testing library, or the lint mechanism that stands in for one. This determines whether boundaries can be enforced or only described, which is a real input to the style decision.
+5. **Category-specific architectural requirements** — payment callback and reconciliation models, webhook vs polling for messaging platforms, audit-trail requirements, anything the domain forces on the shape.
+6. **Any "most teams" or "industry standard" claim** the blueprint will make about architecture gets a source and a year, or gets cut.
+
+Output of this track: the ranked drivers, the scoring table, the style decision with exit triggers, the module map, the cross-cutting decision list from `architecture-decisions.md` §7 walked and answered, and the fitness-function list.
+
+## 7. Track D — Stack for agentic engineering
+
+The stack is chosen for one reader: a coding agent working alone in a fresh session, who must produce correct code with no one watching. That changes the usual criteria. Score candidates against the weighted table below **and** against the architecture drivers from Track C — a stack that wins generically but cannot meet a rank-1 driver loses.
+
+### Weighted criteria (score each candidate stack 0–3 per row; weights in brackets)
+
+| Criterion | Why it matters for an agent | Weight |
+|---|---|---|
+| Mainstream adoption + volume of high-quality documentation and examples | More training data and more current docs → fewer invented APIs | 5 |
+| Strict static typing available and enforceable (compiler/typechecker in `check`) | Catches an agent's wrong assumptions before runtime | 5 |
+| One-command deterministic quality gate (`check` = format + lint + typecheck + tests) with fast feedback (< 2 min for unit) | The session protocol depends on a green/red signal the agent can't argue with | 5 |
+| Mature, standard testing tooling (unit, integration, e2e) with good error output | Acceptance criteria must be provable | 4 |
+| Convention-heavy framework (file structure, routing, data layer conventions) | Fewer free choices → fewer inconsistencies across sessions | 4 |
+| Stable/LTS release, low churn, clear deprecation policy | A version pinned today still has docs in six months | 4 |
+| Small dependency surface; batteries included | Every extra package is another thing to hallucinate about | 3 |
+| Fits the market's hosting reality (self-hostable, no dependence on services blocked or sanctioned for the target country) | A stack that can't deploy is a stack that doesn't ship | 4 (5 for Iran) |
+| Native or first-class i18n/RTL/locale support where needed | Retrofitting RTL is a whole epic | 3 (5 for RTL markets) |
+| Permissive license compatible with the business | Legal blocker | 3 |
+| Team familiarity (if a team exists) | Review capacity | 2 |
+
+### Process
+
+1. From the platform decision (web/PWA/mobile/bot/CLI), list 2–4 realistic candidate stacks (language + framework + ORM/DB + test tools + UI layer).
+2. For every component of every candidate, verify **this session**: current stable version and release date, LTS/maintenance status, not archived/deprecated, license, RTL/i18n support if needed, and the exact install/init command from official docs. Tag each `[VERIFIED — S-nn, date]`.
+3. Score the matrix, pick, and write the **decision record**: chosen stack with pinned versions; the runner-up and why it lost; explicitly **forbidden choices** with reason (e.g., "no ORM X — archived [VERIFIED]", "no service Y — requires foreign card / blocked for Iranian IPs [VERIFIED] [VERIFY-AT-BUILD]").
+4. Define the **agentic engineering conventions** that go into the blueprint and Epic 0: repo layout, `check` command and what it runs, formatter and linter configs (strict), typechecker strictness flags, test layout and naming, fixtures/factories, environment variables and `.env.example`, secrets handling, commit message convention (`type(scope): message [E03-S02]`), branch strategy (trunk + short-lived epic branches), CI running `check` on push, migration policy, logging/observability baseline, error-handling conventions (typed errors, no swallowed exceptions), API contract format (OpenAPI/JSON schema) as a source of truth for both sides.
+5. Verify the **hosting and deployment** path end to end: platform/provider, build command, runtime version, database hosting, object storage, domain/TLS, backups. For Iran see §13.
+
+### Heuristics (not rules — verify every time)
+
+- Strongly typed mainstream languages with huge ecosystems and strict modes tend to win for agents; dynamic languages without type checking tend to lose points on row 2 even when adoption is high.
+- Prefer the framework's "blessed" path over clever architecture; agents do best where the docs have one recommended way.
+- Prefer a relational database with migrations over schemaless stores unless the data model truly demands otherwise; schema is executable documentation.
+- Prefer boring, stable UI component libraries with documented RTL behaviour over visually impressive ones with thin docs.
+- Prefer a monorepo with one `check` over multiple repos for a solo builder.
+
+## 8. Track E — Quality bar and tooling
+
+Full procedure in `code-quality-and-review.md`; read it before starting this track. The purpose is to make the quality gate real rather than aspirational: an agent cannot run a `check` command built from a library that does not exist for its language.
+
+Verify, for the stack chosen in Track D, each with version and maintenance status:
+
+1. **The gate components** — formatter, linter and the community-standard strict rule set, typechecker and its strict flags, test runner, coverage tool, mutation-testing tool (does a maintained one exist for this language, or not?), SAST/dependency audit, secret scanning, duplication detector, accessibility checker, architecture-rule library. Get the exact commands from official docs, not from memory.
+2. **The official style guide** for the language and framework, so conventions are cited rather than invented.
+3. **CI reality on the chosen host** — runners, cache, secret storage, required-check/branch-protection capability, and what the plan the user can actually buy includes.
+4. **The security baseline for the category** — the current OWASP Top 10 (or API/mobile equivalent), plus anything the domain adds (payments, health, minors, personal data).
+5. **Current delivery-metric definitions** if the blueprint will name any — the present DORA formulation and its performance bands. The framework has changed more than once; do not quote a version from memory.
+6. **Current evidence on AI-authored code quality** if the blueprint will assert anything about it (security pass rates, duplication and churn trends, review-bottleneck findings). State the figure with its year and source, or state none. These numbers move every few months and a stale one in a rationale is worse than no number.
+
+Output of this track: the concrete `check` command with its components and expected runtime, the test-quality rules, the named critical e2e paths, and the metric table with definitions and data sources.
+
+## 9. Track F — Integrations and locale realities
+
+For every external dependency the product needs (payment gateway, SMS/OTP, email delivery, maps, push notifications, object storage, CDN, app stores, messenger bot APIs, analytics, error tracking), verify:
+
+- Exists and is active today; official docs URL; pricing model (state figures only if on a pricing page, with date).
+- Reachability from the target market and from the chosen hosting (blocked? needs foreign card? sanctions clause in ToS? requires local company registration?).
+- Sandbox/test mode availability — the acceptance criteria will require testable integrations.
+- Webhook/callback model, idempotency guarantees, rate limits, error codes — these become edge cases and AC.
+- Fallback: what the product does when the service is down (queued, degraded, blocked).
+
+Record each as an **Integration card**: name, purpose, docs `S-nn`, status `[VERIFIED …] [VERIFY-AT-BUILD]`, sandbox yes/no, fallback, owner of credentials (OQ if unknown).
+
+## 10. Track G — UX benchmarks
+
+From the benchmarked products and 2–3 best-in-class references: how they onboard (steps to first value), how they handle empty states, errors and recovery, how they confirm destructive actions, how they do phone/OTP login (for Iran), how they present prices/dates, and what accessibility features are standard. Capture as short observations tied to sources; they justify the flow and copy decisions ("we adopt A's 2-step onboarding because…"). Also check the current accessibility standard version and level to reference (verify).
+
+## 11. When research fails
+
+- Nothing found → `[UNKNOWN → OQ-nn]` with a proposed owner (user / vendor / legal / design) and a proposed default the build session may use if unanswered, clearly marked as such.
+- Conflicting sources → record both, decide, state why; add `[VERIFY-AT-BUILD]` if the conflict is about volatile facts.
+- Volatile facts (availability, sanctions, prices, app-store policy) → always `[VERIFY-AT-BUILD]` in addition to the verification tag; the session protocol makes the building agent re-check these before relying on them.
+- Never "fill in" a plausible library, endpoint or parameter name. If the docs page that lists it was not read, it is not in the document.
+
+## 12. Research summary format (feeds the Decision brief)
+
+```
+### Research summary
+Outcome sentence: …
+Glossary seeds: term → definition (5–15)
+Today's alternatives: …
+Benchmark: <n> players; leaders: …; gap: …; positioning: …
+Best-in-class per flow: onboarding → …; core loop → …; payment → …; recovery → …
+Architecture drivers (ranked, with targets): AD-1 …, AD-2 …; non-drivers: …
+Architecture shape: … (score x/y vs runner-up …); exit triggers: …; modules: …; fitness functions: …
+Stack decision: … (score x/y vs runner-up …); forbidden: …
+Quality gate: check = …; expected runtime …; mutation tool: yes/no; metrics instrumented: …
+Integrations: gateway → …; SMS → …; email → …; hosting → …
+Locale realities: …
+UX benchmarks: …
+Open questions found: OQ-01 …, OQ-02 …
+Sources so far: S-01 … S-nn
+```
+
+## 13. Iran verification list (load when users are Iranian)
+
+Each item below is a *thing to verify this session*, not a fact. Availability, licensing and blocking change frequently; the tag on each must include the date and `[VERIFY-AT-BUILD]`.
+
+**Money**
+- Which payment gateways currently hold a Shaparak (شاپرک) licence / operate as licensed PSP aggregators; sandbox availability; refund API; callback model; fee structure; whether a company registration or personal ID is needed to open a merchant account.
+- Currency display convention in the category (Toman vs Rial), rounding, and how competitors label it.
+- Wallet/credit patterns common in the category.
+
+**Identity and messaging**
+- SMS/OTP providers currently operating (service SMS lines, template pre-approval requirements, delivery to all operators, blacklist behaviour, cost per message, Unicode segment length limits for Persian text).
+- Mobile number formats and operator prefixes; national ID (کد ملی) check-digit validation if identity is needed; postal code format; address structure norms.
+- Which messengers matter for bots/notifications in the target segment (domestic messengers vs Telegram/WhatsApp under filtering) and the current status of each bot API.
+
+**Hosting and reach**
+- Iranian cloud/VPS providers and their offerings (managed DB, object storage, CDN), or foreign hosts reachable from Iran without VPN; DNS/TLS providers reachable; whether the chosen hosting can pay for/reach the chosen services.
+- Foreign services commonly blocked for Iranian IPs or requiring foreign cards (fonts CDNs, analytics, maps, package registries mirrors, container registries, error tracking, email delivery) — and the domestic or self-hosted alternative for each one you need.
+- Sanctions clauses in ToS of any foreign service you still depend on.
+
+**Distribution**
+- App-store reality: domestic Android stores (which are active, their publishing requirements), whether Google Play / Apple App Store publishing is feasible for the user, PWA installability on common Iranian Android browsers.
+- Common device/browser mix in the segment if any recent local data exists (otherwise `[ASSUMED]` mid-range Android).
+
+**Calendar, time, language**
+- Time zone (Asia/Tehran) and current DST policy; official holiday calendar source; work week (Saturday–Wednesday full, Thursday half or off in many sectors — verify for the segment); Jalali calendar library options in the chosen stack (maintained, correct leap-year handling).
+- Persian typography: a well-maintained open Persian web font (license, weights, self-host files) and the number-glyph behaviour; whether the chosen UI library documents RTL.
+
+**Legal/regulatory to flag (never answer)**
+- E-commerce trust seal (e-namad) requirements for taking online payments; personal-data and consumer-protection rules applicable to the category; content licensing for any media; VAT/invoicing rules for the business model.

package/bundled-skills/idea-to-blueprint/references/session-protocol.md

@@ -0,0 +1,133 @@
+# Session protocol — one epic per fresh session
+
+Contents: 1 Why fresh sessions · 2 What must live in the repo · 3 Session lifecycle · 4 Gates (what "done" requires) · 5 Handoff summary format · 6 PROGRESS.md and DECISIONS.md · 7 Amending the blueprint from a session · 8 Recovery · 9 Claude Code vs Codex notes · 10 `[VERIFY-AT-BUILD]` re-check rule
+
+This section is copied (adapted to the product) into section 18 of the blueprint. Its files are in `assets/`.
+
+## 1. Why fresh sessions
+
+Long agent sessions accumulate drift: forgotten constraints, half-remembered decisions, context compression. Starting each epic in a clean session forces every needed fact to live in the repo, where it is versioned, greppable and reviewable. The cost is that nothing can be assumed to be remembered — so the protocol makes the repo the memory: the blueprint says *what*, PROGRESS.md says *where we are*, DECISIONS.md says *why*, and `check` says *whether it works*.
+
+## 2. What must live in the repo (created in Epic 00)
+
+```
+docs/BLUEPRINT.md      the full blueprint (this document)
+docs/PROGRESS.md       state: epic/story status, AC evidence, deviations, next preconditions
+docs/DECISIONS.md      decision records DR-nn (from the blueprint + those made during sessions)
+AGENTS.md              Codex entry point: points at the three docs and the protocol
+CLAUDE.md              Claude Code entry point: same content
+.env.example           every variable with a one-line meaning
+<check command>        one command that runs format + lint + typecheck + tests (documented in BLUEPRINT §13.4)
+```
+
+`AGENTS.md` and `CLAUDE.md` are identical in content and short (≤ 60 lines): where the docs are, the protocol in ten lines, the `check` command, the commit format, and the rule "if it's not in BLUEPRINT or PROGRESS, ask or record — don't assume".
+
+## 3. Session lifecycle
+
+**Boot (user)** — open a fresh session in the repo, paste the session prompt for the epic (Appendix A of the blueprint; generated from `assets/session-prompt.md`).
+
+**Orient (agent)**
+1. Read `AGENTS.md`/`CLAUDE.md`, then `docs/PROGRESS.md` entirely, then `docs/BLUEPRINT.md` sections 12–16, 18, 21 and the target epic in section 17 (and any flow/screen/copy sections the epic references).
+2. Verify preconditions: previous epics DONE in PROGRESS.md; `git status` clean on the main branch; `check` green on a clean tree; env vars listed in the epic's preconditions present locally; every `[VERIFY-AT-BUILD]` item the epic depends on re-checked (see §10) and the result recorded in PROGRESS.md.
+3. If a precondition fails: stop, report exactly what fails and the fix, do not start building. The user decides.
+
+**Plan (agent)**
+4. Restate the epic goal and the story list in ≤ 15 lines. List the ACs that are unclear or reference missing IDs (there should be none; if there are, they are blueprint defects → §7).
+5. Produce the session plan: story order, the tests to write per story (from the story's Tests block), the tasks, and the manual checks the user will need to do at the end. Estimate whether it fits the session; if not, propose which stories to defer to a follow-up epic `E03b` and record it in PROGRESS.md as a deviation.
+6. Wait for "go" unless the user pre-approved ("plan and build without stopping").
+
+**Build (agent)** — for each story in order:
+7. Create a branch `epic/E03` (once per epic) if not on trunk-only.
+8. Write the tests for the story's ACs first; run `check`; the new tests must fail.
+9. Implement the tasks; run `check` after each task or story; keep it green. Copy strings come from the copy table by ID — no improvised strings.
+10. Commit per story: `feat(auth): request OTP by phone [E02-S01]` (type/scope per BLUEPRINT §13.7). Record the story as DONE in PROGRESS.md with one evidence line per AC (test name, or manual-check result).
+11. Any decision not covered by the blueprint (a library detail, a schema nuance) → add `DR-nn` to DECISIONS.md in the same commit. Any AC that turns out wrong or impossible → §7, never a silent change.
+
+**Verify (agent)**
+12. Run the full `check`; run the epic-level tests (flow e2e) and the whole regression suite; run CI (push and wait, or run the CI script locally).
+12b. **Self-review.** Walk the review checklist (BLUEPRINT §14.4) over the epic's diff, story by story, and answer every item. Do this as if reviewing someone else's work: read the diff, not your memory of writing it. Fix what fails rather than noting it. Report the result in the handoff summary as `reviewed: <n> items, <n> fixed, <n> accepted with reason` — never as a bare ✔. This pass exists because the human reviewer sees a large diff produced quickly, and their attention is the scarcest resource in the whole process; anything you can catch here is worth ten times what it costs.
+12c. If the diff for any story exceeded the size limit in §14.4, say so explicitly in the handoff. It is a signal that the story was mis-sized in the blueprint, and it is worth an amendment for the next epic.
+13. Deploy to staging per BLUEPRINT §13.8 if the epic's DoD requires it; run the smoke checks; record results.
+14. Walk the epic's Definition of Done line by line; each line gets a ✔ with evidence or the epic is not done.
+
+**Handoff (agent)**
+15. Update PROGRESS.md: epic status, per-story status, AC evidence, deviations, accepted risks, `[VERIFY-AT-BUILD]` results, next epic's preconditions and any prep the user must do (credentials, accounts).
+16. Update DECISIONS.md and the blueprint Amendments log if anything changed.
+17. Final commit; merge to main if the branch policy says so; confirm CI green.
+18. Print the handoff summary (§5) and say explicitly: "Safe to terminate this session. Next: open a fresh session and paste the E04 prompt."
+
+**Terminate (user)** — close the session. Open a new one for the next epic. Repeat.
+
+## 4. Gates
+
+An epic is DONE only when all of these are true; the agent never marks DONE otherwise:
+
+- Every story DONE with an evidence line per AC (an automated test name that passes in `check`, or a recorded manual check with observation and date).
+- `check` green on the final commit; CI green.
+- Epic-level flow tests green; all previous epics' tests green (no regressions).
+- Staging smoke checks passed when required by the DoD.
+- The review checklist (§14.4) applied to every story, with the result recorded — not "reviewed", but which items failed and what was done.
+- No gate rule weakened, disabled or bypassed to reach green; if one was, a DR entry states why and a follow-up story restores it.
+- No `TODO`/`FIXME`/skipped tests introduced without a matching PROGRESS.md "accepted risk" line with reason and owner.
+- No new flaky test; any flake observed is quarantined with a follow-up story, never re-run until green.
+- PROGRESS.md, DECISIONS.md and (if needed) the Amendments log are updated and committed.
+
+If a gate cannot be met in the session, the epic stays IN PROGRESS with an exact list of what remains; the next session resumes it (§8). Partial is fine; pretending is not.
+
+## 5. Handoff summary format (≤ 20 lines)
+
+```
+## Handoff — E03 <Title> — <date>
+Status: DONE | IN PROGRESS (remaining: E03-S04 AC-3, AC-5; staging smoke)
+Stories: E03-S01 DONE · E03-S02 DONE · E03-S03 DONE · E03-S04 IN PROGRESS
+check: green (commit abc123) · CI: green · staging: deployed, smoke 3/3
+Self-review (§14.4): 4 items failed and fixed (missing object-level auth check on API-07; N+1 in
+  order list; two tests asserted only length; SCR-04 empty state used an improvised string).
+  1 accepted: duplication detector flags the two DTO mappers — kept, extraction is E05's job.
+Diff size: E03-S02 was 620 lines, over the 400 limit — story was mis-sized, amendment A-03 splits it.
+Deviations: E03-S02 AC-4 rate limit changed 5→10 per 10 min — see Amendment A-02, DR-07
+Accepted risks: none | E03-S03 EC-MSG-01 manual only until provider sandbox supports delivery status
+VERIFY-AT-BUILD: INT-sms reachable ✔ (2026-09-05); gateway sandbox ✔
+Decisions added: DR-07, DR-08
+Next epic E04 preconditions: create staging bucket; add STORAGE_KEY to .env; nothing else
+Manual checks for you: open staging SCR-03, request a code on your phone, confirm delivery < 30 s
+Safe to terminate. Next: fresh session, paste E04 prompt.
+```
+
+## 6. PROGRESS.md and DECISIONS.md
+
+Formats are in `assets/PROGRESS.md.template` and `assets/DECISIONS.md.template`. Principles:
+
+- PROGRESS.md is a **state file, not a diary**: current status per epic and story, evidence, deviations, risks, preconditions. Session logs are one line per session at the bottom (date, epic, outcome, commit).
+- Evidence lines are specific: `AC-3 ✔ api/auth_otp_request.test::provider_timeout_returns_503` or `AC-6 ✔ manual 2026-09-05 — Persian digits render on Chrome Android 128`.
+- DECISIONS.md holds `DR-nn` entries: context, options, decision, consequences, date, epic. Blueprint DRs are copied in at Epic 00 so there is one place to look.
+
+## 7. Amending the blueprint from a session
+
+The blueprint is the source of truth, so when reality disagrees with it, the blueprint changes — explicitly:
+
+1. Do not silently implement something different from an AC.
+2. Add an entry to the **Amendments log** (section 18 of the blueprint, table `A-nn | date | epic/story | what changed | why | approved by`).
+3. Edit the affected AC/copy/architecture text in place and mark it `(amended A-nn)`.
+4. If the change affects other epics, add a line to their preconditions.
+5. Scope additions are not amendments — they are new stories in a later epic; record the idea in PROGRESS.md "Parking lot" and move on.
+
+Ask the user before amending anything that changes user-visible behaviour, money, data retention or security; smaller technical amendments can be made and reported in the handoff.
+
+## 8. Recovery
+
+- **Session crashed or was terminated mid-epic**: the next session reads PROGRESS.md, runs `git status` and `git log`, inspects the epic branch, runs `check`, and resumes from the first story/AC without evidence. Uncommitted work is inspected and either committed with a WIP note or discarded, stated in PROGRESS.md.
+- **`check` red at boot**: the previous session violated a gate. Fix the red first as a hotfix story `E03-S00 — restore green` with its own evidence, then continue.
+- **Blueprint defect found** (missing ID, contradictory ACs): treat as §7; if blocking, stop and ask.
+- **Environment broken** (missing service, credentials expired): record in PROGRESS.md, report, stop.
+
+## 9. Claude Code vs Codex notes
+
+- Both read a root instructions file: Claude Code reads `CLAUDE.md`; Codex reads `AGENTS.md`. Keep both, identical in content, pointing at the docs.
+- Skills: Claude Code discovers `SKILL.md` folders under `.claude/skills/` (project) and `~/.claude/skills/` (personal); Codex discovers the same open skill format from its skills locations (`~/.codex/skills/`, `.codex/skills/`, and `.agents/skills/` in recent versions — confirm against the current Codex docs when installing). The session protocol does not depend on skills at build time; it depends only on the repo files.
+- Invocation: paste the session prompt as the first message in either tool. If the harness exposes an effort/thinking level, set it to the maximum for planning and verification steps.
+- Verification commands must be runnable by the agent without interaction (no prompts, no watch mode). Provide a `check` that exits non-zero on failure.
+
+## 10. `[VERIFY-AT-BUILD]` re-check rule
+
+Every item tagged `[VERIFY-AT-BUILD]` in the blueprint (service availability, sandbox status, prices, sanctions/blocking status, app-store policy, library latest patch) is listed in section 18 with the epic that first depends on it. At Orient time the agent re-checks the items its epic needs (a search or a request against the sandbox), records `✔ date` or `✘ date + what changed` in PROGRESS.md, and if ✘ stops and reports before building on it.