qfai 1.0.6 → 1.1.0

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

@@ -0,0 +1,197 @@
+<!--
+QFAI Prompt Body (SSOT)
+- This file is intended to be referenced by tool-specific custom prompt definitions (e.g., Copilot .prompt.md, Claude Code slash commands).
+- Keep tool-specific wrappers thin: "Read this file and follow it."
+-->
+
+---
+
+id: qfai-configure
+title: QFAI Configure (Tune qfai.config.yaml)
+description: "Analyze the repository and tune qfai.config.yaml (testFileGlobs, exclude globs, optional specSections)."
+argument-hint: "[--auto]"
+allowed-tools: [Read, Glob, Write, TodoWrite, Task]
+roles: [DevOpsCIEngineer, QAEngineer, CodeReviewer, Planner]
+mode: evidence-focused
+
+---
+
+# /qfai-configure - Configure QFAI for this repository
+
+## Purpose
+
+Analyze the repository and update `qfai.config.yaml` so QFAI traceability checks (especially SC->Test) are actionable without manual tuning, and optionally tune required spec sections if requested.
+
+## Success Criteria (Definition of Done)
+
+- `qfai.config.yaml` is updated with a **minimal diff** focused on traceability globs.
+- `validation.traceability.testFileGlobs` reflects the real test layout.
+- `validation.traceability.testFileExcludeGlobs` is added only when needed.
+- If strict spec sections are explicitly requested, `validation.require.specSections` is updated with a minimal, evidence-based list.
+- A validation checklist with evidence (sample matched files) is produced.
+- Steering files (`product.md`, `tech.md`, `structure.md`, `manifest.md`) are filled or refreshed with evidence, or marked `TBD` when evidence is missing.
+
+## Non-Negotiable Principles (QFAI Articles)
+
+These principles are inspired by "constitution / articles" patterns used by other agent frameworks, but tailored to QFAI.
+
+1. **SDD First (Specification is the source of truth)**  
+   If there is a conflict between code and spec, treat the spec as authoritative and either (a) fix code or (b) raise an explicit Open Question to change the spec.
+
+2. **Traceability is mandatory**  
+   Every meaningful change must be traceable: **Require -> Spec -> Scenario -> Tests -> Code -> Verification evidence**.
+
+3. **Evidence over confidence**  
+   Prefer observable proof (logs, commands, file diffs, test results). If you cannot verify, say so and record it.
+
+4. **Minimize scope, but never hide gaps**  
+   Keep changes minimal, but do not "paper over" missing decisions. If something blocks correctness, stop and ask.
+
+5. **Quality gates are the decision mechanism**  
+   Use tests/lint/typecheck/build/pack verification (whatever the repo defines) as the primary guardrail. Fix until PASS.
+
+6. **Make it runnable**  
+   Outputs must be executable in terminal/CI. Provide copy-paste commands.
+
+7. **User time is expensive**  
+   Ask only the questions that are truly blocking. Everything else: make reasonable assumptions and label them clearly.
+
+## Absolute Rule - Output Language
+
+**All outputs MUST be written in the user's working language for this session.**
+
+- If the user writes in Japanese, output Japanese.
+- If the user writes in English, output English.
+- If the user mixes languages, prefer the dominant language unless explicitly instructed otherwise.  
+  This rule overrides all other stylistic preferences.
+
+## Multi-Role Orchestration (Subagents)
+
+This workflow assumes the environment _may_ support subagents (e.g., Claude Code "Task" tool) or may not.
+
+### If subagents are supported
+
+Delegate to multiple roles and then merge the results. Use a "real-world workflow" order:
+
+- Facilitator -> Interviewer -> Requirements Analyst -> Planner -> Architect -> (Contract Designer) -> Test Engineer -> QA Engineer -> Code Reviewer -> DevOps/CI Engineer
+
+**Pseudo-invocation pattern** (adjust to your tool):
+
+```text
+Task(
+  subagent_type="planner",
+  description="Analyze repo and propose testFileGlobs",
+  prompt="Context: ...\nGoal: Tune qfai.config.yaml\nConstraints: minimal diff\nReturn: globs + evidence"
+)
+```
+
+### If subagents are NOT supported
+
+Simulate roles by running the same sequence yourself:
+
+- Write a short "role output" section per role, then consolidate into the final deliverable(s).
+
+## Constraints
+
+- Only update `qfai.config.yaml` and `.qfai/assistant/steering/*` unless explicitly asked.
+- Do **not** modify tests or source code.
+- Avoid overly broad globs (e.g., `**/*`).
+- Exclude generated/output directories (`node_modules`, `.git`, `.qfai`, `dist`, `build`, `coverage`, `.next`, `out`, etc.).
+- Keep `validation.require.specSections` unchanged unless the user explicitly requests strict required headings.
+
+## Step 0 - Load Context (always)
+
+1. Read relevant **project steering** (if present):
+   - `.qfai/assistant/steering/structure.md`
+   - `.qfai/assistant/steering/tech.md`
+   - `.qfai/assistant/steering/product.md`
+   - any additional files under `.qfai/assistant/steering/`
+
+2. Read **project constitution / instructions** (if present):
+   - `.qfai/assistant/instructions/constitution.md`
+   - `.qfai/assistant/instructions/workflow.md` (or equivalent)
+
+3. Inspect repo conventions:
+   - package manager (pnpm/npm/yarn), test runner, lint/typecheck scripts, CI definitions
+   - existing test patterns (unit/integration/e2e)
+
+4. Inspect steering templates and placeholders:
+   - `.qfai/assistant/steering/product.md`
+   - `.qfai/assistant/steering/tech.md`
+   - `.qfai/assistant/steering/structure.md`
+   - `.qfai/assistant/steering/manifest.md`
+
+## Step 0 - Project Analysis (mandatory)
+
+Before editing config, **thoroughly analyze the current project**:
+
+- background and goals
+- directory structure and conventions
+- chosen technologies and versions (runtime, package manager, test runner)
+- test locations (unit/integration/e2e)
+- existing test naming rules (`*.test.*`, `*.spec.*`, `*_test.*`, etc.)
+
+If analysis cannot be performed (missing access), clearly state what could not be verified and proceed with minimal-risk assumptions.
+
+## Step 1 - Identify test frameworks and locations
+
+1. Inspect `package.json` and config files (e.g., `vitest.config.*`, `jest.config.*`, `playwright.config.*`, `pytest.ini`, `go.mod`).
+2. Enumerate directories that contain tests (e.g., `tests/`, `src/`, `e2e/`, `integration/`).
+3. Note naming rules and extensions that indicate test files.
+4. If strict spec sections are requested, sample existing `spec.md` files and list H2 headings used.
+
+## Step 2 - Propose glob patterns
+
+Provide 3-10 **include globs** that cover all known test locations:
+
+- Prefer explicit patterns (e.g., `src/**/*.test.ts`, `tests/**/*.spec.ts`).
+- Include src-colocated tests if they exist.
+
+Provide **exclude globs** only when necessary (beyond the default exclusions).
+
+## Step 3 - Update steering (evidence-first)
+
+Fill steering templates with repo evidence.
+
+- Keep existing content when already accurate.
+- When evidence is missing, write `TBD` and record what is missing.
+- Do not invent facts.
+
+## Step 4 - Update `qfai.config.yaml` (minimal diff)
+
+Edit:
+
+- `validation.traceability.testFileGlobs`
+- `validation.traceability.testFileExcludeGlobs` (only if needed)
+- `validation.require.specSections` (only if explicitly requested)
+
+Keep all other config keys unchanged.
+
+## Step 5 - Evidence sampling
+
+Sample 5-15 actual test files that match the proposed globs.
+
+- If zero matches exist, stop and ask for clarification.
+- If some directories are ambiguous, list them as Open Questions.
+
+## Checkpoints
+
+- [ ] Repository analysis completed (frameworks, test layout, naming rules).
+- [ ] Steering files updated with evidence or `TBD`.
+- [ ] Proposed include/exclude globs with rationale.
+- [ ] `qfai.config.yaml` updated (minimal diff).
+- [ ] Optional: specSections tuned when requested (or kept empty).
+- [ ] Evidence: sample matched files listed.
+
+## Output
+
+Provide:
+
+1. Updated `qfai.config.yaml` (diff or full file, as appropriate).
+2. Updated steering files (diff or summary).
+3. A short summary of changes and rationale.
+4. Validation checklist with sampled files.
+5. If specSections updated, list the chosen headings and evidence source.
+6. Open questions (blocking vs non-blocking).
+
+Suggest next step: `/qfai-require` (or `/qfai-discuss` if requirements are not ready).

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

