qfai 1.3.0 → 1.3.12

package/README.md

@@ -31,15 +31,13 @@ npx qfai report
 ## What you can do (CLI commands)
 
 - `npx qfai init`
-  - Creates the QFAI workspace under `.qfai/` (requirements/specs/contracts/report) and installs the AI assistant kit (`assistant/` with prompts, instructions, agents, and steering templates for product/tech/structure/manifest), plus a default GitHub Actions workflow and `qfai.config.yaml`.
+  - Creates the QFAI workspace under `.qfai/` (requirements/specs/contracts/report) and installs the AI assistant kit (`assistant/` with prompts, instructions, agents, and steering templates), plus a default GitHub Actions workflow and `qfai.config.yaml`.
 - `npx qfai validate`
   - Validates specs/contracts/scenarios/traceability and writes `.qfai/report/validate.json`; use `--fail-on error` (or `--fail-on warning`) to turn it into a CI gate, and `--format github` to emit GitHub-friendly annotations.
 - `npx qfai report`
   - Produces a human-readable report (`report.md` by default) or an internal JSON export (`report.json`) from `validate.json`; use `--base-url` to link file paths in Markdown to your repository viewer.
 - `npx qfai doctor`
   - Diagnoses configuration discovery, path resolution, glob scanning, and `validate.json` inputs before running validate/report; use `--fail-on` to enforce failures in CI.
-- `npx qfai guardrails`
-  - Lists, extracts, or checks Decision Guardrails in `delta.md` (`list` / `extract` / `check`); use `--path` to point at target files/directories or custom locations.
 
 ## Operating model (prompt-driven workflow)
 
@@ -57,17 +55,15 @@ The agent reads QFAI assets under `.qfai/assistant/` and produces or updates SDD
 
 QFAI includes a small set of custom prompts (stored under `.qfai/assistant/prompts/`) designed to keep the workflow opinionated and repeatable.
 
-- **qfai-configure**: Analyze the repository (language, frameworks, test layout, directory structure) and update steering (`product.md`, `tech.md`, `structure.md`, `manifest.md`) plus `qfai.config.yaml` with a minimal diff (especially `testFileGlobs`, and optionally `validation.require.specSections` when you want strict headings). Run this once right after `npx qfai init`, and re-run it when the repository structure changes or when you want to enforce required spec headings. Output: updated steering + YAML + validation checklist.
-- **qfai-discuss**: Turn an idea into clear requirements via pre-knowledge research, a full question draft, and one-question-at-a-time discussion of scope, constraints, risks, and open questions.
-- **qfai-require**: Produce `require.md` in the requirements directory from your idea or discussion output.
+- **qfai-configure**: Analyze the repository (language, frameworks, test layout, directory structure) and tailor `qfai.config.yaml` accordingly (especially `testFileGlobs`). Run this once right after `npx qfai init`, and re-run it when the repository structure changes.
+- **qfai-discuss**: Turn an idea into clear requirements by discussing scope, constraints, risks, and open questions.
+- **qfai-require**: Produce `.qfai/require/require.md` from your idea or discussion output.
 - **qfai-spec**: Produce `.qfai/specs/*` and `.qfai/contracts/*` from the requirements, including traceability scaffolding.
-  - Includes a preflight step that bootstraps missing `qfai.config.yaml` and `assistant/steering/*` when run directly after init.
-- **qfai-prototyping**: Implement a minimal runnable skeleton (UI + API + DB) from contracts before test automation. Run after `/qfai-spec` to ensure the app is runnable with `pnpm dev` (or equivalent) before writing tests.
-- **qfai-atdd**: Implement acceptance tests (E2E/API/Integration), enforce layer floors, and drive Coverage Ledger to 100% (sub-agents required when supported).
-- **qfai-tdd-red**: Implement fast tests first (unit/component) and drive Unit/Component Scenario Coverage to 100% using a Coverage Ledger.
-- **qfai-tdd-green**: Implement production code to make the tests pass.
-- **qfai-tdd-refactor**: Refactor safely after tests are green.
+- **qfai-scenario-test**: Implement acceptance tests (ATDD) driven by specs/scenarios.
+- **qfai-unit-test**: Implement unit tests (TDD) driven by specs/scenarios.
+- **qfai-implement**: Implement the feature; iterate test→fix until all quality gates are green.
 - **qfai-verify**: Run/interpret the local quality gates and produce a PR-ready summary.
