archgen-skill 0.0.3 → 0.0.5

package/vendor/skills/archgen/references/artifact-templates.md

@@ -1,7 +1,166 @@
 # Artifact templates — copy, fill, never invent structure
 
+## Provenance header (SHOULD on every NEW tasks.yaml / architecture.yaml)
+
+Begin both files with three YAML comment lines. Comments are ignored by every
+consumer (skill scripts, VS Code extension, any YAML toolchain), so this is
+purely additive metadata — it can never break a parser:
+
+```yaml
+# schema_version: 1
+# generator: archgen v0.0.4
+# generated_at: 2026-08-26T09:00:00.000Z
+```
+
+Version token rules — code-defensive, NEVER guess:
+
+1. If a `.archgen-version` stamp sits next to `SKILL.md` (the installed skill
+   root) and reads as exact `MAJOR.MINOR.PATCH`, write `generator: archgen vX.Y.Z`.
+2. Else if an adjacent `archgen.config.json` carries a semver-shaped
+   `"version"` field, use that value the same way.
+3. Else omit the version token entirely: plain `# generator: archgen`.
+
+`generated_at` is one ISO-8601 timestamp per generation run (all files written
+by the same run share it). Keep the header at the very top of the file; never
+place content above it and never encode meaning anywhere except these three
+lines.
+
+Older artifacts without the header are backfilled by
+`npx archgen-skill migrate --apply` (dry-run `--check` is the default), which
+snapshots each file into `.archgen/.backup/<ts>/migrate/` before touching it
+and skips already-stamped files, so re-running is always safe.
+
+## Self-containment rules (anti-hallucination)
+
+Artifacts are executed by sessions and sub-agents that were NEVER part of the
+conversation that produced them. Hard rules, no exceptions:
+
+1. **Full paths, always.** Every task step, `file_ownership` glob, artifact,
+   and verification command uses complete repo-root-relative paths
+   (`src/features/catalog/api/routes.ts`), never bare filenames (`routes.ts`)
+   and never invented directories. Paths come from `structure:` /
+   `owns[]` in architecture.yaml or from surveyed code — nowhere else.
+2. **Names derive from naming_conventions.** Every file, symbol, table, and
+   env-var name you introduce cites WHICH convention key produced it, e.g.
+   `camelCase symbols per naming_conventions.symbol_casing`. If no key covers
+   it, add the key first, then use it.
+3. **Plans survive context summarization alone.** Any session reading ONLY
+   `.archgen/<slug>/` must execute correctly with zero chat history. If a fact
+   matters, it is written in an artifact; if it is not written, it does not
+   exist.
+4. **Forbidden phrases** (in any artifact): "as discussed", "the usual
+   pattern", "same as before", "see chat". Replace each with the concrete
+   artifact reference it was standing in for.
+5. **Cross-references are artifact-relative**, e.g.
+   `see ../architecture.yaml data_contracts.orders` or
+   `payload per ../architecture.yaml api_contracts.payments.request_payload`.
+   Never restate a contract from memory — point at it.
+6. **Verifier-compatible ids in plans.** `verify-plan.mjs` rejects any
+   UPPERCASE-numbered token in `plans/*.md` that is not a real tasks.yaml id
+   (`TASK-999` fails; your actual ids pass). So: requirement ids
+   (`FR-<MODULE>-nn`) are cited from `tasks.yaml` acceptance lines and
+   `docs/prd.md` itself; inside plan prose link the anchor instead —
+   `../docs/prd.md#fr-catalog-01`. Every tasks.yaml id MUST appear in some
+   plan file (coverage check runs both directions).
+
+## Plan depth by scope class
+
+Pick ONE class before writing any artifact; depth scales with risk, not
+enthusiasm. Misclassifying is a defect: inflating SMALL wastes tokens,
+shrinking LARGE hallucinates.
+
+- **SMALL** (add/touch few things): lean plan-note shape stays —
+
+  ```markdown
+  # <feature> — plan note (SMALL)
+  Intent: <one paragraph>
+  Tasks: see tasks.yaml entries <ids>
+  Risks: <bullets or none>
+  ```
+
+  Every task entry STILL carries absolute-from-repo-root paths verbatim —
+  in `file_ownership`, in each step, in verification commands. No Context
+  section, no diagrams, no PRD.
+
+- **MEDIUM**: `plans/<feature>.md` gains, in order:
+  - **Context** — 2–4 paragraphs max: why now, what exists, what changes.
+  - **Per-task sections** (one `<id> — <title>` heading per task):
+    Approach (short bullets) + **Edge cases** (min 3 bullets each, feeding
+    the edge-case matrix below) + **Out-of-scope** (explicit non-goals).
+  - **Verification steps** — ordered, runnable, repo-root-relative.
+  No PRD, no diagrams unless structure changed.
+
+- **LARGE / greenfield-from-scratch**: FULL professional stack — PRD
+  (`docs/prd.md`, ~1 page per major module) + expanded `architecture.yaml`
+  (naming_conventions, data_contracts, api_contracts, environment_matrix) +
+  per-task edge-case matrices + per-module diagrams + MEDIUM-grade plan
+  sections. Every diagram ≤15 nodes.
+
+## Structural correctness — verifier-enforced authoring rules
+
+- **Waves derive from `depends_on`.** Declared wave / `parallel_group` labels
+  MUST match the dependency-derived topological order — never hand-label a
+  task into a wave that contradicts its `depends_on`. A dependent task may not
+  sit in an earlier (or parallel) wave than its prerequisite.
+  `plan-graph.mjs --mermaid` is the ground truth for wave order.
+- **artifacts ⊆ file_ownership.** Every path a task lists in `artifacts` must
+  fall inside that task's `file_ownership` globs — workers can write ONLY
+  owned paths. Listing a doc the task doesn't own is a verifier-blocking
+  defect.
+- **Verification commands**: repo-root-relative (no `../`, no `--plan .`),
+  fully specific — exact commands, versions, sample sizes, thresholds — the
+  same form a worker would actually run. Generic "run the tests" or
+  wrong-root-resolved paths fail.
+- **YAML subset**: emit only the parser's supported subset — block mappings
+  and block sequences only. Avoid flow mappings (`{...}`), block scalars
+  (`|` / `>`), duplicate keys, and comma-heavy inline values, which the
+  strict parser rejects (these caused format-repair loops).
+- **tasks.yaml edits**: make small targeted edits or one clean full
+  regeneration — never large multi-region patches (they corrupted tasks.yaml
+  in the field).
+
+## Agent workspace & artifact location — the two-tier rule
+
+Location follows LIFETIME + AUDIENCE: the plan (and its rationale) travels as
+ONE self-contained, reviewable, git-versioned unit; the product's deliverables
+travel with the product.
+
+INSIDE `.archgen/<slug>/` — the plan + everything needed to execute/review it:
+- tasks.yaml, plans/, architecture.yaml, answers.yaml, codebase-map.md.
+- `docs/prd.md` — a PLANNING artifact (defines the FR-ids tasks cite), not a
+  shipped doc — stays inside so doc-index can validate FR references.
+- `decisions/NNNN-title.md` — the plan's formal ADRs (its rationale). Inside
+  keeps the feature folder self-contained and ADR↔task↔plan references valid.
+- `.agent/` — ALL agent/sub-agent working state. The leading dot keeps it out
+  of doc-index scans (process state, not a validated artifact):
+  - `.agent/decisions/NNNN-<slug>.md` — EXECUTION-time decisions a sub-agent
+    takes while working (distinct from the plan's formal ADRs in `decisions/`).
+  - `.agent/learnings.md` — conventions/patterns discovered (append-only).
+  - `.agent/notes/<task-id-or-topic>.md` — worker/survey/investigator notes.
+  - `.agent/reports/<verifier|reviewer|investigate>-<round>.md` — persisted
+    verifier/reviewer/investigation findings.
+
+OUTSIDE `.archgen/` — project DELIVERABLES an approved task produces, written
+to the task's `file_ownership` paths at the repo root (never into `.archgen/`):
+- source code (`src/...`), and
+- shipped documentation: README, API reference, deployment/runbooks, user
+  guides — the docs the running software ships to users/operators.
+
+Enterprise refinement — durable ADRs: a decision that outlives this feature
+(project-wide, e.g. "Postgres over MongoDB") SHOULD also be promoted to the
+project's canonical ADR register (`docs/adr/` or the team's equivalent) so
+future features discover it. `.archgen/<slug>/decisions/` is the working
+record; the register is the durable project-wide copy. Never delete or
+re-number an accepted ADR — supersede it.
+
 ## architecture.yaml (LARGE scope)
 
