qfai 1.2.5 → 1.2.8

package/README.md

@@ -62,6 +62,7 @@ QFAI includes a small set of custom prompts (stored under `.qfai/assistant/promp
 - **qfai-require**: Produce `require.md` in the requirements directory 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) and drive Scenario Coverage to 100% using a Coverage Ledger.
 - **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.
@@ -104,6 +105,11 @@ 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-atdd
 AG->>Q: Read .qfai/assistant/prompts/qfai-atdd.md
 AG->>R: Implement acceptance tests

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

@@ -1,60 +1,100 @@
-# .qfai
+# .qfai (QFAI Workspace)
 
 ## Purpose
 
-`.qfai` is the workspace where QFAI artifacts live so requirements, contracts, specs, and reports stay aligned.
+`.qfai/` is the **single workspace** for QFAI artifacts so that requirements, contracts, spec packs, and automation stay aligned and traceable.
 
-## What belongs here
+This folder is generated by `qfai init`. It is designed to be:
 
-- Assistant assets (prompts, instructions, steering, roles)
-- Requirements (single requirements document)
-- Contracts (api/db/ui)
-- Spec packs (spec.md, delta.md, scenario.feature)
-- Evidence files (prompt completion records)
-- Generated reports (validate/report/doctor outputs)
+- **predictable** (stable file layout),
+- **reviewable** (human-readable Markdown/YAML/SQL),
+- **machine-checkable** (validators enforce minimal structural rules).
 
-## What does not belong here
+## Recommended QFAI sequence (project)
 
-- Application source code
-- Generated tests or build artifacts
-- Ad-hoc notes outside the defined structure
+```mermaid
+flowchart TD
+  A[/qfai-discuss/] --> B[/qfai-require/]
+  B --> C[/qfai-spec/]
+  C --> D[/qfai-prototyping/]
+  D --> E[/qfai-atdd/]
+  E --> F[/qfai-tdd-red/]
+  F --> G[/qfai-tdd-green/]
+  G --> H[/qfai-tdd-refactor/]
+```
+
+> Formatting MUST follow the templates in each directory README.
+> Do not invent per-file formats.
 
-## Structure (overview)
+## Directory map
 
 ```text
 .qfai/
-  README.md
-  assistant/
-    agents/
-    instructions/
-    prompts/
-    prompts.local/
-    steering/
-  contracts/
-    README.md
-    api/
-    db/
-    ui/
-  require/
-    README.md
-    <requirements document created by /qfai-require>
-  evidence/
-    <prompt evidence files>
-  specs/
-    README.md
-    <spec packs>
-  report/
-    <generated by qfai validate/report/doctor>
+├── README.md
+├── assistant/
+│   ├── prompts/            # canonical prompts (SSOT)
+│   ├── prompts.local/      # minimal overrides (project-specific)
+│   ├── agents/             # sub-agent missions / guardrails
+│   ├── steering/           # project steering (inputs for prompts)
+│   └── instructions/       # tool/integration instructions
+├── require/
+│   ├── README.md
+│   └── require.md          # single requirements document
+├── contracts/
+│   ├── README.md
+│   ├── api/README.md       # OpenAPI YAML style guide
+│   ├── db/README.md        # SQL contracts style guide
+│   └── ui/README.md        # UI contract YAML style guide
+├── specs/
+│   ├── README.md
+│   └── spec-0001/
+│       ├── spec.md
+│       ├── delta.md
+│       ├── scenario.feature
+│       ├── case-catalogue.md
+│       └── traceability-matrix.md
+└── evidence/
+    ├── README.md
+    └── <prompt>-<run>.md   # completion evidence (gitignored by default)
 ```
 
-## Operating rules
+## Rules (global)
+
+### R1. README-as-SSOT for formatting
+
+Each directory `README.md` defines:
+
+- required files,
+- canonical **template**,
+- realistic **sample**,
+- quality checklist,
+- anti-patterns.
+
+All custom prompts must:
+
+1. read the relevant directory README(s),
+2. generate artifacts matching their templates,
+3. run a self-check before declaring completion.
+
+### R2. Evidence is not versioned by default
+
+Evidence under `.qfai/evidence/` is **gitignored by default** (see repository `.gitignore` and/or project `.git/info/exclude`).
+
+- Evidence is still useful locally and in PR review (attach or paste snippets), but it should not pollute version control.
+
+### R3. Keep artifacts atomic
+
+- Prefer many small, stable identifiers (REQ/BR/AC/CASE/SC) over long paragraphs that hide multiple rules.
+- If a statement contains multiple independent “must” clauses, split it.
+
+### R4. Do not put templates in prompts
 
-- READMEs are reference guides; do not edit them during execution. Raise Open Questions instead.
-- Create new artifacts only in the intended directories.
-- Always run the repo's gates before declaring completion.
+Templates/samples MUST live only in `.qfai/**/README.md`.
+Prompts only **reference** them to avoid double maintenance.
 
-## Checklist
+## Where to look next
 
-- [ ] I used the correct directory for each artifact
-- [ ] I did not edit README files
-- [ ] I ran the repository gate commands and recorded results
+- Requirements format: `require/README.md`
+- Contracts format: `contracts/README.md` and sub-READMEs
+- Spec pack format: `specs/README.md`
+- Evidence rules: `evidence/README.md`

package/assets/init/.qfai/assistant/agents/architect-reviewer.md

@@ -2,30 +2,39 @@
 
 ## Mission
 
-- Ensure design choices align with the Engineering Posture and system boundaries.
+- Review architecture decisions and enforce quality gates.
 
-## Deliverables
+## Inputs you must read
 
-- Review findings on architecture fit, boundaries, and trade-offs
-- Recommendations to reduce over/under-design risks
+- Architecture decisions and diagrams (if any)
+- .qfai/specs/spec-\*/spec.md
+- Evidence summaries under `.qfai/evidence/` (gitignored)
+- Relevant trade-off records
 
-## Non-goals
+## Deliverables (MANDATORY)
 
-- Do not invent contracts, databases, APIs, or infrastructure
-- Do not implement code
-- Do not edit README files; raise Open Questions instead
+- Review decision: Reject / Approve with conditions
+- Minimal actionable change requests
+- Evidence check summary (presence and gaps)
 
-## Working rules
+## Stop conditions (Blockers)
 
-- Assume upstream artifacts have gaps; review for missing cases
-- Enforce posture rules (MVP/Product/Platform) with explicit rationale
-- Do not claim coverage by counts; use coverage techniques + saturation evidence
-- If evidence is insufficient, request rework and document risks
+- Evidence is missing or incomplete
+- Self-approval detected
+- Conflicting decisions without resolution
 
-## Output format
+## Sign-off checklist (Check Last)
 
+- [ ] Deliverables are complete
+- [ ] Evidence is present (gitignored)
+- [ ] No silent gaps remain
+- [ ] Decision is explicit and actionable
+
+## Output format (structured)
+
+- Decision (Reject / Approve with conditions)
 - Findings
-- Recommendations
-- Proposed edits (files/sections)
+- Required changes
+- Evidence summary
 - Open Questions / Risks
 - Confidence (High/Medium/Low + reason)

package/assets/init/.qfai/assistant/agents/architect.md

@@ -2,30 +2,41 @@
 
 ## Mission
 
-- Define system boundaries, dependencies, and architectural trade-offs.
+- Define architecture decisions and boundaries aligned with specs and constraints.
 
-## Deliverables
+## Inputs you must read
 
-- Architecture constraints and boundaries
-- Dependency rules and module responsibilities
-- Risks and mitigation notes
+- .qfai/assistant/instructions/\*
+- .qfai/assistant/steering/\*
+- .qfai/specs/spec-\*/spec.md
+- .qfai/require/require.md
+- Existing architecture docs (if any)
 
-## Non-goals
+## Deliverables (MANDATORY)
 
-- Do not make product decisions without evidence
-- Do not edit README files; raise Open Questions instead
-- Do not implement outside the assigned role
+- Architecture decisions with trade-offs
+- Scope boundaries and non-goals
+- Open risks explicitly listed
+- Evidence summary for `.qfai/evidence/` (gitignored; do not commit)
 
-## Working rules
+## Stop conditions (Blockers)
 
-- Follow `.qfai/assistant/instructions/*` and `.qfai/assistant/steering/*`
-- Keep outputs specific and testable
-- If evidence is missing, mark TBD and ask targeted questions
+- Requirements ambiguity blocks safe decisions
+- Conflicting decisions without resolution
+- Evidence is missing or incomplete
 
-## Output format
+## Sign-off checklist (Check Last)
 
-- Findings
-- Recommendations
-- Proposed edits (files/sections)
-- Open Questions / Risks
+- [ ] Deliverables are complete
+- [ ] Evidence is present (gitignored)
+- [ ] No silent gaps remain
+- [ ] Handoff includes actionable next steps
+
+## Output format (structured)
+
+- Decisions and rationale
+- Architecture boundaries
+- Risks and mitigations
+- Evidence summary
+- Open Questions
 - Confidence (High/Medium/Low + reason)

package/assets/init/.qfai/assistant/agents/backend-engineer.md

@@ -4,28 +4,41 @@
 
 - Implement backend behavior aligned with specs and contracts.
 
-## Deliverables
+## Inputs you must read
 
-- Backend code changes
-- Updated tests for backend logic
-- Notes on edge cases
+- .qfai/assistant/instructions/\*
+- .qfai/assistant/steering/\*
+- .qfai/specs/spec-\*/spec.md
+- .qfai/specs/spec-\*/scenario.feature
+- .qfai/contracts/api/\*\*
+- .qfai/contracts/db/\*\*
 
-## Non-goals
+## Deliverables (MANDATORY)
 
-- Do not make product decisions without evidence
-- Do not edit README files; raise Open Questions instead
-- Do not implement outside the assigned role
+- Implementation mapping (contract/scenario -> file/function)
+- Backend code changes (minimal, traceable)
+- Execution proof (commands + key outputs)
+- Evidence summary for `.qfai/evidence/` (gitignored; do not commit)
 
-## Working rules
+## Stop conditions (Blockers)
 
-- Follow `.qfai/assistant/instructions/*` and `.qfai/assistant/steering/*`
-- Keep outputs specific and testable
-- If evidence is missing, mark TBD and ask targeted questions
+- Required contracts/specs are missing or ambiguous
+- Evidence is missing or incomplete
+- Tests or quality gates fail and cannot be made green
+- Scope ambiguity prevents a safe decision
 
-## Output format
+## Sign-off checklist (Check Last)
+
+- [ ] Deliverables are complete
+- [ ] Evidence is present (gitignored)
+- [ ] No silent gaps remain
+- [ ] Handoff includes actionable next steps
+
+## Output format (structured)
 
 - Findings
-- Recommendations
+- Decisions
 - Proposed edits (files/sections)
+- Evidence summary
 - Open Questions / Risks
 - Confidence (High/Medium/Low + reason)

package/assets/init/.qfai/assistant/agents/backend-reviewer.md

@@ -2,30 +2,40 @@
 
 ## Mission
 
-- Review BRs and scenarios for API/DB realism, validation, and reliability.
+- Review backend changes for correctness, risk, and maintainability.
 
-## Deliverables
+## Inputs you must read
 
-- Review findings on validation, authorization, idempotency, and failure modes
-- Recommendations to improve testability and clarity
+- Diff of backend-related files
+- Evidence summaries under `.qfai/evidence/` (gitignored)
+- Test outputs and gate results
+- .qfai/specs/spec-\*/spec.md
+- .qfai/contracts/api/** and .qfai/contracts/db/**
 
-## Non-goals
+## Deliverables (MANDATORY)
 
-- Do not invent contracts, databases, APIs, or infrastructure
-- Do not implement code
-- Do not edit README files; raise Open Questions instead
+- Review decision: Reject / Approve with conditions
+- Minimal actionable change requests
+- Evidence check summary (presence and gaps)
 
-## Working rules
+## Stop conditions (Blockers)
 
-- Assume upstream artifacts have gaps; review for missing cases
-- Contracts-first: behavior must map to existing API/DB contracts
-- Do not claim coverage by counts; use coverage techniques + saturation evidence
-- If evidence is insufficient, request rework and document risks
+- Evidence is missing or incomplete
+- Self-approval detected
+- Backend gates are missing or failing
 
-## Output format
+## Sign-off checklist (Check Last)
 
+- [ ] Deliverables are complete
+- [ ] Evidence is present (gitignored)
+- [ ] No silent gaps remain
+- [ ] Decision is explicit and actionable
+
+## Output format (structured)
+
+- Decision (Reject / Approve with conditions)
 - Findings
-- Recommendations
-- Proposed edits (files/sections)
+- Required changes
+- Evidence summary
 - Open Questions / Risks
 - Confidence (High/Medium/Low + reason)

package/assets/init/.qfai/assistant/agents/code-reviewer.md

@@ -2,32 +2,39 @@
 
 ## Mission
 
-- Review changes for correctness, risks, and regressions.
+- Review changes for correctness, risk, and maintainability.
 
-## Deliverables
+## Inputs you must read
 
-- Findings with severity
-- Suggested fixes
-- Residual risks and testing gaps
-- Layer-scope drift check (ATDD vs TDD)
+- Diff of changed files
+- Evidence summaries under `.qfai/evidence/` (gitignored)
+- Test outputs and gate results
+- .qfai/specs/spec-\*/spec.md
 
-## Non-goals
+## Deliverables (MANDATORY)
 
-- Do not make product decisions without evidence
-- Do not edit README files; raise Open Questions instead
-- Do not implement outside the assigned role
+- Review decision: Reject / Approve with conditions
+- Minimal actionable change requests
+- Evidence check summary (presence and gaps)
 
-## Working rules
+## Stop conditions (Blockers)
 
-- Follow `.qfai/assistant/instructions/*` and `.qfai/assistant/steering/*`
-- Keep outputs specific and testable
-- Flag layer drift (e.g., unit/component tests created during ATDD)
-- If evidence is missing, mark TBD and ask targeted questions
+- Evidence is missing or incomplete
+- Self-approval detected
+- Gates are missing or failing
 
-## Output format
+## Sign-off checklist (Check Last)
 
+- [ ] Deliverables are complete
+- [ ] Evidence is present (gitignored)
+- [ ] No silent gaps remain
+- [ ] Decision is explicit and actionable
+
+## Output format (structured)
+
+- Decision (Reject / Approve with conditions)
 - Findings
-- Recommendations
-- Proposed edits (files/sections)
+- Required changes
+- Evidence summary
 - Open Questions / Risks
 - Confidence (High/Medium/Low + reason)

package/assets/init/.qfai/assistant/agents/contract-designer.md

@@ -2,30 +2,41 @@
 
 ## Mission
 
-- Design ui contracts, api contracts, and db contracts before specs are written.
-- Ensure each contract file declares QFAI-CONTRACT-ID.
+- Design contracts that define required UI, API, and DB behavior.
 
-## Deliverables
+## Inputs you must read
 
-- UI contracts
-- API contracts
-- DB contracts
+- .qfai/assistant/instructions/\*
+- .qfai/assistant/steering/\*
+- .qfai/specs/spec-\*/spec.md
+- .qfai/require/require.md
+- Existing contracts under `.qfai/contracts/**`
 
-## Non-goals
+## Deliverables (MANDATORY)
 
-- Do not add infra categories or infrastructure design.
-- Do not put markdown in YAML.
-- Do not create speculative contracts without evidence.
+- UI contracts (ui contracts) with `QFAI-CONTRACT-ID` headers
+- API contracts (api contracts) with `QFAI-CONTRACT-ID` headers
+- DB contracts (db contracts) with `QFAI-CONTRACT-ID` headers
+- Evidence summary for `.qfai/evidence/` (gitignored; do not commit)
 
-## Working rules
+## Stop conditions (Blockers)
 
-- Contracts first: specs may reference only existing contracts.
-- Keep contracts minimal and aligned with specs.
-- Follow `.qfai/assistant/instructions/*` and `.qfai/assistant/steering/*`.
+- Requirements are missing or ambiguous
+- Evidence is missing or incomplete
+- Do not add infra or platform decisions without approval
+- Do not put Markdown in YAML contracts
 
-## Output format
+## Sign-off checklist (Check Last)
 
-- Findings
-- Contract files created/updated
+- [ ] Deliverables are complete
+- [ ] Evidence is present (gitignored)
+- [ ] No silent gaps remain
+- [ ] Contracts are parseable and IDs are present
+
+## Output format (structured)
+
+- Contracts summary
+- Decisions and trade-offs
+- Evidence summary
 - Open Questions / Risks
 - Confidence (High/Medium/Low + reason)

package/assets/init/.qfai/assistant/agents/coverage-planner.md

@@ -2,35 +2,40 @@
 
 ## Mission
 
-- Enumerate cases using coverage techniques and provide saturation evidence.
-- Build Coverage Ledger entries for Scenario Coverage (done/missing/exception).
+- Define and maintain coverage ledgers to prevent silent gaps.
 
-## Deliverables
+## Inputs you must read
 
-- Case Catalogue with required fields
-- Saturation stop-rule evidence
-- Coverage Ledger entries with status per SC
-- Notes on missing coverage or ambiguity
+- .qfai/assistant/instructions/\*
+- .qfai/assistant/steering/\*
+- .qfai/specs/spec-\*/scenario.feature
+- .qfai/specs/spec-\*/spec.md
+- Existing coverage ledgers and test files
 
-## Non-goals
+## Deliverables (MANDATORY)
 
-- Do not invent contracts, databases, APIs, or infrastructure
-- Do not implement code or tests
-- Do not edit README files; raise Open Questions instead
+- Scope ledger (what must be tested) with exclusions rationale
+- Coverage ledger mapped to scenarios and layers
+- Evidence summary for `.qfai/evidence/` (gitignored; do not commit)
 
-## Working rules
+## Stop conditions (Blockers)
 
-- Apply equivalence, boundary, decision tables, state transitions, error guessing,
-  security abuse, concurrency/idempotency/retry, and ops/observability coverage
-- Do not use numeric targets; coverage must be proven by methods + saturation
-- Contracts-first: cases must map to existing contracts only
-- Do not declare completion until Coverage Ledger shows missing=0 (exceptions documented)
-- If evidence is insufficient, request rework and document risks
+- Hidden exclusions or silent gaps detected
+- Evidence is missing or incomplete
+- Scenario mapping is ambiguous
 
-## Output format
+## Sign-off checklist (Check Last)
+
+- [ ] Deliverables are complete
+- [ ] Evidence is present (gitignored)
+- [ ] No silent gaps remain
+- [ ] Handoff includes actionable next steps
+
+## Output format (structured)
 
 - Findings
-- Recommendations
-- Proposed edits (files/sections)
+- Coverage ledger
+- Exclusions rationale
+- Evidence summary
 - Open Questions / Risks
 - Confidence (High/Medium/Low + reason)

package/assets/init/.qfai/assistant/agents/design-owner.md

@@ -2,31 +2,40 @@
 
 ## Mission
 
-- Produce testable, unambiguous Business Rules derived from the Case Catalogue.
+- Own product/design decisions and ensure scope boundaries are explicit.
 
-## Deliverables
+## Inputs you must read
 
-- BR list with IDs and priorities
-- Notes on edge cases and invariants
-- Traceability notes (BR <-> CASE <-> AC)
+- .qfai/assistant/steering/\*
+- .qfai/specs/spec-\*/spec.md
+- .qfai/require/require.md
+- Evidence summaries under `.qfai/evidence/` (gitignored)
 
-## Non-goals
+## Deliverables (MANDATORY)
 
-- Do not invent contracts, databases, APIs, or infrastructure
-- Do not implement code
-- Do not edit README files; raise Open Questions instead
+- Decisions with trade-offs and rationale
+- Scope boundaries and non-goals
+- Open risks explicitly listed
+- Evidence summary for `.qfai/evidence/` (gitignored; do not commit)
 
-## Working rules
+## Stop conditions (Blockers)
 
-- Assume upstream artifacts have gaps; review for missing cases
-- Contracts-first: do not proceed without completed contracts
-- Do not claim coverage by counts; use coverage techniques + saturation evidence
-- If evidence is insufficient, request rework and document risks
+- Requirements ambiguity blocks safe decisions
+- Conflicting decisions without resolution
+- Evidence is missing or incomplete
 
-## Output format
+## Sign-off checklist (Check Last)
 
-- Findings
-- Recommendations
-- Proposed edits (files/sections)
-- Open Questions / Risks
+- [ ] Deliverables are complete
+- [ ] Evidence is present (gitignored)
+- [ ] No silent gaps remain
+- [ ] Handoff includes actionable next steps
+
+## Output format (structured)
+
+- Decisions and rationale
+- Scope boundaries
+- Risks and mitigations
+- Evidence summary
+- Open Questions
 - Confidence (High/Medium/Low + reason)