+- **qfai-pr**: Draft a PR description aligned with the repository’s PR template.
 
 ### Workflow sequence (example)
 
@@ -86,7 +82,7 @@ R-->>U: .qfai kit installed (prompts, instructions, agents)
 
 U->>AG: Run /qfai-configure
 AG->>Q: Read .qfai/assistant/prompts/qfai-configure.md
-AG->>R: Update qfai.config.yaml (testFileGlobs, optional specSections)
+AG->>R: Update qfai.config.yaml (testFileGlobs, etc.)
 AG-->>U: Config tuned to this repo
 
 opt If you only have an idea
@@ -100,38 +96,27 @@ AG->>R: Create/Update requirements docs
 AG-->>U: Requirements ready
 
 U->>AG: Run /qfai-spec
-Note over U,AG: /qfai-spec performs a preflight to converge config/steering when /qfai-configure is skipped.
 AG->>Q: Read .qfai/assistant/prompts/qfai-spec.md
 AG->>R: Create specs + contracts + scenario.feature
 AG-->>U: SDD artifacts ready
 
-U->>AG: Run /qfai-prototyping
-AG->>Q: Read .qfai/assistant/prompts/qfai-prototyping.md
-AG->>R: Implement minimal runnable skeleton (UI + API + DB)
-AG-->>U: Runnable prototype ready (dev server starts)
+U->>AG: Run /qfai-scenario-test
+AG->>Q: Read .qfai/assistant/prompts/qfai-scenario-test.md
+AG->>R: Implement acceptance tests
+AG-->>U: Scenario tests ready
 
-U->>AG: Run /qfai-atdd
-AG->>Q: Read .qfai/assistant/prompts/qfai-atdd.md
-AG->>R: Implement acceptance tests (3 layers + floors)
-AG-->>U: Acceptance tests ready
+U->>AG: Run /qfai-unit-test
+AG->>Q: Read .qfai/assistant/prompts/qfai-unit-test.md
+AG->>R: Implement unit tests
+AG-->>U: Unit tests ready
 
-U->>AG: Run /qfai-tdd-red
-AG->>Q: Read .qfai/assistant/prompts/qfai-tdd-red.md
-AG->>R: Implement fast tests (RED)
-AG-->>U: RED tests ready
-
-U->>AG: Run /qfai-tdd-green
-AG->>Q: Read .qfai/assistant/prompts/qfai-tdd-green.md
+U->>AG: Run /qfai-implement
+AG->>Q: Read .qfai/assistant/prompts/qfai-implement.md
 loop Implement and fix until green
 AG->>R: Implement code changes
 AG->>R: Run project tests locally
 end
-AG-->>U: Working implementation (tests green)
-
-U->>AG: Run /qfai-tdd-refactor
-AG->>Q: Read .qfai/assistant/prompts/qfai-tdd-refactor.md
-AG->>R: Refactor safely
-AG-->>U: Refactor complete
+AG-->>U: Working implementation (quality gates passing)
 
 U->>R: Run npx qfai validate
 U->>R: Run npx qfai report
@@ -141,85 +126,41 @@ R-->>U: Traceability checks and report artifacts
 Operational notes.
 
 - Each custom prompt must output in the user’s language (absolute requirement).
-- Prompts must consult instructions/steering and delta.md; rejected options must not be reintroduced without a [RE-OPEN] Decision Record.
 - Except `qfai-discuss`, each prompt must analyze the project context (architecture, tech stack, test framework, repo structure) before generating artifacts or code.
