qfai 1.0.3 → 1.0.5

package/assets/init/.qfai/assistant/prompts/qfai-unit-test.md

@@ -0,0 +1,202 @@
+<!--
+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-unit-test
+title: QFAI Unit Test (TDD executable)
+description: "Implement CI-runnable unit tests derived from spec/scenario; includes review and quality checks."
+argument-hint: "<spec-id> [--auto]"
+allowed-tools: [Read, Glob, Write, TodoWrite, Task, Bash]
+roles: [TestEngineer, BackendEngineer, FrontendEngineer, QAEngineer, CodeReviewer]
+mode: test-first
+
+---
+
+# /qfai-unit-test — Implement Unit Tests (TDD)
+
+## Purpose
+
+Implement **unit tests** that enforce the spec and provide fast feedback.
+
+## Success Criteria (Definition of Done)
+
+- Unit tests exist, are deterministic, and runnable in CI.
+- Tests cover core logic and key edge cases derived from spec/scenario.
+- Tests fail meaningfully (actionable errors).
+
+## 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="Create an execution plan and DoD",
+  prompt="Context: ...\nGoal: ...\nConstraints: ...\nReturn: phases + risks + DoD"
+)
+```
+
+### 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).
+
+## Behavior Rules (high leverage)
+
+- **Language**: Output MUST follow the user’s working language for this session.
+- **Question budget**: Ask at most **5** clarifying questions total. Prioritize blockers. If `--auto`, proceed with explicit assumptions.
+- **No hallucination**: Do not invent file paths, commands, or policies. Confirm via repo inspection.
+- **Evidence**: Do not claim completion without commands/results (format/lint/type/test/pack as applicable).
+- **Subagent contract**: When delegating, require the subagent response structure:
+  1. Findings 2) Recommendations 3) Proposed edits 4) Open Questions/Risks 5) Confidence
+
+## 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. Read existing artifacts for the current work item (if present):
+   - `.qfai/require/`
+   - `.qfai/specs/spec-*/`
+   - `.qfai/contracts/`
+
+4. Inspect repo conventions:
+   - package manager (pnpm/npm/yarn), test runner, lint/typecheck scripts, CI definitions
+   - existing test patterns (unit/integration/e2e)
+
+## Step 0 — Project Analysis (mandatory)
+
+Before producing any deliverable, **thoroughly analyze the current project** so your outputs fit the repo’s:
+
+- background and goals
+- directory structure and conventions
+- chosen technologies and versions (runtime, package manager, test runner)
+- architecture boundaries (packages, CLI, core modules)
+- existing patterns for tests, docs, and CI
+
+### Minimum analysis checklist
+
+- [ ] Read key repo docs: README / CHANGELOG / RELEASE (if present)
+- [ ] Inspect `.qfai/` layout and existing SDD/ATDD/TDD artifacts (if present)
+- [ ] Inspect `packages/qfai` structure (CLI entrypoints, core modules, validators, assets/init)
+- [ ] Identify standard gate commands (format/lint/type/test/verify-pack) and where they are defined
+- [ ] Search for existing examples/patterns of similar changes in tests (if available)
+- [ ] Note constraints: Node versions, CI matrix, packaging rules, verify-pack expectations
+
+If analysis cannot be performed (missing access), clearly state what could not be verified and proceed with minimal-risk assumptions.
+
+## Step 0.5 — Steering Bootstrap / Refresh (mandatory when incomplete)
+
+QFAI expects `assistant/steering/` to contain **project‑specific facts** so all subsequent design/test/implementation fits this repository.
+
+### What to do
+
+1. Open these files:
+
+- `.qfai/assistant/steering/product.md`
+- `.qfai/assistant/steering/tech.md`
+- `.qfai/assistant/steering/structure.md`
+
+2. If they are missing, mostly empty, or still have placeholders (e.g., `- ` only), **populate them by analyzing the current repository**:
+
+- derive “what/why/users/success/non-goals” from README/docs/issues (product.md)
+- derive runtime/tooling versions + constraints from package.json, CI config, lockfiles (tech.md)
+- derive repo layout + key directories + gate commands from the file tree and scripts (structure.md)
+
+3. Do **not** invent facts. If something cannot be verified, write it as:
+
+- `TBD` + what evidence is missing, or
+- an Open Question (if it blocks correctness)
+
+### Steering refresh checklist
+
+- [ ] product.md: what we build / users / success / non-goals / release posture
+- [ ] tech.md: Node / package manager / TS / test / lint / CI constraints
+- [ ] structure.md: repo layout, key packages, entrypoints, standard gate commands, how to run locally
+
+## Step 1 — Read relevant artifacts
+
+- `.qfai/specs/spec-XXXX/spec.md`
+- `.qfai/specs/spec-XXXX/scenario.feature`
+- referenced contracts (if used by logic)
+
+## Step 2 — Identify units and boundaries (Test Engineer + Architect mindset)
+
+- What are the smallest meaningful units?
+- What should be mocked vs real?
+- Where are seams (interfaces) needed to test cleanly?
+
+## Step 3 — Write tests first (RED)
+
+- Add tests that should fail on current code.
+- Keep them minimal and focused.
+
+## Step 4 — Review test quality
+
+- QA Engineer: edge cases, unwanted behavior, observability
+- Code Reviewer: brittleness, over-mocking, unclear naming
+
+## Step 5 — Provide run commands + evidence
+
+- Document the exact command(s) to run unit tests.
+- Provide summary of pass/fail.
+
+## Output
+
+- Unit test files
+- Run command snippet
+- Evidence summary

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

@@ -0,0 +1,231 @@
+<!--
+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-verify
+title: QFAI Verify (Quality Gates + Evidence)
+description: "Run and document quality gates (repo + qfai validate/report), fix until PASS."
+argument-hint: "[--auto]"
+allowed-tools: [Read, Glob, Bash, Write, TodoWrite, Task]
+roles: [DevOpsCIEngineer, QAEngineer, CodeReviewer, Planner]
+mode: evidence-focused
+
+---
+
+# /qfai-verify — Quality Gates and Evidence
+
+## Purpose
+
+Run quality gates and produce **evidence** that the change is correct and safe.
+
+## Success Criteria (Definition of Done)
+
+- Repo quality gates PASS (format/lint/type/test/build/etc).
+- QFAI checks PASS (at minimum: `qfai validate`, and optionally `qfai report`).
+- A concise evidence summary exists (copy‑paste for PR).
+
+## 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="Create an execution plan and DoD",
+  prompt="Context: ...\nGoal: ...\nConstraints: ...\nReturn: phases + risks + DoD"
+)
+```
+
+### 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).
+
+## Behavior Rules (high leverage)
+
+- **Language**: Output MUST follow the user’s working language for this session.
+- **Question budget**: Ask at most **5** clarifying questions total. Prioritize blockers. If `--auto`, proceed with explicit assumptions.
+- **No hallucination**: Do not invent file paths, commands, or policies. Confirm via repo inspection.
+- **Evidence**: Do not claim completion without commands/results (format/lint/type/test/pack as applicable).
+- **Subagent contract**: When delegating, require the subagent response structure:
+  1. Findings 2) Recommendations 3) Proposed edits 4) Open Questions/Risks 5) Confidence
+
+## 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. Read existing artifacts for the current work item (if present):
+   - `.qfai/require/`
+   - `.qfai/specs/spec-*/`
+   - `.qfai/contracts/`
+
+4. Inspect repo conventions:
+   - package manager (pnpm/npm/yarn), test runner, lint/typecheck scripts, CI definitions
+   - existing test patterns (unit/integration/e2e)
+
+## Step 0 — Project Analysis (mandatory)
+
+Before producing any deliverable, **thoroughly analyze the current project** so your outputs fit the repo’s:
+
+- background and goals
+- directory structure and conventions
+- chosen technologies and versions (runtime, package manager, test runner)
+- architecture boundaries (packages, CLI, core modules)
+- existing patterns for tests, docs, and CI
+
+### Minimum analysis checklist
+
+- [ ] Read key repo docs: README / CHANGELOG / RELEASE (if present)
+- [ ] Inspect `.qfai/` layout and existing SDD/ATDD/TDD artifacts (if present)
+- [ ] Inspect `packages/qfai` structure (CLI entrypoints, core modules, validators, assets/init)
+- [ ] Identify standard gate commands (format/lint/type/test/verify-pack) and where they are defined
+- [ ] Search for existing examples/patterns of similar changes in tests (if available)
+- [ ] Note constraints: Node versions, CI matrix, packaging rules, verify-pack expectations
+
+If analysis cannot be performed (missing access), clearly state what could not be verified and proceed with minimal-risk assumptions.
+
+## Step 0.5 — Steering Bootstrap / Refresh (mandatory when incomplete)
+
+QFAI expects `assistant/steering/` to contain **project‑specific facts** so all subsequent design/test/implementation fits this repository.
+
+### What to do
+
+1. Open these files:
+
+- `.qfai/assistant/steering/product.md`
+- `.qfai/assistant/steering/tech.md`
+- `.qfai/assistant/steering/structure.md`
+
+2. If they are missing, mostly empty, or still have placeholders (e.g., `- ` only), **populate them by analyzing the current repository**:
+
+- derive “what/why/users/success/non-goals” from README/docs/issues (product.md)
+- derive runtime/tooling versions + constraints from package.json, CI config, lockfiles (tech.md)
+- derive repo layout + key directories + gate commands from the file tree and scripts (structure.md)
+
+3. Do **not** invent facts. If something cannot be verified, write it as:
+
+- `TBD` + what evidence is missing, or
+- an Open Question (if it blocks correctness)
+
+### Steering refresh checklist
+
+- [ ] product.md: what we build / users / success / non-goals / release posture
+- [ ] tech.md: Node / package manager / TS / test / lint / CI constraints
+- [ ] structure.md: repo layout, key packages, entrypoints, standard gate commands, how to run locally
+
+## Step 1 — Discover project gate commands (DevOps/CI Engineer)
+
+Prefer existing scripts:
+
+- package.json scripts
+- Makefile / task runner
+- CI config
+
+If unknown, propose defaults and mark assumptions.
+
+## Step 2 — Run QFAI gates
+
+Run (adjust as needed):
+
+- `qfai validate --fail-on error`
+- `qfai report` (if used in this repo)
+
+Capture:
+
+- exit codes
+- key errors/warnings
+- file paths affected
+
+## Step 3 — Run repo gates
+
+Run the repo’s standard pipeline in a stable order:
+
+1. format
+2. lint
+3. typecheck
+4. unit tests
+5. scenario/e2e tests
+6. build/package (if relevant)
+
+## Step 4 — Fix loop (Code Reviewer + QA)
+
+If anything fails:
+
+- Identify whether it’s spec mismatch, test issue, or implementation defect.
+- Fix the root cause (do not silence tests without reason).
+
+## Step 5 — Produce Evidence Summary (Planner)
+
+Output this format:
+
+### Verification Evidence
+
+- QFAI:
+  - command:
+  - result:
+- Repo gates:
+  - command:
+  - result:
+- Notes:
+  - assumptions:
+  - risks:
+
+## Output
+
+- Evidence summary
+- Next action suggestion: /qfai-pr (optional) or proceed to PR creation