@@ -219,4 +219,4 @@ Output this format:
 ## Output
 
 - Evidence summary
-- Next action suggestion: /qfai-pr (optional) or proceed to PR creation
+- Next action suggestion: proceed to PR creation (use your platform workflow)

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

@@ -7,9 +7,15 @@ These are intentionally short and practical:
 - `product.md` : what we are building and why
 - `tech.md` : stack, versions, constraints
 - `structure.md` : repo structure, key directories, how to run gates
+- `manifest.md` : product-level decision spine and governance rubric
 
 QFAI prompts are expected to read these before producing deliverables.
 
+Rule:
+
+- Keep steering flat (no subdirectories).
+- Markdown only.
+
 ## AI-managed policy (recommended)
 
 These steering files are intended to be **filled and refreshed by the AI** (via QFAI custom prompts).

package/assets/init/.qfai/assistant/steering/manifest.md

@@ -0,0 +1,43 @@
+# Manifest (Decision Spine)
+
+## Product / Mission
+
+- Summary:
+- Value:
+- Evidence:
+
+## Drive / Lens / Axioms
+
+- Axioms / principles:
+- Decision lens (what we optimize for):
+- Evidence:
+
+## Compatibility vs Change (Rubric)
+
+- Compatibility:
+- Change:
+- Examples:
+- Evidence:
+
+## Ownership / Governance
+
+- Owner:
+- Review / approval:
+- Update cadence:
+- Evidence:
+
+## Evidence
+
+- Rule (e.g., link to repo evidence for every claim):
+- Evidence:
+
+## Non-goals / Not-now (Optional)
+
+-
+- Evidence:
+
+## References (Optional)
+
+- product.md
+- tech.md
+- structure.md

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