-- Prompts must delegate work to role-based sub-agents when supported; Orchestrator does not implement and Reviewer is non-edit.
-- /qfai-atdd and /qfai-tdd-red must maintain a Coverage Ledger and do not declare completion until 100% implemented (exceptions require DR + approval).
+- Prompts should delegate work to multiple role-based sub-agents (Planner, Architect, Contract Designer, QA, Code Reviewer, etc.) to emulate a real delivery flow.
+- Change classification (Primary/Tags) is required in delta.md and recommended in PRs. See `.qfai/assistant/instructions/change-classification.md`.
+- Verification planning is recorded in `delta.md` (`Verification -> Plan`) and validated in CI (`VFY-*` rules).
 
 ## Configuration
 
-Configuration is stored at the repository root as `qfai.config.yaml`.
-Most projects only customize `paths` and `validation.traceability`.
-`.qfai/require` is currently a fixed location (not configurable).
+Configuration is stored at the repository root as `qfai.config.yaml`; you can change paths, traceability policies, and CI gate thresholds.
 
-Example: a schema-valid configuration.
+Example: override paths and traceability globs.
 
 ```yaml
 paths:
-  specsDir: .qfai/specs
   contractsDir: .qfai/contracts
+  specsDir: .qfai/specs
+  requireDir: .qfai/require
   outDir: .qfai/report
   promptsDir: .qfai/assistant/prompts
   srcDir: src
   testsDir: tests
-
 validation:
   failOn: error # error | warning | never
   traceability:
     testFileGlobs:
       - "src/**/*.test.ts"
       - "tests/**/*.spec.ts"
-      - "features/**/*.feature"
     testFileExcludeGlobs:
       - "**/fixtures/**"
     scMustHaveTest: true
     scNoTestSeverity: warning # error | warning
-
-output:
-  validateJsonPath: .qfai/report/validate.json
-```
-
-### Spec validation (BR lines and required sections)
-
-BR lines are required and must use the format `- [BR-0001-0001][P1] ...` (priority P0-P3). Headings can be in any language.
-AC lines are supported with the format `- [AC-0001-0001] Given/When/Then ... (CASE-0001-0001)`.
-`validation.require.specSections` controls required H2 section titles in `spec.md`. The default is an empty list to support multi-language specs.
-If you want strict required headings, run `/qfai-configure` and specify your desired spec template headings.
-
-Example (Japanese):
-
-```yaml
-validation:
-  require:
-    specSections:
-      - 背景
-      - スコープ
-      - 非ゴール
-      - 用語
-      - 前提
-      - 決定事項
-      - 業務ルール
-```
-
-Example (English):
-
-```yaml
-validation:
-  require:
-    specSections:
-      - Background
-      - Scope
-      - Non-goals
-      - Glossary
-      - Assumptions
-      - Decisions
-      - Business Rules
 ```
 
 Notes.
 
 - `validate.json`, `report.json`, and `doctor.json` are internal exports and are not a stable external contract; prefer `report.md` for integrations that must survive tool upgrades.
-- `--strict` is a CLI option for `qfai validate` (treat warnings as failures); it is not a YAML setting.
 - Scenario files are expected to use the Gherkin extension `*.feature` (not `*.md`).
 
 ## Specifications and contracts (SDD)
@@ -233,25 +174,9 @@ QFAI uses a small, opinionated set of artifacts to reduce ambiguity and prevent
   - API contracts: YAML (`.yaml` / `.yml`)
   - DB contracts: SQL (`.sql`)
 - Scenarios (ATDD): Gherkin `.feature` files
-- Delta: append-only Change Log + Decision Records (selected/rejected; RE-OPEN required to revisit rejected options)
 
 Traceability is validated across these artifacts, so code changes remain grounded in the specs and the tests prove compliance.
 