package/assets/init/.qfai/assistant/prompts.local/README.md

@@ -0,0 +1,6 @@
+# prompts.local/
+
+Optional per-project overrides.
+
+If a file with the same name exists here (e.g., `qfai-spec.md`), a tool wrapper may prefer it to customize behavior for this repo.
+Keep overrides minimal; prefer updating steering/instructions instead.

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

@@ -0,0 +1,33 @@
+# steering/
+
+Project context for the AI. Keep these files up to date.
+
+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
+
+QFAI prompts are expected to read these before producing deliverables.
+
+## AI-managed policy (recommended)
+
+These steering files are intended to be **filled and refreshed by the AI** (via QFAI custom prompts).
+Humans may edit them, but the default workflow is:
+
+- run a QFAI command (e.g., /qfai-require, /qfai-spec, /qfai-implement)
+- the agent analyzes the repository and updates steering if placeholders exist
+
+Guideline:
+
+- do not invent facts; if unknown, write `TBD` with missing evidence
+
+## Evidence-first writing (recommended)
+
+Steering MUST be grounded in repo evidence. When possible, include:
+
+- file paths (e.g., `package.json`, `.github/workflows/ci.yml`)
+- commands (e.g., `pnpm -C packages/qfai test`)
+- directory anchors (e.g., `packages/qfai/src/cli`)
+
+If a fact cannot be verified, mark it as `TBD` and record what evidence is missing.

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