@@ -20,6 +20,13 @@ Include the contract ID in the SQL header comments so QFAI can discover/index it
 
 - Keep DB contracts minimal and spec-driven (only what scenarios/tests need).
 - This directory is for the **contract/schema snapshot**, not migrations history.
-- If your project uses an ORM schema (Prisma, etc.), decide one:
-  - (Recommended for v1.0.6) Keep a minimal `.sql` contract snapshot here, and link to the real schema in the spec.
-  - (Future) Add support for other schema formats via config (out of scope for v1.0.6).
+
+If your project uses an ORM schema (Prisma, etc.), decide one:
+
+### Recommended
+
+- Keep a minimal `.sql` contract snapshot here, and link to the real schema in the spec.
+
+### Out of scope
+
+- Add support for other schema formats via config.

package/assets/init/.qfai/samples/guardrails/delta_with_guardrails.md

@@ -0,0 +1,19 @@
+# SPEC-0001: Delta (Decision Guardrails Sample)
+
+## Decision Guardrails
+
+- ID: DG-0001
+  Type: non-goal
+  Guardrail: Do not introduce per-language parsing rules into validators.
+  Rationale: Multi-language output is a core contract.
+  Reconsider: never
+  Related: SPEC-0001
+  Keywords: parsing, validators, multi-language
+
+- ID: DG-0002
+  Type: not-now
+  Guardrail: Do not add automatic template upgrades for existing repositories.
+  Rationale: Update safety needs a dedicated upgrade design.
+  Reconsider: after upgrade design is approved
+  Related: V11-OQ-007
+  Keywords: upgrade, templates

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

@@ -8,4 +8,8 @@ A **spec pack** lives under `specs/spec-XXXX/` and contains:
 
 Create/update spec packs with `/qfai-spec`.
 
+Decision Guardrails can be stored under `delta.md` as `## Decision Guardrails`. See `.qfai/samples/guardrails/delta_with_guardrails.md` for an opt-in example.
+
+Manifest is maintained under `.qfai/assistant/steering/manifest.md` (product-level decision spine). Do not duplicate a manifest under specs.
+
 Note: After `qfai init`, this folder contains only this README. Spec packs (`spec-XXXX/`) are created by running `/qfai-spec`.