-Traceability evidence can be provided in two ways:
-
-- `QFAI:SC-XXXX-XXXX` annotations inside test code
-- `@SC-XXXX-XXXX` tags inside `.feature` files (Cucumber-style acceptance tests)
-
-### Test strategy tags (optional)
-
-You can annotate scenarios with lightweight test strategy metadata to keep the test pyramid/trophy healthy.
-These tags are opt-in and only produce warnings, so you can roll them out gradually without breaking existing specs.
-
-- Layer tags: `@layer-unit`, `@layer-component`, `@layer-integration`, `@layer-api`, `@layer-e2e`
-- Size tags: `@size-s`, `@size-m`, `@size-l`
-
-Traceability enforcement is layer-aware: once any SC in a layer has test evidence, coverage for that layer becomes mandatory; layers without evidence are deferred until tests exist.
-
 ## Continuous integration (GitHub Actions)
 
 (GitHub Actions)
@@ -260,21 +185,9 @@ Traceability enforcement is layer-aware: once any SC in a layer has test evidenc
 
 What works out-of-the-box.
 
-- The generated workflow runs without installing repository dependencies; it only executes `npx qfai validate --fail-on error`, so it works even if your repo is not a Node project.
-- The default workflow does not enable `actions/setup-node` caching, so it does not require a lockfile.
-- If you want to pin the QFAI version, install your repo dependencies (e.g., to run tests), or enable dependency caching, customize the workflow accordingly.
+- The generated workflow is npm-oriented (`npm ci`); if your repository uses pnpm/yarn/bun, replace the install/cache steps accordingly.
 - The default validate gate fails only on `error`; use `--fail-on warning` or `--strict` if you want a stricter gate.
 
-Optional cache example (requires a lockfile):
-
-```yaml
-- uses: actions/setup-node@v4
-  with:
-    node-version: 20
-    cache: npm
-    # cache-dependency-path: package-lock.json
-```
-
 Typical customizations.
 
 - Add a second job to generate `report.md` from the uploaded `validate.json`.
@@ -291,12 +204,12 @@ Typical customizations.
 │   └── commands
 │       ├── qfai-configure.md
 │       ├── qfai-discuss.md
-│       ├── qfai-atdd.md
+│       ├── qfai-implement.md
+│       ├── qfai-pr.md
 │       ├── qfai-require.md
+│       ├── qfai-scenario-test.md
 │       ├── qfai-spec.md
-│       ├── qfai-tdd-green.md
-│       ├── qfai-tdd-red.md
-│       ├── qfai-tdd-refactor.md
+│       ├── qfai-unit-test.md
 │       └── qfai-verify.md
 ├── .codex
 │   └── skills
@@ -304,17 +217,17 @@ Typical customizations.
 │       │   └── SKILL.md
 │       ├── qfai-discuss
 │       │   └── SKILL.md
-│       ├── qfai-atdd
+│       ├── qfai-implement
 │       │   └── SKILL.md
-│       ├── qfai-require
+│       ├── qfai-pr
 │       │   └── SKILL.md
-│       ├── qfai-spec
+│       ├── qfai-require
 │       │   └── SKILL.md
-│       ├── qfai-tdd-green
+│       ├── qfai-scenario-test
 │       │   └── SKILL.md
-│       ├── qfai-tdd-red
+│       ├── qfai-spec
 │       │   └── SKILL.md
-│       ├── qfai-tdd-refactor
+│       ├── qfai-unit-test
 │       │   └── SKILL.md
 │       └── qfai-verify
 │           └── SKILL.md
@@ -322,16 +235,17 @@ Typical customizations.
 │   ├── prompts
 │   │   ├── qfai-configure.prompt.md
 │   │   ├── qfai-discuss.prompt.md
-│   │   ├── qfai-atdd.prompt.md
+│   │   ├── qfai-implement.prompt.md
+│   │   ├── qfai-pr.prompt.md
 │   │   ├── qfai-require.prompt.md
+│   │   ├── qfai-scenario-test.prompt.md
 │   │   ├── qfai-spec.prompt.md