+The four contract blocks below (`naming_conventions`, `data_contracts`,
+`api_contracts`, `environment_matrix`) are THE anti-hallucination source of
+truth: tasks cite them by key instead of re-describing shapes from memory.
+Module entries extend `schemas/architecture-conventions.md` (its
+`name`/`responsibility`/`owns[]` trio is unchanged and still normative).
+
 ```yaml
 name: Acme Shop
 slug: acme-shop            # becomes .archgen/acme-shop/
@@ -17,13 +176,44 @@ structure:                 # planned folder tree — planned BEFORE code exists
     purpose: cross-feature utilities, no feature imports
   - path: src/config/
     purpose: env parsing + constants
+naming_conventions:        # filled during generation; referenced by EVERY task
+  file_naming: kebab-case files, feature folder mirrors module name
+  dir_layout: "<module>/{api,internal,tests}; shared code only in src/shared/"
+  symbol_casing: PascalCase types, camelCase functions, SCREAMING_SNAKE env
+  test_placement: colocated <name>.test.ts next to unit under test
 modules:
   - name: catalog
     responsibility: product browsing + search
     owns: ["src/features/catalog/**"]
+    depends_on_modules: []            # acyclic; drives task depends_on edges
+    key_interfaces:                   # what OTHER modules may import — nothing else
+      - CatalogApi (src/features/catalog/api/index.ts)
   - name: checkout
     responsibility: cart → payment orchestration
     owns: ["src/features/checkout/**"]
+    depends_on_modules: [catalog]
+    key_interfaces:
+      - CheckoutApi (src/features/checkout/api/index.ts)
+data_contracts:           # schemas/entities; field tables, not prose
+  orders:
+    storage: postgres table orders (migration migrations/NNNN_orders.sql)
+    fields:
+      - {field: id,         type: uuid,        required: true, notes: pk}
+      - {field: session_id, type: uuid,        required: true, notes: fk sessions}
+      - {field: total_cents, type: integer,    required: true, notes: >= 0}
+      - {field: status,     type: enum(pending,paid,failed), required: true}
+      - {field: created_at, type: timestamptz, required: true, notes: db default now()}
+api_contracts:            # endpoint/method/auth/payload/error-shape tables
+  payments:
+    - endpoint: /api/checkout/pay
+      method: POST
+      auth: session cookie; 401 when absent
+      request_payload: {order_id: uuid}
+      success: 200 {payment_id: uuid, status: paid}
+      error_shape: {code: string, message: string, retryable: boolean}
+environment_matrix:       # vars per env; unparsed vars fail fast in src/config/
+  - {var: DATABASE_URL, dev: local docker postgres, ci: ephemeral service, prod: secret ref, required: true}
+  - {var: PAYMENT_API_KEY, dev: stub key, ci: stub key, prod: secret ref, required: true}
 decisions:                 # ADR-lite; full ADRs live in decisions/
   - id: D1
     title: Postgres over MongoDB
@@ -32,6 +222,49 @@ decisions:                 # ADR-lite; full ADRs live in decisions/
     consequences: schema migrations required per release
 ```
 