package/assets/init/root/.claude/commands/qfai-configure.md

@@ -0,0 +1,14 @@
+---
+description: "QFAI: Configure qfai.config.yaml based on the repository"
+argument-hint: "[optional notes]"
+---
+
+Follow the canonical QFAI prompt exactly:
+@.qfai/assistant/prompts/qfai-configure.md
+
+Follow the DoD/Checkpoints in the prompt.
+Use the repository as the source of truth.
+
+Additional user notes: $ARGUMENTS
+
+Critical: output must match the user's language.

package/assets/init/root/.claude/commands/qfai-discuss.md

@@ -0,0 +1,14 @@
+---
+description: "QFAI: Discuss an idea and clarify requirements"
+argument-hint: "[optional notes]"
+---
+
+Follow the canonical QFAI prompt exactly:
+@.qfai/assistant/prompts/qfai-discuss.md
+
+Follow the DoD/Checkpoints in the prompt.
+Use the repository as the source of truth.
+
+Additional user notes: $ARGUMENTS
+
+Critical: output must match the user's language.

package/assets/init/root/.claude/commands/qfai-implement.md

@@ -0,0 +1,14 @@
+---
+description: "QFAI: Implement code changes with tests"
+argument-hint: "[optional notes]"
+---
+
+Follow the canonical QFAI prompt exactly:
+@.qfai/assistant/prompts/qfai-implement.md
+
+Follow the DoD/Checkpoints in the prompt.
+Use the repository as the source of truth.
+
+Additional user notes: $ARGUMENTS
+
+Critical: output must match the user's language.

package/assets/init/root/.claude/commands/qfai-require.md

@@ -0,0 +1,14 @@
+---
+description: "QFAI: Create requirements artifacts"
+argument-hint: "[optional notes]"
+---
+
+Follow the canonical QFAI prompt exactly:
+@.qfai/assistant/prompts/qfai-require.md
+
+Follow the DoD/Checkpoints in the prompt.
+Use the repository as the source of truth.
+
+Additional user notes: $ARGUMENTS
+
+Critical: output must match the user's language.

package/assets/init/root/.claude/commands/qfai-scenario-test.md

@@ -0,0 +1,14 @@
+---
+description: "QFAI: Implement acceptance tests from scenarios"
+argument-hint: "[optional notes]"
+---
+
+Follow the canonical QFAI prompt exactly:
+@.qfai/assistant/prompts/qfai-scenario-test.md
+
+Follow the DoD/Checkpoints in the prompt.
+Use the repository as the source of truth.
+
+Additional user notes: $ARGUMENTS
+
+Critical: output must match the user's language.

package/assets/init/root/.claude/commands/qfai-spec.md

@@ -0,0 +1,14 @@
+---
+description: "QFAI: Create specs, contracts, and scenarios"
+argument-hint: "[optional notes]"
+---
+
+Follow the canonical QFAI prompt exactly:
+@.qfai/assistant/prompts/qfai-spec.md
+
+Follow the DoD/Checkpoints in the prompt.
+Use the repository as the source of truth.
+
+Additional user notes: $ARGUMENTS
+
+Critical: output must match the user's language.

package/assets/init/root/.claude/commands/qfai-unit-test.md

@@ -0,0 +1,14 @@
+---
+description: "QFAI: Implement unit tests from specs/scenarios"
+argument-hint: "[optional notes]"
+---
+
+Follow the canonical QFAI prompt exactly:
+@.qfai/assistant/prompts/qfai-unit-test.md
+
+Follow the DoD/Checkpoints in the prompt.
+Use the repository as the source of truth.
+
+Additional user notes: $ARGUMENTS
+
+Critical: output must match the user's language.

package/assets/init/root/.claude/commands/qfai-verify.md

@@ -0,0 +1,14 @@
+---
+description: "QFAI: Run quality gates and produce evidence"
+argument-hint: "[optional notes]"
+---
+
+Follow the canonical QFAI prompt exactly:
+@.qfai/assistant/prompts/qfai-verify.md
+
+Follow the DoD/Checkpoints in the prompt.
+Use the repository as the source of truth.
+
+Additional user notes: $ARGUMENTS
+
+Critical: output must match the user's language.