-│   │   ├── qfai-tdd-green.prompt.md
-│   │   ├── qfai-tdd-red.prompt.md
-│   │   ├── qfai-tdd-refactor.prompt.md
+│   │   ├── qfai-unit-test.prompt.md
 │   │   └── qfai-verify.prompt.md
 │   ├── workflows
 │   │   └── qfai.yml
-│   └── copilot-instructions.md
+│   ├── copilot-instructions.md
+│   └── PULL_REQUEST_TEMPLATE.md
 ├── .qfai
 │   ├── assistant
 │   │   ├── agents
@@ -360,12 +274,12 @@ Typical customizations.
 │   │   │   ├── README.md
 │   │   │   ├── qfai-configure.md
 │   │   │   ├── qfai-discuss.md
-│   │   │   ├── qfai-atdd.md
+│   │   │   ├── qfai-implement.md
+│   │   │   ├── qfai-pr.md
 │   │   │   ├── qfai-require.md
+│   │   │   ├── qfai-scenario-test.md
 │   │   │   ├── qfai-spec.md
-│   │   │   ├── qfai-tdd-green.md
-│   │   │   ├── qfai-tdd-red.md
-│   │   │   ├── qfai-tdd-refactor.md
+│   │   │   ├── qfai-unit-test.md
 │   │   │   └── qfai-verify.md
 │   │   ├── prompts.local
 │   │   │   └── README.md
@@ -373,7 +287,6 @@ Typical customizations.
 │   │   │   ├── README.md
 │   │   │   ├── product.md
 │   │   │   ├── structure.md
-│   │   │   ├── manifest.md
 │   │   │   └── tech.md
 │   │   └── README.md
 │   ├── contracts
@@ -401,10 +314,12 @@ Typical customizations.
 
 - **GitHub Copilot prompt files**: `.github/prompts/*.prompt.md` (invoke from Copilot Chat as `/qfai-...`).
 - **GitHub Copilot repository instructions**: `.github/copilot-instructions.md` (baseline behavior guidance for Copilot in this repo).
-- **Claude Code slash commands**: `.claude/commands/*.md` (invoke as `/qfai-...`).
-- **OpenAI Codex skills**: `.codex/skills/*/SKILL.md` (invoke as Codex skills; each skill points to the canonical QFAI prompt).
+- **Claude Code slash commands**: `.claude/commands/*.md` (invoke as `/qfai-...`; commands forward to `.qfai/assistant/skills/<id>/SKILL.md`).
+- **OpenAI Codex skills**: `.codex/skills/*/SKILL.md` (invoke as Codex skills; each skill points to the canonical QFAI skill doc).
+
+Each of these files is intentionally thin and forwards to the canonical source of truth under `.qfai/assistant/` (Copilot/Claude/Codex wrappers: `skills/` -> `prompts/` (SSOT in v1.3.x)).
 
-Each of these files is intentionally thin and forwards to the canonical source of truth under `.qfai/assistant/prompts/`.
+Claude Code wrappers also use `skills/` as the entrypoint (v1.3.8+): `.claude/commands` -> `.qfai/assistant/skills/` -> `.qfai/assistant/prompts/` (SSOT in v1.3.x).
 
 ## Contributing (for QFAI maintainers)
 

package/assets/init/.qfai/README.md

@@ -25,21 +25,32 @@ flowchart TD
 
 > Formatting MUST follow the templates in each directory README.
 > Do not invent per-file formats.