+Token balance: one contract block per module/domain (~10–20 lines each);
+split further rather than letting any single block exceed ~40 lines.
+
+## Product requirements document (PRD) — LARGE/greenfield
+
+Written to `docs/prd.md` BEFORE tasks.yaml. Bullet-dense prose, zero filler
+paragraphs; target ~1 page per major module. Requirement ids here are the
+stable handles every task acceptance cites.
+
+```markdown
+# PRD — <project name>
+
+## Problem statement & goals
+- <pain, quantified where possible>
+- Goals: <3–5 outcome bullets, each measurable>
+
+## Non-goals
+- <explicitly out; prevents scope creep mid-execution>
+
+## Personas / stakeholders
+- <persona>: <need>, <success looks like>
+
+## Functional requirements — <module-name>   (repeat per module)
+- FR-<MODULE>-01: <single verifiable behavior statement>
+- FR-<MODULE>-02: ...
+<!-- ids are immutable once tasks reference them -->
+
+## Non-functional requirements (measurable targets, no adjectives)
+- Perf: p95 API latency < 300 ms at 50 rps; LCP < 2.5 s
+- Security: authz check on every endpoint; no secrets in repo; OWASP top-10 reviewed
+- i18n: all user-facing strings externalized; ICU plurals; RTL-safe layouts
+- A11y: WCAG 2.1 AA; full keyboard nav; contrast ≥ 4.5:1
+
+## Success metrics
+- <metric>: <baseline> → <target> within <window>
+
+## Risks & mitigations
+- <risk> → <mitigation>, <owner task id or ADR ref>
+
+## Open questions
+- <question> — owner <name/role>, blocks <task id | none>
+```
+
 ## tasks.yaml (canonical shape)
 
 ```yaml
@@ -41,7 +274,7 @@ tasks:
   - id: C
     title: Scaffold project skeleton + config loading
     depends_on: []
-    file_ownership: ["src/config/**", "package.json"]
+    file_ownership: ["src/config/**", "package.json"]   # FULL repo-root-relative paths, never bare filenames
     acceptance:
       - "npm run build exits 0"
       - "config loads from env with typed schema"
@@ -62,17 +295,55 @@ tasks:
 ```
 
 Rules encoded above: depends_on = prerequisites; ownership globs disjoint