package/assets/init/root/.codex/README.md

@@ -0,0 +1,16 @@
+# QFAI Codex skills
+
+This directory provides thin Codex skill wrappers for QFAI prompts.
+
+## Canonical prompts
+
+The source of truth is always the prompt body under:
+
+- .qfai/assistant/prompts/
+
+If there is any mismatch, the canonical `.qfai` prompt wins.
+
+## Usage
+
+In Codex CLI, select a skill by name (e.g., `qfai-configure`) and provide your request.
+All outputs must match the user's language.

package/assets/init/root/.codex/skills/qfai-configure/SKILL.md

@@ -0,0 +1,18 @@
+---
+name: qfai-configure
+description: QFAI: Configure qfai.config.yaml based on the repository
+---
+
+This skill is a thin wrapper that forwards to the canonical QFAI prompt in this repository:
+
+- .qfai/assistant/prompts/qfai-configure.md
+
+How to invoke (Codex CLI):
+
+- Select the `qfai-configure` skill, or reference it by name and provide your request.
+
+Instructions:
+
+1. Read the prompt above and follow it precisely.
+2. Use the repository as the source of truth (tools, frameworks, directory structure).
+3. Ensure all outputs match the user's language.

package/assets/init/root/.codex/skills/qfai-discuss/SKILL.md

@@ -0,0 +1,18 @@
+---
+name: qfai-discuss
+description: QFAI: Discuss an idea and clarify requirements
+---
+
+This skill is a thin wrapper that forwards to the canonical QFAI prompt in this repository:
+
+- .qfai/assistant/prompts/qfai-discuss.md
+
+How to invoke (Codex CLI):
+
+- Select the `qfai-discuss` skill, or reference it by name and provide your request.
+
+Instructions:
+
+1. Read the prompt above and follow it precisely.
+2. Use the repository as the source of truth (tools, frameworks, directory structure).
+3. Ensure all outputs match the user's language.

package/assets/init/root/.codex/skills/qfai-implement/SKILL.md

@@ -0,0 +1,18 @@
+---
+name: qfai-implement
+description: QFAI: Implement code changes with tests
+---
+
+This skill is a thin wrapper that forwards to the canonical QFAI prompt in this repository:
+
+- .qfai/assistant/prompts/qfai-implement.md
+
+How to invoke (Codex CLI):
+
+- Select the `qfai-implement` skill, or reference it by name and provide your request.
+
+Instructions:
+
+1. Read the prompt above and follow it precisely.
+2. Use the repository as the source of truth (tools, frameworks, directory structure).
+3. Ensure all outputs match the user's language.

package/assets/init/root/.codex/skills/qfai-require/SKILL.md

@@ -0,0 +1,18 @@
+---
+name: qfai-require
+description: QFAI: Create requirements artifacts
+---
+
+This skill is a thin wrapper that forwards to the canonical QFAI prompt in this repository:
+
+- .qfai/assistant/prompts/qfai-require.md
+
+How to invoke (Codex CLI):
+
+- Select the `qfai-require` skill, or reference it by name and provide your request.
+
+Instructions:
+
+1. Read the prompt above and follow it precisely.
+2. Use the repository as the source of truth (tools, frameworks, directory structure).
+3. Ensure all outputs match the user's language.

package/assets/init/root/.codex/skills/qfai-scenario-test/SKILL.md

@@ -0,0 +1,18 @@
+---
+name: qfai-scenario-test
+description: QFAI: Implement acceptance tests from scenarios
+---
+
+This skill is a thin wrapper that forwards to the canonical QFAI prompt in this repository:
+
+- .qfai/assistant/prompts/qfai-scenario-test.md
+
+How to invoke (Codex CLI):
+
+- Select the `qfai-scenario-test` skill, or reference it by name and provide your request.
+
+Instructions:
+
+1. Read the prompt above and follow it precisely.
+2. Use the repository as the source of truth (tools, frameworks, directory structure).
+3. Ensure all outputs match the user's language.

package/assets/init/root/.codex/skills/qfai-spec/SKILL.md