+> Requirements decomposition starts from **Actors** and **Business Flows** in `require/`.
+> Keep `business-flows.md` as the top-level narrative backbone; derive REQ/SPEC/SCENARIO from BF steps.
 
 ## Directory map
 
 ```text
 .qfai/
 ├── README.md
+├── discussions/
+│   ├── README.md
+│   └── discuss-0001-<topic>.md   # discussion log (decision/evidence)
 ├── assistant/
 │   ├── prompts/            # canonical prompts (SSOT)
 │   ├── prompts.local/      # minimal overrides (project-specific)
+│   ├── skills/             # skill wrappers (experimental)
+│   ├── skills.local/       # project-specific skill overrides
 │   ├── agents/             # sub-agent missions / guardrails
 │   ├── steering/           # project steering (inputs for prompts)
 │   └── instructions/       # tool/integration instructions
 ├── require/
 │   ├── README.md
-│   └── require.md          # single requirements document
+│   ├── glossary.md         # terms (SSOT)
+│   ├── actors.md           # actor catalog (SSOT)
+│   ├── business-flows.md   # business flow catalog (SSOT)
+│   ├── require.md          # requirements (REQ-*) + BF coverage map
+│   └── open-questions.md
 ├── contracts/
 │   ├── README.md
 │   ├── api/README.md       # OpenAPI YAML style guide
@@ -53,6 +64,9 @@ flowchart TD
 │       ├── scenario.feature
 │       ├── case-catalogue.md
 │       └── traceability-matrix.md
+├── templates/
+│   └── spec/
+│       └── delta.md
 └── evidence/
     ├── README.md
     └── <prompt>-<run>.md   # completion evidence (gitignored by default)
@@ -92,9 +106,18 @@ Evidence under `.qfai/evidence/` is **gitignored by default** (see repository `.
 Templates/samples MUST live only in `.qfai/**/README.md`.
 Prompts only **reference** them to avoid double maintenance.
 
+## Skills (experimental)
+
+QFAI also ships an **assistant skills** tree at `assistant/skills/`.
+
+Currently, these `SKILL.md` files are **thin wrappers** around the canonical prompts (SSOT remains `assistant/prompts/`).
+
+Later versions will migrate SSOT from prompts to skills and update tool wrappers accordingly.
+
 ## Where to look next
 
 - Requirements format: `require/README.md`
 - Contracts format: `contracts/README.md` and sub-READMEs
 - Spec pack format: `specs/README.md`
+- Change classification (Primary/Tags): `assistant/instructions/change-classification.md`
 - Evidence rules: `evidence/README.md`

package/assets/init/.qfai/assistant/instructions/change-classification.md