@@ -0,0 +1,32 @@
+# Product Steering
+
+## What are we building?
+
+- Summary:
+- Evidence: (e.g., README, docs, issue links)
+
+## Who is the user?
+
+- Personas / roles:
+- Evidence:
+
+## What is “success”?
+
+- Success metrics / acceptance definition:
+- Evidence:
+
+## Non-goals
+
+-
+- Evidence:
+
+## Release posture
+
+- Compatibility policy:
+- Breaking change policy:
+- Evidence:
+
+## Open questions
+
+- Blocking:
+- Non-blocking:

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

@@ -0,0 +1,34 @@
+# Structure Steering
+
+## Repo layout (high level)
+
+- Top-level directories:
+- Evidence:
+
+## Key packages / entrypoints
+
+- Package(s) of interest:
+- CLI entry:
+- Core modules:
+- Evidence:
+
+## Architecture constraints
+
+- Boundaries (what must not depend on what):
+- Conventions (naming, file layout):
+- Evidence:
+
+## Quality gates (SSOT)
+
+- format:
+- lint:
+- typecheck:
+- test:
+- verify-pack / pack:
+- Evidence:
+
+## How to run locally
+
+Provide copy-paste commands and expected outputs.
+
+- Evidence:

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

@@ -0,0 +1,37 @@
+# Tech Steering
+
+## Runtime / platform
+
+- Node:
+- Evidence:
+- OS assumptions:
+- Evidence:
+- CI environment:
+- Evidence:
+
+## Package manager
+
+- pnpm / npm / yarn:
+- Evidence:
+
+## Language / framework
+
+- TypeScript:
+- Build tool:
+- Test runner:
+- Lint / format:
+- Evidence:
+
+## Constraints
+
+-
+- Evidence:
+
+## Standard commands (copy-paste)
+
+- Install:
+- Test:
+- Lint:
+- Typecheck:
+- Pack/verify:
+- Evidence:

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