@@ -0,0 +1,18 @@
+---
+name: qfai-spec
+description: QFAI: Create specs, contracts, and scenarios
+---
+
+This skill is a thin wrapper that forwards to the canonical QFAI prompt in this repository:
+
+- .qfai/assistant/prompts/qfai-spec.md
+
+How to invoke (Codex CLI):
+
+- Select the `qfai-spec` skill, or reference it by name and provide your request.
+
+Instructions:
+
+1. Read the prompt above and follow it precisely.
+2. Use the repository as the source of truth (tools, frameworks, directory structure).
+3. Ensure all outputs match the user's language.

package/assets/init/root/.codex/skills/qfai-unit-test/SKILL.md

@@ -0,0 +1,18 @@
+---
+name: qfai-unit-test
+description: QFAI: Implement unit tests from specs/scenarios
+---
+
+This skill is a thin wrapper that forwards to the canonical QFAI prompt in this repository:
+
+- .qfai/assistant/prompts/qfai-unit-test.md
+
+How to invoke (Codex CLI):
+
+- Select the `qfai-unit-test` skill, or reference it by name and provide your request.
+
+Instructions:
+
+1. Read the prompt above and follow it precisely.
+2. Use the repository as the source of truth (tools, frameworks, directory structure).
+3. Ensure all outputs match the user's language.

package/assets/init/root/.codex/skills/qfai-verify/SKILL.md

@@ -0,0 +1,18 @@
+---
+name: qfai-verify
+description: QFAI: Run quality gates and produce evidence
+---
+
+This skill is a thin wrapper that forwards to the canonical QFAI prompt in this repository:
+
+- .qfai/assistant/prompts/qfai-verify.md
+
+How to invoke (Codex CLI):
+
+- Select the `qfai-verify` skill, or reference it by name and provide your request.
+
+Instructions:
+
+1. Read the prompt above and follow it precisely.
+2. Use the repository as the source of truth (tools, frameworks, directory structure).
+3. Ensure all outputs match the user's language.

package/assets/init/root/.github/copilot-instructions.md

@@ -0,0 +1,14 @@
+# QFAI repository instructions (Copilot)
+
+This repository uses QFAI (Quality-First AI) to improve the quality and consistency of AI-assisted development.
+
+## Golden rules
+
+- Always match the user’s language in your outputs.
+- Treat `.qfai/` as the canonical source of truth for the QFAI workflow:
+  - Prompts: `.qfai/assistant/prompts/`
+  - Instructions: `.qfai/assistant/instructions/`
+  - Project steering: `.qfai/assistant/steering/`
+- When asked to perform QFAI workflow tasks, prefer using the QFAI prompt wrappers in `.github/prompts/` (e.g., `/qfai-spec`) which forward to the canonical prompts.
+- Do not invent repository structure, tools, or frameworks. Inspect the repo first and align with what is already used.
+- Keep changes minimal and targeted. Update tests and docs when behavior changes.

package/assets/init/root/.github/prompts/qfai-configure.prompt.md

@@ -0,0 +1,17 @@
+---
+agent: "agent"
+description: "QFAI: Configure qfai.config.yaml based on the repository"
+---
+
+You are operating in a repository that uses QFAI.
+
+1. Open and follow the canonical QFAI prompt:
+
+- .qfai/assistant/prompts/qfai-configure.md
+
+2. Use the repository as the source of truth (tools, frameworks, directory structure).
+3. Ask the user for missing inputs only when necessary.
+4. Do not modify files not required by the canonical prompt.
+5. All outputs must match the user's language.
+
+User notes: ${input:notes:Optional}

package/assets/init/root/.github/prompts/qfai-discuss.prompt.md

@@ -0,0 +1,17 @@
+---
+agent: "agent"
+description: "QFAI: Discuss an idea and clarify requirements"
+---
+
+You are operating in a repository that uses QFAI.
+
+1. Open and follow the canonical QFAI prompt:
+
+- .qfai/assistant/prompts/qfai-discuss.md
+
+2. Use the repository as the source of truth (tools, frameworks, directory structure).
+3. Ask the user for missing inputs only when necessary.
+4. Do not modify files not required by the canonical prompt.
+5. All outputs must match the user's language.
+
+User notes: ${input:notes:Optional}