@@ -0,0 +1,107 @@
+# Change Classification (Primary / Tags)
+
+To keep PR/design/review/test planning aligned, classify each change along two axes.
+
+- **Primary**: choose exactly one main purpose (mutually exclusive).
+- **Tags**: choose zero or more impacted surfaces.
+
+This classification is used in:
+
+- PR body (Change Classification)
+- `.qfai/specs/*/delta.md` Metadata
+- Review focus (QA / Architect / Code Reviewer)
+- Test strategy (which layers to add/update)
+
+---
+
+## 1. Primary (choose exactly one)
+
+Primary answers: "What is the main purpose of this change?"
+
+| Primary        | Meaning (short)                                            | Typical examples                                                                                           | Expected tests/evidence                                              |
+| -------------- | ---------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------- |
+| **Initial**    | New capability/artifact without changing existing behavior | New command/prompt, new spec pack template, new validator rule                                             | New tests are expected. Update README/templates.                     |
+| **Behavior**   | User-observable output changes                             | `validate` results change, output format/defaults change, `init` artifacts change, config/contract changes | Regression tests + acceptance updates. Note migration/compat impact. |
+| **Structural** | Internal changes with no external behavior change          | Refactor, internal algorithm swap (same output), type cleanup, deduplication                               | Existing tests should still pass; show evidence of output stability. |
+| **Ops**        | Ops/dev/distribution changes (runtime behavior unchanged)  | CI/release/packaging/scripts, docs-only, tests-only                                                        | Provide gate command evidence (format/lint/test/pack).               |
+
+### Primary decision algorithm (for AI)
+
+Pick the **first** that applies:
+
+1. **Behavior**: With the same inputs/assumptions, does user-observable output change?
+   - Example: validate error/warn changes, report output changes, `init` artifacts change, config defaults change, CLI options change.
+2. **Initial**: A new capability/artifact is added without changing existing behavior.
+   - Example: new guardrail check, new command, new template file.
+3. **Structural**: Internal structure changes but external behavior stays the same.
+4. **Ops**: None of the above; only CI/release/tooling/docs/tests.
+
+#### Common pitfalls
+
+- **`init` outputs** are user-observable. Usually **Behavior**; if only new files are added, **Initial**.
+- **Config schema/defaults/allowed inputs** changes are **Behavior** (often with `@api`).
+- **Log wording only** can be **Ops**, unless logs are part of an external contract.
+- **Tests only** is **Ops** (`@test`), but if tests accompany behavior changes, Primary is **Behavior**.
+
+---
+
+## 2. Tags (multi-select)
+
+Tags indicate which surfaces are affected. They do not replace Primary.
+
+| Tag       | Trigger condition                                            | Examples                                                                                       |
+| --------- | ------------------------------------------------------------ | ---------------------------------------------------------------------------------------------- |
+| **@api**  | Public interfaces/contracts/inputs/outputs are involved      | CLI options, `qfai.config.yaml` schema, public `validate.json` schema, contracts/specs formats |
+| **@db**   | Persisted data formats or DB contracts are involved          | `.qfai/contracts/db/*`, SQL contracts, ledger formats, report data structure                   |
+| **@nfr**  | Non-functional goals (perf/reliability/security/operability) | Performance improvements, error/recovery changes, logging/observability, security fixes        |
+| **@docs** | Documentation/templates/guides change                        | README, guides, template explanations, rules clarification                                     |
+| **@test** | Tests/verification/CI strategy change                        | Tests added/updated, fixtures updated, gate command changes                                    |
+
+### Tag selection (for AI)
+
+- You may assign tags mechanically from file types.
+- When in doubt, include the tag (over-tagging is safer than under-tagging).
+- If only `@docs` and `@test` remain, re-check whether Primary should be **Ops**.
+
+---
+
+## 3. Where to declare (required)
+
+### 3.1 PR body
+
+Include in the PR template:
+
+- Primary: `Initial | Behavior | Structural | Ops`
+- Tags: list from `@api @db @nfr @docs @test`
+- Rationale (1-3 lines)
+
+### 3.2 delta.md
+
+Include in each spec pack `delta.md` Metadata:
+
+- Primary
+- Tags
+
+Include in each DL entry `#### Verification`:
+
+- `### Plan` with one or more items (`id/level/target/method/owner/expected`)
+- If `compat: Change`, `Verification.Plan` is required
+
+---
+
+## 4. Examples
+
+### Example 1: Fix a validate misclassification bug
+
+- Primary: **Behavior** (results change)
+- Tags: **@api @test** (public output + tests)
+
+### Example 2: Parser refactor (output unchanged)
+
+- Primary: **Structural**
+- Tags: **@nfr @test** (quality/maintainability; add regression tests if needed)
+
+### Example 3: README-only update
+
+- Primary: **Ops**
+- Tags: **@docs**

package/assets/init/.qfai/assistant/instructions/requirements-decomposition.md