-within a wave; acceptance = objectively checkable statements.
+within a wave; acceptance = objectively checkable statements. Acceptance
+bullets SHOULD reference edge-matrix rows (`E1`–`En` of that task's matrix)
+and, on LARGE, the FR ids they implement. Schema stays stable
+(`schemas/tasks.schema.json`, schema_version 1) — no new required fields;
+guidance lives in comments and plan files.
+
+LARGE-grade example task (same schema, richer acceptance — sits beside the
+minimal ones above, never replaces them):
+
+```yaml
+  - id: PAY-2
+    title: Order payment capture with retry
+    depends_on: [A]
+    parallel_group: wave-payments
+    file_ownership:
+      - src/features/checkout/internal/capture.ts       # full path per naming_conventions.dir_layout
+      - src/features/checkout/internal/capture.test.ts  # colocated per naming_conventions.test_placement
+    artifacts: ["docs/payment-retry.md"]
+    acceptance:
+      - "capture() sends idempotency key; double submit charges once (E3)"
+      - "gateway 5xx retries 3x exponential backoff, then raises PaymentFailed (E5)"
+      - "denied card → 402 with error_shape from ../architecture.yaml api_contracts.payments (FR-PAYMENTS-02)"
+      - "amounts render via session locale, cents-safe integer math (E6)"
+```
+
+## Edge-case matrix (per task, MEDIUM+)
 
-## SMALL-scope plan note (plans/<feature>.md)
+Each MEDIUM/LARGE task carries a matrix in its plan section. Every row MUST
+map to an acceptance bullet — no orphan rows; every acceptance bullet SHOULD
+trace to ≥1 row. Minimum coverage classes per task: empty/null, boundary
+values, authz denied, concurrent/conflicting write, failure/retry path,
+i18n/formatting edge. Tasks touching infra (migrations, deploys, queues)
+ADD: partial-failure recovery, rollback story.
 
 ```markdown
-# <feature> — plan note (SMALL)
-Intent: <one paragraph>
-Tasks: see tasks.yaml entries <ids>
-Risks: <bullets or none>
+| Case | Input/state                     | Expected behavior                    | Covered by |
+| ---- | ------------------------------- | ------------------------------------ | ---------- |
+| E1   | empty/null: cart with 0 items   | 200, total 0, no gateway call        | PAY-2#1    |
+| E2   | boundary: qty = max allowed 999 | accepted; 1000 rejected with 422     | PAY-2#1    |
+| E3   | concurrent: same order paid 2x  | idempotency key → single charge      | PAY-2#1    |
+| E4   | authz denied: expired session   | 401 error_shape, no state change     | PAY-2#2    |
+| E5   | failure/retry: gateway 5xx x3   | backoff retry then PaymentFailed     | PAY-2#2    |
+| E6   | i18n: locale de-DE, ¥-less cur  | EUR formatting, correct decimal comma| PAY-2#3    |
 ```
 
+`Covered by` = `<task-id>#<acceptance index>` (1-based, matching the
+tasks.yaml `acceptance` array). Rows are additive across waves; keep each
+matrix ≤10 rows — split into per-concern tables beyond that.
+
 ## ADR template (decisions/NNNN-title.md)
 
 ```markdown
@@ -103,3 +374,33 @@ graph LR
   api --> db[(Postgres)]
   api --> cache[(Redis)]
 ```
+
+## Per-module diagram (LARGE)
+
+For EACH `modules:` entry in architecture.yaml, one small flowchart of its
+internal components plus its `depends_on_modules` edges (arrow points from
+consumer to provider). Plus ONE integration diagram wiring all modules —
+edges between modules only, no internals. HARD LIMIT: ≤15 nodes per diagram;
+split into two diagrams rather than cramming. Internals stay ≤6 nodes per
+module.
+
+Catalog module (internal + inbound depends_on edge):
+
+```mermaid
+graph LR
+  subgraph catalog
+    routes[api routes] --> svc[search service]
+    svc --> repo[(product repository)]
+  end
+  checkout -.->|depends_on CatalogApi| routes
+```
+
+Integration (modules as atoms, mirrors depends_on_modules):
+
+```mermaid
+graph LR
+  accounts --> catalog
+  cart --> catalog
+  checkout --> cart
+  checkout --> accounts
+```

package/vendor/skills/archgen/references/interview.md

@@ -1,26 +1,193 @@
 # Interview playbook — requirement elicitation
 
 Goal: complete, conflict-free requirements in the FEWEST round-trips.
-Batch 3–5 questions per message. Never ask what you can infer.
+Batch 3–5 questions per message. Never ask what you can infer — ask only
+decision-forks, state everything else as a veto-able decision (§ How to ask).
 
-## Round 1 — business frame (ask the user)
+## How to ask
 
-1. What problem does this solve, and for whom? (one sentence is enough)
-2. What does success look like — measurable if possible?
-3. Hard constraints: deadline, budget, must-keep systems?
+- **Tool-first, options-fallback.** Use your harness's ask-question /
+  interactive multiple-choice tool when one exists; no such tool → ask inline
+  with labeled options. Same content either way.
+- **Recommendation-first.** Every option set leads with YOUR best judgment
+  tagged `(recommended)`, then alternatives. The user accepts the
+  recommendation by default and may override — never present bare options
+  without a recommendation.
+- **Ask forks, state decisions.** Ask ONLY the few decision-forks that
+  materially branch the plan. Everything derivative: DECIDE autonomously and
+  announce — "I'll use X because Y — say so if you'd rather Z" — so the user
+  can veto without being interrogated.
+- **Volume scales with scope.** Round caps (§ Step 1) are MAXIMA, not targets:
+  SMALL/simple prompt → at most 1–2 core questions, decide the rest; MEDIUM →
+  the targeted set; LARGE — or an experienced engineer signaling they want
+  control → the fuller discovery set.
 
-## Round 2 — technical frame (infer first, confirm second)
+Worked example (recommendation-first, inline fallback form):
+
+> Rollout strategy?
+> 1. Feature flag + staged rollout **(recommended)** — existing users unaffected
+> 2. Immediate cutover — simpler, riskier
+> 3. Versioned API alongside — only if existing clients break
+> Reply 1–3, or just "ok" to accept the recommendation.
+
+## Round 0 — calibration exchange (skippable)
+
+Two or three rapid items, asked once at the very start — each INFERRED first
+(§ How to ask), asked only when genuinely ambiguous:
+
+1. Rough scale: prototype, MVP, or production-bound? INFER from the opening
+   message + repo context; state the inference + one line of reasoning and
+   let the user confirm or correct. Ask open-ended ONLY when genuinely
+   ambiguous.
+2. Team size + convention constraints? (solo? existing lint/CI/style guides?)
+3. Deadline pressure: none, moderate, crunch?
+
+Purpose is ONLY to pick question-set depth and right-size later verification
+rigor — never to collect requirements. SKIP the whole exchange when the user's
+opening message already answers these items (e.g. "quick prototype by
+Friday"); SMALL/simple prompts skip calibration entirely and go straight to
+their 1–2 core forks (§ How to ask). Record whatever was captured under
+`calibration:` in answers.yaml.
+
+## Step 1 — classify intent (decide during round 1)
+
+From the opening message + calibration, decide ONE intent class, state it to
+the user in one sentence, and record it as `intent_class` in answers.yaml:
+
+| intent_class | Signal | Question depth | Round cap |
+|---|---|---|---|
+| GREENFIELD-SYSTEM | net-new product/system from scratch; no host repo | full PRD-grade discovery | ≤6 |
+| GREENFIELD-MODULE | net-new capability inside an existing system/repo | targeted; infer from host repo first | ≤3 |
+| BROWNFIELD-FEATURE | existing repo, additive behavior | survey-first; ask only survey gaps (max ~5 questions) | ≤3 |
+| BROWNFIELD-CHANGE | modify existing behavior in place | survey-first; diff current vs desired | ≤3 |
+
+Never interrogate a BROWNFIELD-FEATURE with PRD-grade questions — token waste,
+user annoyance. Round caps INCLUDE round 0 when it runs.
+
+Default `scope_class` from the intent class (user's choice wins — scope_class
+is agreed in GENERATE step 1 and recorded in answers.yaml):
+GREENFIELD-SYSTEM→LARGE, GREENFIELD-MODULE→MEDIUM,
+BROWNFIELD-FEATURE→MEDIUM/SMALL, BROWNFIELD-CHANGE→SMALL.
+
+Scale is INFERRED, not asked: derive scope_class from the opening message +
+repo context + the class above, state it with one line of reasoning, and let
+the user confirm or correct. Ask about scale ONLY when genuinely
+ambiguous/confused. Small/simple prompts: skip heavy calibration, ask only
+the 1–2 core forks (§ How to ask), decide the rest.
+
+## GREENFIELD-SYSTEM — professional discovery (≤6 rounds)
+
+Creating a system from scratch demands PRD-grade inputs. Each round below
+lists its questions and where the answers land (`feeds:` tags — see
+Traceability).
+
+### R1 — problem, users, success → PRD
+
+1. What problem does this solve, for whom — and what is explicitly NOT a goal?
+2. Who uses it? Sketch 1–3 personas: role, key job-to-be-done, environment.
+3. What does success look like — measurable (activation, conversion,
+   time-saved, error rate)? Adjectives are not metrics.
+
+### R2 — shape & module decomposition → architecture.yaml `modules`
+
+Infer stack/hosting from stated preferences, then confirm:
 
-Draft answers from context (existing repo, stated stack), then confirm:
 4. Stack + hosting target correct? (state your inference)
-5. Scale expectation: users/reqs/day, data growth?
-6. Integration surfaces: auth, payments, email, existing APIs?
+5. Integration surfaces: auth, payments, email, existing APIs?
+
+Then PROPOSE a strawman module map from the domain talk — one line per
+candidate module as `name — responsibility` (mirroring `modules[]`:
+name/responsibility/owns) — and ask the user to react:
+
+6. React to this strawman module map: [list]. What is missing, misnamed, or
+   should be merged/split? Iterate until agreement — this seeds
+   architecture.yaml `modules`.
+
+### R3 — data & API sketches → `data_contracts`, `api_contracts`
+
+7. Core data entities and relationships — one line each: Entity — key fields —
+   belongs-to / has-many? (seeds `data_contracts`)
+8. Primary API surface: the 5–10 operations users/systems perform, verb +
+   resource? (seeds `api_contracts`)
+
+### R4 — NFRs with numbers → PRD
+
+Numbers or it didn't happen — reject "fast"/"scalable" without figures.
 
-## Round 3 — constraints & risks
+9. Performance budgets: p95 latency, throughput at peak?
+10. Scale targets: users, reqs/day, data growth per year?
+11. Security/compliance checklist level (GDPR/HIPAA/PCI)? i18n locales?
+    Accessibility level (e.g. WCAG 2.2 AA)?
 
-7. Compliance needs? (GDPR/HIPAA/PCI — checklist level only)
-8. What must NOT change?
-9. Top 2 risks the user already knows about?
+### R5 — environment & naming → `environment_matrix`, `naming_conventions`
+
+12. Environment/deploy reality: which environments exist (dev/staging/prod),
+    hosting, config/secrets handling, deploy cadence? (seeds
+    `environment_matrix`)
+13. Naming/brand conventions that already exist: product-name casing, domain
+    terms to preserve, UI copy language(s)? (seeds `naming_conventions`;
+    "none" is a valid answer)
+
+### R6 — close-out → PRD
+
+14. Explicit out-of-scope list — adjacent things on record as NOT in this build?
+15. Top 2 risks you already know about?
+
+Close by presenting the agreed module map + captured NFR numbers for final
+confirmation ([wait for user]).
+
+### Traceability — `feeds:` tags
+
+Every recorded answer MAY carry a `feeds:` tag naming the artifact section it
+lands in. Keep the vocabulary literal — downstream templates consume these
+exact names:
+
+- PRD sections: `prd.problem`, `prd.goals`, `prd.non_goals`, `prd.personas`,
+  `prd.metrics`, `prd.nfrs`, `prd.constraints`, `prd.integrations`,
+  `prd.risks`, `prd.out_of_scope`
+- architecture.yaml keys: `arch.modules`, `arch.data_contracts`,
+  `arch.api_contracts`, `arch.environment_matrix`, `arch.naming_conventions`
+
+Multiple targets join with `|`, e.g. `feeds: prd.goals|arch.modules`.
+
+## GREENFIELD-MODULE — net-new inside an existing system (≤3 rounds)
+
+Infer first from the host repo (structure, conventions, neighboring modules),
+confirm second:
+
+1. Where does it plug in — which host modules does it read from / expose to?
+2. Contract with the host: data it consumes/produces, APIs or events it
+   exposes? (seeds `data_contracts` / `api_contracts` deltas)
+3. Inherited vs new NFRs: follow host perf/a11y/i18n baselines or set new ones?
+4. Naming follows host conventions — confirm? (seeds `naming_conventions`)
+
+## BROWNFIELD classes — survey BEFORE questioning (mandatory)
+
+Run the survey first (SKILL.md BROWNFIELD steps 1–2): prefer the codegraph MCP
+(`codegraph_explore`) when configured, else structured glob/grep; produce or
+update `.archgen/<slug>/codebase-map.md`. Then ask ONLY what the survey could
+not answer. NEVER ask what a file already answers — quote the file and ask for
+confirmation instead.
+
+### BROWNFIELD-FEATURE (additive; max ~5 questions, one batched message)
+
+Ask only unresolved gaps, typically:
+
+1. Acceptance criteria the code cannot reveal — exact expected behavior, edge
+   cases that matter.
+2. Back-compat expectations for existing records or clients.
+3. Rollout preference: feature flag, staged, immediate?
+4. Must-NOT-touch paths beyond what the map shows?
+5. Anything the codebase-map got wrong?
+
+### BROWNFIELD-CHANGE (behavior modification; ≤3 rounds)
+
+Survey focus: current behavior + blast radius (callers, tests, consumers).
+
+1. Current vs desired behavior — precise diff, including what must stay.
+2. Compatibility: migrate in place, version alongside, or breaking change?
+3. Acceptance for "changed": how do we prove old behavior is gone and the new
+   behavior holds?
 
 ## Conflict detection
 
@@ -32,18 +199,47 @@ While collecting, watch for and surface immediately:
 Format: "I see a tension between X and Y. Which wins?" — one per message,
 resolve before proceeding. [wait for user]
 
+## Token discipline
+
+- Batch 3–5 questions per message; never ping-pong one-per-message.
+- Hard round caps — MAXIMA, not targets (small prompts ask far fewer;
+  § How to ask): GREENFIELD-SYSTEM ≤6 rounds, every other class ≤3
+  (round 0 counts when it runs).
+- Skip any question already answered by the opening message, calibration, or
+  survey artifacts.
+
 ## Answers-file format (machine-readable, enables non-interactive runs)
 
 For scripted E2E or re-runs, requirements may come from a file instead of
 conversation — `.archgen/<slug>/answers.yaml`:
 
 ```yaml
-scope_class: MEDIUM        # SMALL | MEDIUM | LARGE
+scope_class: MEDIUM        # SMALL | MEDIUM | LARGE — UNCHANGED; SKILL.md reads
+                           # this for right-sizing. Never remove or rename.
+intent_class: GREENFIELD-SYSTEM  # optional: GREENFIELD-SYSTEM |
+                           # GREENFIELD-MODULE | BROWNFIELD-FEATURE |
+                           # BROWNFIELD-CHANGE
+calibration:               # optional — from round 0
+  scale: production        # prototype | mvp | production
+  teamConstraints: solo dev, repo lint rules apply
+  pressure: medium         # low | medium | high
 problem: one-line problem statement
 success_criteria:
-  - measurable outcome
+  - text: measurable outcome          # structured entries MAY carry feeds:
+    feeds: prd.metrics
 constraints:
-  - must-not-change items
+  - must-not-change item              # plain scalars stay valid; tag via
+                                      # trailing comment:  # feeds: prd.constraints
+non_goals:                 # optional (GREENFIELD-SYSTEM)
+  - multi-tenant accounts
+personas:                  # optional (GREENFIELD-SYSTEM)
+  - role: shopper
+    goal: find and buy in under two minutes
+nfrs:                      # optional; NUMBERS required for GREENFIELD-SYSTEM
+  - "p95 API latency < 300ms at 50 rps"
+  - "locales: en, de"
+  - "accessibility: WCAG 2.2 AA"
+out_of_scope: []           # optional
 stack:
   language: typescript
   runtime: node
@@ -54,13 +250,26 @@ risks:
   - known risk text
 ```
 
+Backward compatibility: ALL additions (`intent_class`, `calibration`,
+`non_goals`, `personas`, `nfrs`, `out_of_scope`, per-answer `feeds:` tags) are
+OPTIONAL. Existing fields keep their names and semantics; `scope_class` is
+retained verbatim because SKILL.md consumes it. Consumers that do not trace
+provenance ignore `feeds:` tags in both forms (sibling key on structured
+entries, trailing comment on plain scalars).
+
 The orchestrator treats answers.yaml as authoritative user input and skips
 the conversational rounds when it exists and parses cleanly.
 
 ## Completion test
 
 Requirements are done when ALL hold:
-- Every ROUND-1 question answered
+- Every applicable question in the chosen intent class's question set answered
+  (or explicitly waived by the user)
 - All drafted inferences confirmed or corrected
 - Zero unresolved conflicts
 - Scope class agreed (SMALL/MEDIUM/LARGE) — this gates artifact generation
+  (unchanged; SKILL.md consumes it)
+- Chosen `intent_class` recorded in answers.yaml
+- GREENFIELD-SYSTEM only: module-map agreement reached (user reacted to the
+  strawman and the revision is confirmed) AND NFR numbers captured — an NFR
+  without a number fails this gate