@rashidee/co2 1.2.5

package/plugin/skills/util-projectinit/reference/co2-context-generation-guide.md

@@ -0,0 +1,761 @@
+# CO2 Context Generation Guide (v2.0)
+
+> **Purpose.** Instructions for an AI Agent participating in a brainstorming
+> session whose objective is to turn an application idea into a complete **CO2
+> project context tree**: a root `CLAUDE.md` plus one `PRD.md` per custom
+> application. This single document governs the whole flow — it supersedes and
+> combines the former `co2_claude_md.md` (CLAUDE.md brainstorming guide) and
+> `co2-artifact-generation-spec.md` (artifact generation specification).
+>
+> It is referenced from a brainstorm session document's `## References` and
+> governs both the content of the artifacts and how they are drafted round by
+> round under the brainstorm session protocol (`brainstorm-protocol.md`).
+
+---
+
+## 1. Your role in the brainstorm
+
+You are the second brain in a brainstorm. The Human has an idea — possibly
+half-formed. The brainstorm is **iterative**: you produce drafts early and
+**refine them round by round** as the conversation surfaces more detail. The
+drafts are the working artifacts — every round leaves them more complete, more
+accurate, and with fewer `[TODO]` markers than the round before.
+
+Your job each round:
+
+1. **Draft / refine** — write the current best-guess artifacts (full files, not
+   snippets) to the destination tree at the end of every agent turn.
+2. **Surface** infrastructure, applications and modules the Human has not yet
+   named but the idea clearly implies — put them in the draft, tagged
+   `[TODO: confirm]` when uncertain.
+3. **Challenge** under-specification — especially around bounded contexts. A
+   vague module list produces a vague codebase. Show the challenge as a `[TODO]`
+   in the draft and a focused question in the round.
+4. **Probe** — ask 1–5 focused questions per round, scoped to whatever part of
+   the current phase's draft is weakest. Do not interrogate; let the draft do
+   most of the talking.
+
+### 1.1 Round shape (under the session protocol)
+
+Each agent turn follows the same rhythm:
+
+- **(files)** Full draft of every in-scope artifact written to the destination
+  tree — CLAUDE.md from the very first turn; all PRDs from inventory lock.
+- **(session doc, `Output` section)** The dashboard — overridden every round
+  (see §8), including 1–3 diff bullets naming what changed since the previous
+  round (additions, splits, merges, deletions) so the Human can track drift.
+- **(session doc, `Round N` questions)** 1–5 focused questions targeting the
+  weakest area.
+
+### 1.2 First turn (Round 1 / "round 0 draft")
+
+Even when the Human gives a one-sentence idea, your first turn must already
+include a full draft CLAUDE.md skeleton in the destination tree — every
+top-level section present, populated with whatever the sentence implies, the
+rest as `[TODO]`. Never respond with questions alone. The draft is the
+conversation.
+
+### 1.3 Round-by-round refinement principles
+
+- **Never delete a draft and restart.** Refine in place. A module that survived
+  three rounds has earned its place; don't churn it without reason.
+- **Diff visibility.** Every round, name what changed since the prior round.
+- **Convergence over completeness.** Aim to reduce `[TODO]` count and module
+  churn each round. A round that adds five new `[TODO]`s without resolving any
+  old ones is a regression — flag it.
+- **Stop conditions are Human-owned.** The inventory lock (§3) and session
+  completion are the Human's calls. Present convergence evidence and ask; never
+  auto-advance.
+
+---
+
+## 2. Output artifact tree
+
+The final deliverable is a folder tree at the destination declared in the
+session's `Output Specification` (format: `co2-tree`):
+
+```
+<destination>/                          ← project root
+├── CLAUDE.md                           ← project context (§7)
+├── <app_folder_1>/
+│   └── context/
+│       └── PRD.md
+├── <app_folder_2>/
+│   └── context/
+│       └── PRD.md
+└── ...                                 ← one folder per Custom Application
+```
+
+- `<app_folder>` = snake_case of the application name (`SkolaFund Web` →
+  `skolafund_web`), matching the `# Application Folder structure` section of
+  CLAUDE.md exactly.
+- **Every** Custom Application in CLAUDE.md gets a PRD.md — including middleware,
+  adapters, CLIs and SDK libraries (library PRDs simply omit the UI-oriented
+  sections; see §11.3).
+- Generate **nothing else**: no DEVTOOL.md, no ENVIRONMENT.md, no source code,
+  no mockups, no DESIGN_SYSTEM.md (reference it as `[TODO]` where relevant), no
+  `.gitignore`. Those are downstream or per-developer concerns.
+- **Never write credentials** into any artifact. Use
+  `<to be filled by developer>` or the project standard from `# Rules`
+  (`bestrnd` / `B3st1n3t@2025`) — never invent secrets.
+
+---
+
+## 3. Two-phase flow with inventory lock
+
+PRD content is keyed by the **application × module matrix** derived from
+CLAUDE.md. Churn in that matrix after PRDs exist multiplies rework across every
+PRD file. Therefore:
+
+### Phase A — CLAUDE.md convergence
+- Rounds produce and refine **CLAUDE.md only**, per §4–§7 below (draft from the
+  first turn, diff bullets, `[TODO]` discipline, business-module pushback).
+- **Phase A additions beyond CLAUDE.md content:**
+  1. **App Codes** — assign every Custom Application a unique 2–3 letter
+     uppercase code derived from its name initials (`SkolaFund Web` → `SW`,
+     `SkolaFund Middleware` → `SM`). Codes seed requirement IDs (§11.5).
+     Resolve collisions by extending to 3 letters, confirmed with the Human.
+  2. **App × Module matrix** — maintain, in the session dashboard (§8), a
+     matrix of Custom Applications (rows) × Modules (columns) marking which
+     modules each application's PRD will contain. Every module must appear in
+     at least one application; every application must have at least one module.
+     An unmarked column is an orphan module — challenge it.
+- **Inventory lock gate.** When Phase A convergence checks pass (§9.1),
+  explicitly ask the Human to lock the inventory (applications + modules +
+  matrix). Phase B must not start before the Human answers "lock" (or
+  equivalent) in a round answer or feedback. Identity details, Rules,
+  Terminology and 3rd-party fine print may continue to evolve after lock —
+  only the app/module inventory freezes.
+
+### Phase B — PRD generation and refinement
+- On lock, scaffold every application folder and generate all PRD.md first
+  drafts in the same agent turn, then refine round by round.
+- Post-lock inventory changes are allowed **only** on explicit Human
+  instruction; when they happen, re-sync the matrix and cascade the change to
+  every affected PRD in the same turn (add/remove module sections, never
+  renumber existing IDs).
+- Round focus: rather than touching all PRDs shallowly each round, go deep on
+  the applications/modules the Human's answers targeted, and say which PRDs
+  changed in the diff bullets.
+
+---
+
+# PHASE A — CLAUDE.md
+
+## 4. The four lists you must produce
+
+Every CLAUDE.md ultimately answers four questions. Treat them as the spine of
+Phase A:
+
+| List | What it captures | Where in CLAUDE.md |
+|------|------------------|--------------------|
+| **3rd Party Services** | Infrastructure the project deploys (DBs, queues, caches, SSO) + External Services it consumes (SaaS APIs) | `# Supporting 3rd Party Applications` (+ `## External Services` sub-section) |
+| **Custom Applications** | Apps the team will build (backends, portals, adapters, SDKs, frontends) | `# Custom Applications` |
+| **System Modules** | Cross-cutting framework concerns (auth, audit, notification, …) | `# Modules` → `## System Module` → `### <Module>` |
+| **Business Modules** | Domain bounded contexts | `# Modules` → `## Business Module` → `### <Module>` |
+
+Business Modules are the hardest and the highest-leverage. Spend most of the
+brainstorm there.
+
+## 5. Probing checklist — what to ask the Human
+
+Ask these in roughly this order. Skip questions the Human has already answered.
+Loop back when an answer reveals a new branch.
+
+### 5.1 Framing
+- What problem does this solve? Who feels the pain today?
+- Who are the **actors** (every distinct user type, internal and external)?
+- What are the **outcomes** for each actor? (Convert "features" to outcomes.)
+- What is explicitly **out of scope**? (Boundaries by negation.)
+
+### 5.2 Channels & surfaces
+- Web portal? Mobile app? Public API? CLI? Embedded widget? Each is a candidate
+  custom application.
+- Is there a separate **admin / operator** interface? (Almost always yes — make
+  it explicit.)
+- Does anyone consume the system **programmatically** (partners, third-party
+  devs)? → SDK candidate.
+
+### 5.3 Data
+- What are the **major entities** (nouns the Human keeps repeating)?
+- For each: is it transactional/structured (relational) or
+  document-shaped/profile-like (NoSQL)?
+- What entities have **independent lifecycles** (created/updated/deleted on a
+  different cadence)?
+- What entities cross an **organizational boundary** (owned by a different
+  team / party)?
+- Is any data **regulated** (PII, payment, health, location)?
+
+### 5.4 Workflows
+- Walk the Human through the **happy path** for each actor. Note where one
+  actor hands off to another.
+- Where does the system **wait** for something (approval, payment, external
+  response)? Each wait is a candidate async boundary.
+- Are there **scheduled** workflows (nightly sync, monthly report, expiry
+  sweep)? → Batch Job module.
+- Are there **broadcast** flows (announcements, notifications)? → Notification
+  module + possibly News/Announcement business module.
+
+### 5.5 Integrations
+- Does the system integrate with **external** parties (banks, government,
+  partners, SaaS)?
+- Each integration: synchronous API, async event, batch file? Inbound,
+  outbound, or both?
+- Is there a **two-sided** integration (Country A ↔ Country B, Buyer ↔
+  Seller)? → adapter pair pattern.
+
+### 5.6 Non-functional cues (cheap to ask, expensive to retrofit)
+- Expected scale (users / requests / records)?
+- Compliance / region constraints (GDPR, PDPA, HIPAA, on-prem requirements)?
+- SSO required? Multi-tenancy? Audit trail requirements?
+
+If the Human cannot answer any of these, **don't invent a number** — mark it
+`[TODO]` in the draft.
+
+## 6. Deriving the four lists
+
+### 6.1 3rd Party Services — capability → service map
+
+You discover infrastructure by listening for capabilities, then mapping them.
+Apply the table below, but only pick what the conversation actually surfaced —
+**not picking** infrastructure is also a valid answer.
+
+| Signal you heard | Add this |
+|------------------|----------|
+| "users log in" / "SSO" / "roles" | **Single Sign On** — Keycloak |
+| "send email" / "notify" | **SMTP Server** — Mailcatcher (dev) |
+| "push notification" | External Service — **Firebase Cloud Messaging** |
+| "upload" / "attach" / "documents" / "files" | **File Storage** — MinIO |
+| "fast lookup" / "session" / "rate limit" | **Cache** — Redis |
+| "profiles" / "JSON-shaped data" / "flexible schema" | **Document Database** — MongoDB |
+| "transactions" / "orders" / "invoices" / "relational" | **Relational Database** — MySQL or PostgreSQL |
+| "events between services" / "fire and forget" / "fan-out" | **Message Queue** — RabbitMQ |
+| "full-text search" / "fuzzy match" / "autocomplete" | **Search** — Meilisearch |
+| "rate limit at edge" / "API key" / "throttle" | **API Gateway** — Kong |
+| "maps" / "geocoding" / "directions" | External Service — Google Maps / Mapbox |
+| "AI" / "LLM" / "embedding" | External Service — OpenAI / Anthropic |
+| "payments" | External Service — Stripe / PayPal |
+
+### 6.2 Grouping infrastructure by bounded context
+
+When the system has multiple bounded contexts (e.g., Hub vs HC vs SC, or Public
+vs Admin), give each **its own database / queue / cache** rather than one shared
+instance:
+
+- `Hub Core Database`, `Hub Support Database`, `HC Database`, `SC Database`
+- `HC Adapter Message Queue`, `SC Adapter Message Queue`
+- `Hub Cache`, `HC Cache`
+
+This is intentional. It reinforces the bounded context boundary at the
+infrastructure layer and prevents "shared DB" coupling later. **Ask the Human**
+whether contexts share storage — default to "no" unless they say yes.
+
+### 6.3 External Services vs 3rd Party Applications
+
+| Type | Definition | Goes under |
+|------|------------|------------|
+| **3rd Party Application** | The project deploys it (Docker container, K8s pod). You own the credentials and the data. | `# Supporting 3rd Party Applications` |
+| **External Service** | SaaS or remote API. The project only consumes it. Someone else operates it. | `## External Services` (sub-section) |
+
+If none are implied, omit `## External Services` entirely — do not insert a stub.
+
+### 6.4 Per-service detail to capture
+
+For each 3rd Party Application, the draft should list:
+- Technology + major version (`MongoDB version 8.x`)
+- Databases / Buckets / Vhosts as sub-bullets (one line each) — names follow
+  `<project-code-lower>_<context>_<purpose>` (e.g., `urp_hub_kc`, `urp_hub_main`)
+- `Depends on:` only when one infrastructure piece depends on another (rare —
+  usually only Keycloak depends on its DB)
+
+### 6.5 Custom Applications — common shapes
+
+A custom application is a deployable unit with its own lifecycle. Heuristics:
+
+| Shape | When to include | Naming pattern |
+|-------|-----------------|----------------|
+| **Middleware / Core service** | Almost always — the primary backend | `<Domain> Middleware` or `<Domain> Core` |
+| **Support / Admin portal** | Internal operators need a UI distinct from end-user UI | `<Domain> Support Portal` |
+| **Public-facing frontend** | End users hit a web UI | `<Domain> Web` or `<Domain> Portal` |
+| **Mobile app** | Native iOS/Android channel mentioned | `<Domain> Mobile` |
+| **Adapter** (pair) | Two-party integration (Country A ↔ Country B, Buyer ↔ Seller) | `<Side> Adapter` (e.g., `HC Adapter`, `SC Adapter`) |
+| **SDK library** | Third-party developers integrate with you | `<Side> Adapter SDK` |
+| **CLI / batch tool** | Devops or scheduled operations need an executable | `<Domain> CLI` |
+| **API Gateway / BFF** | Multiple frontends consume an aggregated API | `<Domain> Gateway` |
+
+### 6.6 Custom Application decision rules
+
+A new custom application is justified when **at least two** of these are true:
+- Different deployment cadence (releases at a different rhythm)
+- Different runtime profile (latency, scale, security posture)
+- Different audience (end user vs operator vs partner)
+- Different technology stack (mobile native vs web vs JVM service)
+- Different team ownership
+
+If only one is true, it is probably a **module inside an existing application**,
+not a new application. Push back on the Human before adding it.
+
+### 6.7 Dependency list per app
+
+Every custom application gets a `Depends on:` bullet list naming:
+- Each 3rd party application it consumes (DB, queue, cache, SSO)
+- Each external service it consumes
+- Each other custom application it calls
+
+Names must match the `## <Name>` heading they refer to **exactly**. This is
+what enables dependency validation later.
+
+### 6.8 Port allocation
+
+One port per **server-style** custom app (skip SDK libraries — they are
+libraries, not servers).
+
+| Tier | Port range |
+|------|-----------|
+| Public Layer | 8080 |
+| Tier 1 / Hub | 9001–9019 |
+| Tier 2 / HC (or "side A") | 9020–9039 |
+| Tier 3 / SC (or "side B") | 9040–9059 |
+
+Sub-domain pattern: `<type-abbr>-<tier-abbr>-<project-code-lower>`
+(`mw-hub-urp`, `sup-hub-urp`, `ad-hc-urp`). Untiered projects: allocate
+sequentially from `8080`.
+
+### 6.9 System Modules
+
+System modules are **cross-cutting framework concerns** — present in almost
+every project. Default to all seven below. Drop one only when the brief makes
+it clearly inapplicable, and ask the Human to confirm the drop.
+
+| Module | Drop when… |
+|--------|------------|
+| **Authentication and Authorization** | No users at all (rare — usually a one-off script) |
+| **User** | No users at all |
+| **Notification** | Human explicitly says "no email, no push, no in-app alerts" |
+| **Activities** | Human explicitly says "we don't track user activity feeds" |
+| **Audit Trail** | Human explicitly says "no audit / compliance need" — push back hard, this is almost always needed |
+| **Document Management** | No file/document upload anywhere in the system |
+| **Batch Job** | No scheduled work and no on-demand background processing |
+
+Each module is a `### <Module Name>` heading (three hashes) under
+`## System Module`, with **one** descriptive line. Keep it short — PRDs expand
+it in Phase B.
+
+> Use these names **verbatim**. Downstream skills (`util-projectsync`,
+> `specgen-*`) match on these exact strings.
+
+## 7. Deriving Business Modules — the hard part
+
+> **This is where bounded contexts are designed.** A weak business module list
+> produces a weak codebase, regardless of how good the rest of CLAUDE.md is.
+> Spend disproportionate effort here.
+
+### 7.1 What a Business Module is
+
+A business module is a **bounded context** — a region of the system with:
+- A **cohesive ubiquitous language** (the words inside it have a single agreed
+  meaning)
+- A **distinct lifecycle** (its entities are created/updated/deleted on their
+  own rhythm)
+- A **clear owner** (one actor or team is primarily responsible)
+- A **transactional or eventual-consistency boundary** (atomic operations stay
+  within it; cross-context work goes through events or APIs)
+
+If two candidate modules share all four properties, they are **one** module,
+not two. Merge them.
+
+If one candidate module violates any of the four (e.g., entity X is talked
+about two different ways by two different actors), it is probably **two**
+modules wearing one name. Split it.
+
+### 7.2 Signals that justify a separate Business Module
+
+Add a new module when **at least two** of these signals are present:
+
+| Signal | Example |
+|--------|---------|
+| Distinct primary actor | "Employer" managed by employers; "Candidate" managed by candidates |
+| Distinct lifecycle | Job posts expire weekly; user profiles update yearly |
+| Distinct ubiquitous language | A "Demand" in HR ≠ a "Demand" in supply chain |
+| Distinct regulatory regime | Payment data (PCI) vs profile data (GDPR) |
+| Crosses an organizational boundary | Hub-side employers vs source-country agents |
+| Distinct consistency requirement | Order placement is strongly consistent; analytics is eventually consistent |
+| Distinct integration surface | One module exposes an API to partners; another is internal-only |
+| Distinct read/write ratio | Read-heavy catalog vs write-heavy transaction log |
+
+A single signal alone is usually not enough — that's a sub-aggregate inside a
+larger module.
+
+### 7.3 Common Business Module archetypes
+
+Watch for these patterns in the conversation:
+
+| Archetype | Triggered by | Example names |
+|-----------|--------------|---------------|
+| **Dashboard** | Any portal mentions a landing/summary screen | `Dashboard` |
+| **Reference data / taxonomies** | "list of countries", "industry codes", "occupation categories" | `Location Information`, `Industrial Classification`, `Occupation Classification` |
+| **Primary entity management** | A noun the Human repeats — the thing the system is *about* | `Employer`, `Candidate Profile`, `Job Demand`, `Order`, `Booking`, `Patient` |
+| **Workflow / process** | A multi-step procedure with state transitions | `Recruitment Step`, `Onboarding`, `Claim Processing` |
+| **Cross-system sync** | Data must mirror between two contexts | `Employer Sync`, `Recruitment Agent Sync` |
+| **Marketplace / matching** | Two-sided platform with matching logic | `Job Matching`, `Talent Search` |
+| **Broadcast / announcement** | Operators publish content to many users | `News and Announcement` |
+| **Support / help desk** | Users can report issues, raise tickets, get help | `Support Ticket` |
+| **Reporting / analytics** | Operators view aggregated KPIs (distinct from ops dashboards) | `Reporting`, `Analytics` |
+| **Billing / payment** | Money changes hands | `Billing`, `Subscription` |
+| **Settings / configuration** | Tenant- or system-level configuration that is non-trivial | `Tenant Configuration`, `Feature Toggle` |
+
+You do **not** need all of these. Pick the ones the conversation actually
+surfaced.
+
+### 7.4 Anti-patterns to push back on
+
+When the Human proposes a module, run this checklist before accepting:
+
+| Anti-pattern | How it looks | How to fix |
+|--------------|--------------|-----------|
+| **CRUD-named module** | "User CRUD", "Order CRUD" | Drop the CRUD suffix. The module name is the noun. |
+| **Database-named module** | "Postgres Module", "Mongo Module" | Storage is not a context. Name by domain concept. |
+| **Layer-named module** | "Frontend Module", "API Module" | Layers are not contexts. Split by domain. |
+| **Catch-all module** | "Common", "Misc", "Utilities" | Force a name. If it can't be named, it doesn't exist yet. |
+| **One module per screen** | "Login Module", "Signup Module", "Forgot Password Module" | Collapse into `Authentication and Authorization` (system module). |
+| **Tech-named module** | "GraphQL Module", "Kafka Module" | Same as database-named. Rename by domain. |
+| **Adjective-only name** | "Premium Module", "Free Module" | Adjective ≠ context. Rename by what it *does*. |
+| **Two-noun glue module** | "Employer-and-Candidate Module" | Split into two. The "and" is a relationship, not a context. |
+
+### 7.5 Bounded context map (optional but recommended)
+
+For non-trivial projects, ask the Human to sketch the **context map** — how
+modules relate. The four relationship types worth naming:
+
+- **Upstream / Downstream** — module A's data flows into module B (B depends on A)
+- **Partnership** — two modules co-design a shared interface and evolve together
+- **Customer / Supplier** — module A consumes module B's API as-is; B owns the contract
+- **Anti-corruption layer** — module A translates module B's model to protect
+  itself from B's churn (typical between custom apps and external partners)
+
+The context map does **not** go into CLAUDE.md verbatim, but it should inform:
+- Custom application dependency lists (`Depends on:`)
+- Whether two candidates collapse into one module or stay split
+- Which 3rd-party infrastructure is grouped under which context
+
+### 7.6 Naming conventions
+
+| Rule | Example |
+|------|---------|
+| Title Case | `Recruitment Agent`, not `recruitment agent` |
+| Singular noun, not plural | `Employer`, not `Employers` |
+| Domain language, not tech | `Job Demand`, not `Job Posting Service` |
+| Avoid prefixes / suffixes | `Candidate Profile`, not `Module Candidate Profile` |
+| Match the ubiquitous language | If the Human says "Demand", do not write "Job Request" |
+
+### 7.7 CLAUDE.md draft structure
+
+When you draft, use **this exact top-level section order**. The downstream CO2
+skills depend on it.
+
+```
+# Context
+# Project Detail
+# Goals
+# Terminology
+# Development Tool       ← link to DEVTOOL.md (one line)
+# Environment            ← link to ENVIRONMENT.md (one line)
+# Supporting 3rd Party Applications
+  ## <each 3rd party app>
+  ## External Services             (omit entirely if none)
+    ### <each external service>
+# Custom Applications
+  ## <each custom app>
+# Port Allocation                  (omit entirely if no custom apps)
+# Modules
+  ## System Module
+    ### <each system module>
+  ## Business Module
+    ### <each business module>
+# Application Folder structure
+# Rules
+```
+
+#### Heading-level invariants
+
+| Level | Used for |
+|-------|----------|
+| `#` | Top-level CLAUDE.md sections (12 sections, fixed order above) |
+| `##` | Items within a section: each 3rd party app, each custom app, **and** the System/Business module *tier* headings |
+| `###` | Individual modules under `## System Module` / `## Business Module`, and each external service under `## External Services` |
+
+Modules at `###` (three hashes) is **mandatory** — `util-projectsync` matches
+modules by exactly this level. If you flatten modules to `##`, the sync skill
+silently drops them.
+
+#### Empty-section sentences
+
+Never leave a section body empty. Use the matching sentence:
+
+| Section empty | Sentence |
+|---------------|----------|
+| `# Supporting 3rd Party Applications` | `**No Supporting 3rd Party Applications for this project**` |
+| `## External Services` | Omit the heading entirely |
+| `# Custom Applications` | `**No Custom Applications for this project**` (and omit `# Port Allocation`) |
+| `## System Module` | `**There is no System Module for this project**` |
+| `## Business Module` | `**There is no Business Module for this project**` |
+
+#### Naming invariants across the file
+
+- **Project Code** is UPPERCASE (`URP`). The lowercase form (`urp`) is used
+  everywhere downstream — sub-domain suffixes, default bucket names, Keycloak
+  realm, database name prefixes.
+- Every name referenced in a `Depends on:` list **must** be an exact
+  case-sensitive match to a `## <Name>` heading elsewhere in CLAUDE.md.
+- Database / bucket / vhost names use `<project-code-lower>_<context>_<purpose>`
+  (e.g., `urp_hub_main`).
+
+#### [TODO] markers are first-class
+
+When the brainstorm leaves a question unanswered, write the best default you
+can and tag it `[TODO: <what to confirm>]` on its own line directly above the
+affected bullet or heading. Do **not** silently invent facts.
+
+---
+
+# PHASE B — PRD.md per application
+
+## 8. Draft materialization and the session dashboard
+
+- **Files are the draft channel.** On every agent turn (CLAUDE.md from the first
+  turn; all PRDs from inventory lock), write the current drafts directly to the
+  destination tree, overwriting previous drafts. The Human reviews the real
+  files in their editor — the same surface they will polish later.
+- **The session document's `Output` section holds the dashboard, not the
+  content** (overridden every round, points form):
+  1. Phase indicator (A / A-lock-pending / B) and current round
+  2. Inventory summary: project code/name, app list with App Codes and ports,
+     module counts
+  3. The App × Module matrix
+  4. `[TODO]` ledger: count per artifact + the list, so convergence is visible
+  5. Diff bullets: what changed since the previous round, per artifact
+- On session completion (`Session completion = COMPLETED`), write the final
+  tree, then place the hand-off summary (§13) under `Output > ## Final Artifact`
+  together with the destination path.
+
+## 9. Convergence gates
+
+### 9.1 Phase A → inventory lock
+
+Present these as evidence when asking the Human to lock. Until all pass, keep
+iterating Phase A:
+
+| Check | Pass condition |
+|-------|----------------|
+| **Identity** | Project Code + Project Name + one-paragraph description present and confirmed by the Human (no `[TODO]`). |
+| **Actors & channels** | Every actor named in the conversation maps to at least one Custom Application (or is explicitly out of scope). No actor without a surface; no surface without an actor. |
+| **Business modules** | Every business module has survived a round of pushback (§7.2 signals + §7.4 anti-patterns). The Human has acknowledged any modules you flagged. |
+| **TODOs** | Every remaining CLAUDE.md `[TODO]` is either (a) resolved, or (b) explicitly accepted by the Human as something to fill during polishing. |
+| **App Codes** | Assigned, collision-free. |
+| **Matrix** | Complete — no orphan modules, no module-less applications. |
+
+The Human owns the lock. Do not auto-advance even when all checks pass —
+present them and ask.
+
+### 9.2 Phase B → session completion
+
+All must pass before final hand-off:
+
+1. Every Custom Application folder + PRD exists; every matrix cell is realized
+   as a module section in the right PRD; no PRD contains an unmatrixed module.
+2. Every module section carries all five facets, each version-tagged; no
+   `### Bug` anywhere.
+3. Every User Story names an actor from CLAUDE.md's audience/actor language and
+   has at least one covering Test scenario.
+4. ID lint passes: format, widths, step-of-3, app-wide uniqueness per type,
+   app code matches the PRD's declared code.
+5. Cross-PRD consistency spot-check done (§11.4) — named in the final diff
+   bullets.
+6. Remaining `[TODO]`s are enumerated in the hand-off summary and explicitly
+   accepted by the Human.
+
+Session completion itself is signalled only by the Human via the session's
+Status table — never self-declare.
+
+## 10. Phase B round questioning — what to probe per PRD
+
+The five requirement facets have distinct purposes. Aim questions accordingly:
+
+| Facet | Determines | Probe for |
+|-------|-----------|-----------|
+| **User Story** | UI and UX | Actor-by-actor journeys per module: entry point, screens, actions, what the actor sees on success/failure. Format: "As a <actor>, I want <capability> so that <outcome>" — outcome mandatory. |
+| **Non Functional Requirement** | Validation and business logic | Field-level validation, business rules, calculations, limits, latency/pagination expectations, security posture per module. |
+| **Constraint** | Scope | What is fixed, excluded, or deferred: phase boundaries, immutable identifiers, single-provider decisions, "no hard delete", regulatory gates. |
+| **Reference** | Supporting material | Links to sibling-app model docs (`../../<backend_app>/context/model/<module-slug>/model.md` — mark `[TODO: generated later]` at brainstorm time), external API docs, standards. |
+| **Test** | Test spec design | End-to-end observable scenarios in arrange→act→assert narrative form, covering each User Story's happy path plus the highest-risk NFR/Constraint violations. |
+
+## 11. PRD.md content rules
+
+### 11.1 Canonical structure (fixed order)
+
+```
+# Context                       ← boilerplate, §11.2
+# Design System                 ← UI apps only; link + ## Layout
+# Assets                        ← UI apps only; may be a [TODO] stub at brainstorm time
+# Architecture Principle
+  ## Technology Stack
+  ## API Reference              ← apps that expose or consume APIs
+# High Level Process Flow
+# System Module
+  ## <Module>                   ← only modules marked for this app in the matrix
+    ### User Story
+    ### Non Functional Requirement
+    ### Constraint
+    ### Reference
+    ### Test
+# Business Module
+  ## <Module>                   ← same five ### facets
+```
+
+Heading-level invariants: facets at `###`, modules at `##`, top sections at
+`#`. Separate modules with `---` horizontal rules.
+
+### 11.2 Context boilerplate (standard intent, adapted per app)
+
+Every PRD opens with the standard Context bullets:
+- The document contains user stories, NFRs, constraints and references by
+  module for this application; the application name is inferred from the root
+  folder name.
+- The section-versioning contract: each facet heading carries
+  `[v{major}.{minor}.{patch}]`; major = change affecting overall understanding,
+  minor = detail-level change, patch = typo/formatting; invalidated items are
+  struck through, never deleted.
+- One bullet declaring the application's requirement-ID app code, e.g.
+  `- Requirement ID app code: SW`.
+
+### 11.3 Module inclusion and per-shape emphasis
+
+- Include **only** the modules marked for this application in the locked matrix.
+- Module names and their System/Business classification are copied **verbatim**
+  from CLAUDE.md `###` headings — never renamed, never re-tiered.
+- Every included module carries **all five facet headings**, each tagged
+  `[v1.0.0]` at generation, **even when empty** — empty facets are a legitimate
+  state meaning "nothing app-specific yet".
+- **Never generate a `### Bug` facet.** Bug is a development-lifecycle section
+  appended later by other CO2 skills.
+
+| App shape | Emphasize | Omit / stub |
+|-----------|-----------|-------------|
+| Frontend (Web/Portal/Mobile) | Design System + Layout, Assets, User Stories, client-side validation NFRs, screen-level Tests | — |
+| Middleware / Core / Adapter | Architecture Principle, API Reference, business-logic NFRs, data Constraints, integration Tests | Design System, Assets (omit sections entirely) |
+| SDK / library | API Reference (the contract), Constraints (compat/versioning), consumer-perspective Stories ("As an integrating developer…") | Design System, Assets, Port entries |
+| CLI / batch | Operator-perspective Stories, scheduling NFRs, idempotency Constraints | Design System, Assets |
+
+### 11.4 Cross-application consistency
+
+- The same business rule stated in two PRDs must not contradict; state the rule
+  authoritatively in the owning backend's PRD (as NFR/Constraint) and reference
+  it from frontend PRDs (Reference facet) rather than restating divergent
+  copies.
+- Frontend User Stories must be servable by some backend capability implied in
+  the backend PRD for the same module; when the backend side is missing, add it
+  in the same turn.
+- Architecture Principle and Technology Stack must agree with CLAUDE.md
+  `# Application Folder structure` stack declarations exactly.
+
+### 11.5 Requirement ID scheme
+
+- Format: `<TYPE><APPCODE><NUMBER>` inside square brackets, e.g. `[USSW00003]`.
+- Types and zero-padded widths:
+  `US` = 5 digits · `NFR` = 4 · `CONS` = 3 · `REF` = 4 · `TST` = 4.
+- Numbering starts at 3 and **steps by 3** (`00003, 00006, 00009 …`), leaving
+  insertion room between existing items.
+- **Uniqueness scope is the whole application (per type)** — numbering runs
+  continuously across all modules in a PRD, never resetting per module.
+- IDs are immutable once assigned: refinement edits an item's text and bumps
+  the facet version; it never renumbers. Removed items are struck through, ID
+  retained.
+
+### 11.6 [TODO] discipline (extends §7.7)
+
+- Never invent facts; write the best default and tag `[TODO: what to confirm]`
+  on its own line above the affected item.
+- PRD-specific values that must be `[TODO]` unless the Human supplied them:
+  latency numbers, pagination sizes, file-size/duration limits, retention
+  periods, external-provider choices, locale lists.
+
+---
+
+## 12. Integration with the brainstorm session protocol
+
+- The session's `Output Specification` uses `format: co2-tree`;
+  `destination` = the project root folder to scaffold; `versioning: overwrite`
+  applies to draft turns (finals inherit the same tree). When `co2-tree` is the
+  format, **this guide governs output handling** — the protocol's single-file
+  rendering step is delegated here.
+- The generated tree lives under the scan root but never matches
+  `*.brainstorm.md`, so agent writes to it do not wake the watcher.
+- All other protocol mechanics (rounds, statuses, feedback, error handling)
+  apply unchanged.
+
+## 13. Output: hand-off summary
+
+After writing the final tree, print this summary under
+`Output > ## Final Artifact` so the Human can scan-review before polishing:
+
+```
+## Final Artifact
+- Destination: ./output/<project-code-lower>/
+
+### Project
+- Code: URP
+- Name: Universal Recruitment Platform
+- One-liner: …
+
+### Inferred Inventory
+| Category               | Count | Names |
+|------------------------|-------|-------|
+| 3rd Party Applications | N     | …     |
+| External Services      | N     | …     |
+| Custom Applications    | N     | …     |
+| System Modules         | 7     | (standard set) |
+| Business Modules       | N     | …     |
+
+### PRD Inventory
+| Application (Code) | Modules | Stories | NFRs | Constraints | Tests | [TODO]s |
+|--------------------|---------|---------|------|-------------|-------|---------|
+| … one row per app …|         |         |      |             |       |         |
+
+### Open Questions ([TODO] markers across the tree)
+- [TODO] …
+
+### Recommended Next Step
+- Polish the tree, then move it into the actual project location.
+- Run `util-projectsync` to reconcile per-application folders.
+```
+
+## 14. Mandatory rules (do not skip)
+
+- **Draft from the first turn, refine every round.** Write full artifact drafts
+  to the destination tree at the end of every agent turn — never respond with
+  questions alone.
+- **Diff each round.** The dashboard opens with 1–3 bullets naming what changed
+  since the previous round. The Human must be able to track drift.
+- **Two phases, one lock.** No PRD content before the Human locks the
+  inventory; no inventory churn after lock without explicit Human instruction
+  (and full cascade when it happens).
+- **Stop only on Human signal.** Inventory lock and session completion are the
+  Human's calls — present convergence evidence and ask.
+- **Push back on weak modules.** A business module failing §7.2 (fewer than two
+  signals) or matching §7.4 (anti-patterns) gets challenged before it is
+  written.
+- **No fabricated infrastructure.** Pick only what the conversation surfaced.
+  Smaller is better.
+- **No fabricated numbers.** Missing scale / SLA / version / limit → sensible
+  default + `[TODO: confirm]`.
+- **Module heading levels are non-negotiable**: `###` under
+  `## System Module` / `## Business Module` in CLAUDE.md; `##` modules with
+  `###` facets in PRDs.
+- **Names match exactly across every file.** Dependency strings, module
+  strings, application strings — copy-paste, do not retype.
+- **IDs are immutable, unique app-wide per type, step-of-3.**
+- **No `### Bug` at generation time.**
+- **No credentials anywhere.** Placeholders or the `# Rules` project standard
+  only.
+- **Scope of generation**: CLAUDE.md + application folders + PRD.md files only.
+  No DEVTOOL.md, no ENVIRONMENT.md, no source code, no mockups.