@@ -0,0 +1,75 @@
+# Requirements Decomposition (SSOT)
+
+## Purpose
+
+Define a **repeatable decomposition** from top-level domain context to requirements, specs, and tests.
+
+This document is the **decision rule SSOT** for AI and humans when answering:
+
+- "What is the top-level structure?"
+- "How do we break down work into spec packs?"
+- "How do we keep traceability stable?"
+
+## Canonical order (top -> down)
+
+1. **Glossary** (`require/glossary.md`)
+2. **Actors** (`require/actors.md`)
+3. **Business flows** (`require/business-flows.md`)
+4. **Requirements** (`require/require.md`)
+5. **Spec packs** (`specs/spec-*/spec.md`, `delta.md`, `scenario.feature`, `case-catalogue.md`, `traceability-matrix.md`)
+6. **ATDD / TDD** (tests + code)
+
+## Decision rules
+
+### Rule 1 - Always anchor scope to Business Flow steps
+
+- A spec pack MUST be a slice of **one or more BF steps**.
+- If a BF step is in scope, it MUST be covered by:
+  - a requirement (`REQ-*`) and/or
+  - a spec pack (`spec-*`) and/or
+  - an explicit Out-of-scope row in the Coverage Map.
+
+### Rule 2 - Use actors to remove ambiguity
+
+When writing requirements/specs/scenarios, explicitly name:
+
+- the primary actor who initiates the interaction
+- any supporting actors (external services, humans, systems)
+
+If an actor is missing, add it to `actors.md` before proceeding.
+
+### Rule 3 - Keep Glossary small but authoritative
+
+- Add terms only if they reduce ambiguity or avoid inconsistent naming.
+- Prefer **one term** with synonyms over multiple near-duplicate terms.
+- When a term changes meaning, record the decision in a discussion log.
+
+## How to decompose (mechanical procedure)
+
+1. Draft **Actors** (Primary / Supporting / System).
+2. Draft **Business Flow backbone**:
+   - 5-15 steps per flow is a useful target.
+   - Each step should be a verb phrase and observable.
+3. For each in-scope BF step, draft:
+   - a candidate user story (optional; can remain implicit)
+   - one or more atomic **REQ-FUNC** items (EARS style recommended)
+   - any **REQ-NFR** needed for the step
+4. Group BF steps into spec packs:
+   - Aim for 1-3 scenarios per spec pack.
+   - Split when scenarios exceed that or when the slice spans multiple distinct user goals.
+5. In each spec pack:
+   - Reference BF step IDs and actor IDs in `spec.md` Context.
+   - Ensure traceability matrix includes BF step IDs.
+
+## Examples
+
+### Example: One BF step -> one spec pack
+
+- BF step: `BF-0003-S02 User submits validation request`
+- Spec pack: `spec-0012`
+  - Context: Actor `ACT-0001 Developer`
+  - Traceability: `BF-0003-S02 -> REQ-FUNC-0044 -> spec-0012 -> SC-0012-01`
+
+## Non-goals
+
+- BPMN diagrams are NOT required (text-first). If you add diagrams, they are optional evidence, not SSOT.

package/assets/init/.qfai/assistant/prompts/qfai-discuss.md

@@ -21,6 +21,7 @@ mode: interactive-by-default
 ## FORMAT SSOT (Mandatory)
 
 - **Before writing or editing any `.qfai/**` artifact\*\*, read and follow the relevant directory README template and sample:
+  - `.qfai/discussions/README.md`
   - `.qfai/require/README.md`
   - `.qfai/specs/README.md`
   - `.qfai/contracts/**/README.md`
@@ -86,6 +87,7 @@ Turn a vague idea into explicit, testable requirements and decisions that downst
 ## Mandatory Outputs
 
 - Requirements Seed
+- Draft catalogs (in the discuss record): **Actors (ACT-\*)**, **Business Flows (BF-\* + step IDs)**, **Glossary seeds (TERM-\*)**
 - Decision Table (with rejected/deferred options)
 - Discuss record: `.qfai/discussions/discuss-XXXX.md`
 - Evidence file: `.qfai/evidence/discuss-<discuss-id>.md`
@@ -94,6 +96,7 @@ Turn a vague idea into explicit, testable requirements and decisions that downst
 ## Success Criteria (Definition of Done)
 
 - A “Requirements Seed” exists: goals, non-goals, constraints, acceptance criteria (high level), and open questions.
+- Draft **Actors / Business Flows / Glossary seeds** exist with stable IDs in the discuss record.
 - The output is ready to be fed into **/qfai-require** with minimal further clarification.
 - A **discuss record** is saved to `.qfai/discussions/discuss-XXXX.md` with all decisions and candidates.
 - Evidence file exists: `.qfai/evidence/discuss-<discuss-id>.md`.