@@ -1,91 +1,11 @@
-# Contracts (UI / API / DB)
+# contracts/
 
-契約は「システム外部との約束」を明文化する場所です。Spec（spec.md）の `QFAI-CONTRACT-REF` による参照が必須で、これが Spec→Contract 対応の SSOT になります。Scenario は `# QFAI-CONTRACT-REF` で契約参照を宣言します（none 可）。
+Contracts define stable interfaces and are referenced by specs/scenarios/tests.
 
-## 置くべきファイル
+Subfolders:
 
-- UI: `ui/ui-0001-<slug>.yaml` または `.yml`
-- THEMA: `ui/thema-001-<slug>.yml`（3桁）
-- API: `api/api-0001-<slug>.yaml` / `.yml` / `.json`（OpenAPI）
-- DB: `db/db-0001-<slug>.sql`（ID は `DB-xxxx`）
-- assets: `ui/assets/<contract-id>/assets.yaml`（参照整合のみ検証）
+- `ui/` : UI contracts (YAML)
+- `api/`: API contracts (YAML)
+- `db/` : DB contracts (YAML)
 
-## 契約ID宣言（必須）
-
-- 1ファイル = 1ID
-- 契約IDの正は契約ファイル側（`QFAI-CONTRACT-ID` が SSOT）
-- ファイル内に `QFAI-CONTRACT-ID: <ID>` をコメント行で宣言する
-- 例: `# QFAI-CONTRACT-ID: API-0001` / `// QFAI-CONTRACT-ID: UI-0001` / `-- QFAI-CONTRACT-ID: DB-0001`
-
-## 最小例（UI）
-
-```yaml
-# QFAI-CONTRACT-ID: UI-0001
-id: UI-0001
-name: 受注登録画面
-refs:
-  - BR-0001
-themaRef: THEMA-001
-assets:
-  pack: assets/ui-0001-sample
-  use:
-    - UI-0001.desktop.light.default
-```
-
-## 最小例（THEMA）
-
-```yaml
-# QFAI-CONTRACT-ID: THEMA-001
-id: THEMA-001
-name: facebook-like
-tokens:
-  color:
-    background: "#FFFFFF"
-    textPrimary: "#111111"
-    accent: "#1877F2"
-```
-
-## 最小例（API）
-
-```yaml
-# QFAI-CONTRACT-ID: API-0001
-openapi: 3.0.0
-info:
-  title: Sample API
-  version: 0.1.0
-paths:
-  /health:
-    get:
-      operationId: API-0001
-      responses:
-        "200":
-          description: OK
-```
-
-## 最小例（DB）
-
-```sql
--- QFAI-CONTRACT-ID: DB-0001
-CREATE TABLE sample_table (
-  id INTEGER PRIMARY KEY
-);
-```
-
-## CI でチェックされること（抜粋）
-
-- 契約宣言: `QFAI-CONTRACT-ID` の未記載/複数宣言/重複IDは error
-- 契約ID: 配置ディレクトリ（ui/api/db）と prefix（UI/API/DB）の不整合は error
-- UI/API: パース失敗は error
-- API: OpenAPI 定義があること（`openapi`）
-- DB: 危険 SQL（DROP/TRUNCATE 等）の警告
-- 共通: ID 形式（`PREFIX-0001`）、ID の重複検知
-
-## 依存関係
-
-- Spec → Contracts（spec.md に `QFAI-CONTRACT-REF` を必ず1行以上宣言、0件は `none`。この行が SSOT）
-- Scenario → Contracts（scenario.feature に `# QFAI-CONTRACT-REF` を必ず1行以上宣言、0件は `none`）
-
-## 良い例 / 悪い例
-
-- 良い例: Spec で契約を参照し、必要に応じて Scenario でも参照している
-- 悪い例: Spec が契約を参照しておらず orphan contract が発生する（allowOrphanContracts=false で error）
+Create contracts only when needed by the spec (keep minimal).

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

@@ -0,0 +1,8 @@
+# contracts/api/
+
+Place API contracts here (YAML).
+
+Guidelines:
+
+- Keep contracts minimal: define only what scenarios/tests need to validate.
+- Include examples where helpful.