qfai 1.1.5 → 1.1.7

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

@@ -1,26 +1,79 @@
-# .qfai (QFAI Workspace)
+# .qfai
 
-Generated by: `qfai init`
-This kit is generated by the installed QFAI version. See the QFAI changelog for release details.
+## 1. 目的
 
-This directory is the workspace for **QFAI (Quality‑First AI)**.  
-QFAI standardizes engineering work around a fixed workflow:
+`.qfai` は QFAI が要件・仕様・契約・レポートを管理するためのワークスペースです。AI と人間が同じ前提で作業できるよう、成果物を決まった構造に揃えます。
 
-Note: You may edit files under `.qfai/` to fit your project. QFAI prompts treat this workspace as project-local SSOT for guidance and artifacts.
+## 2. 背景
 
-**SDD → ATDD → TDD → Implementation → Verification**
+成果物の置き場や粒度が曖昧だと、AI がアドリブで不要な成果物を生成しやすく、検証（validate/verify）で弾けない曖昧さが残ります。`.qfai` はそのブレを抑えるための「成果物の骨格」です。
 
-## Directory Overview
+## 3. ここに配置するもの
 
-- `assistant/` : AI assistance assets (SSOT prompt bodies + subagent definitions + steering/instructions)
-- `require/` : Requirements artifact(s) (SSOT for business/product requirements)
-- `specs/` : Spec packs (spec.md / delta.md / scenario.feature)
-- `contracts/` : Interface contracts (ui/api/db)
-- `report/` : Output location for generated reports (e.g., `qfai report`)
+- AI の指示資産（assistant）
+- 要求定義（require）
+- 契約（contracts）
+- 仕様（specs）
+- レポート（report）
 
-## Key rule
+## 4. ここに配置してはならないもの
 
-The canonical “instructions to the AI” live under `assistant/`.  
-Tool‑specific wrappers (Copilot / Claude Code / etc.) should be thin and simply reference the files in:
+- アプリのソースコード
+- 生成されたテストコード
+- 運用上の雑多なメモ（成果物の責務に属さないもの）
+- README に定義されていない構造や成果物
 
-- `assistant/prompts/`
+## 5. ディレクトリ構造
+
+```text
+.
+├─ README.md
+├─ assistant
+│  ├─ README.md
+│  ├─ agents
+│  │  ├─ README.md
+│  │  └─ <role files>
+│  ├─ instructions
+│  │  ├─ README.md
+│  │  └─ <instruction files>
+│  ├─ prompts
+│  │  ├─ README.md
+│  │  └─ <prompt files>
+│  ├─ prompts.local
+│  │  └─ README.md
+│  └─ steering
+│     ├─ README.md
+│     └─ <steering files>
+├─ require
+│  ├─ README.md
+│  └─ require.md
+├─ contracts
+│  ├─ README.md
+│  ├─ api
+│  │  ├─ README.md
+│  │  └─ <api contracts>
+│  ├─ db
+│  │  ├─ README.md
+│  │  └─ <db contracts>
+│  └─ ui
+│     ├─ README.md
+│     └─ <ui contracts>
+├─ specs
+│  ├─ README.md
+│  └─ <spec packs>
+└─ report
+   ├─ README.md
+   └─ <generated reports>
+```
+
+## 6. 運用ルール
+
+- README は参照用ガイドです。通常は編集しません。
+- README の不足や矛盾を見つけた場合は README を編集せず、Open Question として起票します。
+- 作業は各ディレクトリの README のチェックリストに従います。
+
+## 7. チェックリスト
+
+- [ ] 作業対象ディレクトリの README を読んだ
+- [ ] 成果物を所定のディレクトリに配置した
+- [ ] validate/verify のチェックコマンドを実行し、全て通過した

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

@@ -1,9 +1,87 @@
-# assistant/
+# assistant
 
-This folder contains AI assistance assets.
+## 1. 目的
 
-- `prompts/` : SSOT prompt bodies (referenced by tool-specific custom prompt definitions)
-- `prompts.local/` : optional per-project overrides (not required)
-- `agents/` : subagent definitions (general job roles)
-- `instructions/` : constitutions/workflow policies for the AI
-- `steering/` : project context (product/tech/structure/manifest) used before work begins
+`assistant` は AI が成果物を作成するときに参照する指示資産の置き場です。プロジェクト固有の前提と作業手順をここに揃えます。
+
+## 2. 背景
+
+同じ指示でも、散在すると参照漏れや解釈ブレが発生します。`assistant` を SSOT として整理し、プロンプトやサブエージェントの行動を安定化させます。
+
+## 3. ここに配置するもの
+
+- prompts: コマンド別の作業指示（SSOT）
+- prompts.local: 必要に応じた上書き（最小限）
+- agents: サブエージェントの役割定義
+- instructions: 行動規範・品質基準・ワークフロー
+- steering: プロジェクト文脈（前提・制約・方針）
+
+## 4. ここに配置してはならないもの
+
+- requirements/specs/contracts の成果物
+- 実装コード
+- 手順のない雑多なメモ
+
+## 5. ディレクトリ構造
+
+```text
+.
+├─ README.md
+├─ prompts
+│  └─ README.md
+├─ prompts.local
+│  └─ README.md
+├─ agents
+│  └─ README.md
+├─ instructions
+│  └─ README.md
+└─ steering
+   └─ README.md
+```
+
+## 6. テンプレート
+
+指示ファイルは原則「ルール」「手順」「チェックリスト」を含めます。
+
+```md
+# Title
+
+## Rules
+
+- <must>
+
+## Steps
+
+1. <do>
+
+## Checklist
+
+- [ ] <check>
+```
+
+## 7. 完成例
+
+```md
+# Example
+
+## Rules
+
+- 出力ファイルのパスを必ず明記する
+- 作業完了条件としてチェックコマンドを実行する
+
+## Steps
+
+1. 入力を読む
+2. 成果物を生成する
+3. チェックコマンドを実行する
+
+## Checklist
+
+- [ ] 出力パスが明記されている
+- [ ] チェックコマンドを全て通過した
+```
+
+## 8. チェックリスト
+
+- [ ] 成果物を `assistant` に置いていない（責務分離）
+- [ ] 指示は検証可能な形（チェックリスト）になっている

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

@@ -1,36 +1,114 @@
-# agents/
+# agents
 
-Subagent definitions (general job roles).
+## 1. 目的
 
-These files are SSOT "role cards".
-A QFAI custom prompt may delegate work to multiple roles and then consolidate results.
+`agents` はサブエージェントの役割定義を格納します。作業を分担し、各成果物の責務と判断基準を明確化します。
 
-Role set (recommended initial):
+## 2. 背景
 
-- Facilitator
-- Interviewer
-- Requirements Analyst
-- Planner
-- Architect
-- Contract Designer
-- QA Engineer
-- Test Engineer
-- Front-end Engineer
-- Back-end Engineer
-- DevOps/CI Engineer
-- Code Reviewer
+単一プロンプトで全てを決めると、論点の取りこぼしや品質ムラが発生します。役割定義により、検討・作成・レビューを分離して安定化させます。
 
-## Metadata (for tool integration)
+## 3. ここに配置するもの
 
-Each role card includes YAML frontmatter:
+- 役割定義ファイル（Markdown）
+- 役割ごとの Mission / Non-goals / Working rules / Output format
 
-- `trigger_terms`: keywords that suggest when the role is relevant
-- `use_when`: brief activation condition
-- `allowed_tools`: expected tool surface
-- `output_format`: default response format
+## 4. ここに配置してはならないもの
 
-## Response contract
+- 要件や仕様そのもの
+- 実装コード
+- プロジェクト固有の前提（それは steering）
 
-All subagents must use the "Findings / Recommendations / Proposed edits / Open Questions / Confidence" structure.
+## 5. ディレクトリ構造
 
-Note: These are **role cards** (definitions). Actual delegation/execution depends on your AI product (Copilot, Claude Code, etc.). If subagents are not supported, the orchestrator prompt must emulate role-by-role reasoning in a single run.
+```text
+.
+├─ README.md
+├─ facilitator.md
+├─ interviewer.md
+├─ requirements-analyst.md
+├─ planner.md
+├─ architect.md
+├─ contract-designer.md
+├─ qa-engineer.md
+├─ test-engineer.md
+├─ frontend-engineer.md
+├─ backend-engineer.md
+├─ devops-ci-engineer.md
+└─ code-reviewer.md
+```
+
+## 6. テンプレート
+
+```md
+---
+trigger_terms:
+  - <keyword>
+use_when: <condition>
+output_format: markdown
+---
+
+# Role name
+
+## Mission
+
+- <responsibilities>
+
+## Non-goals
+
+- <not doing>
+
+## Working rules
+
+- <must>
+- <must not>
+
+## Output format
+
+- Findings:
+- Recommendations:
+- Proposed edits:
+- Open Questions:
+- Confidence:
+```
+
+## 7. 完成例
+
+```md
+---
+trigger_terms:
+  - contract
+use_when: contracts を作るとき
+output_format: markdown
+---
+
+# Contract Designer
+
+## Mission
+
+- API/DB/UI の契約を先に定義し、spec が架空参照しないようにする
+- YAML/SQL の構文を正しく保つ
+
+## Non-goals
+
+- 実装の技術選定を決めない
+
+## Working rules
+
+- カテゴリ（api/db/ui）を増やさない
+- テンプレと命名規約を守る
+- 不明点は Open Question にする
+
+## Output format
+
+- Findings:
+- Recommendations:
+- Proposed edits:
+- Open Questions:
+- Confidence:
+```
+
+## 8. チェックリスト
+
+- [ ] Mission と Non-goals が分離している
+- [ ] Working rules が明確で検証可能

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

@@ -14,6 +14,12 @@ output_format: markdown
 
 **All outputs MUST be written in the user’s working language for this session.**
 
+## README Rule
+
+- `.qfai/**/README.md` is a reference guide. Do NOT edit README files.
+- If you find a gap or inconsistency in a README, do NOT modify it. Instead, record an **Open Question**.
+- Before starting work, read the README of the target directory and follow its structure, templates, and checklist.
+
 ## Subagent Response Contract (required)
 
 When invoked by a QFAI custom prompt, respond using **exactly** this structure:

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

@@ -14,6 +14,12 @@ output_format: markdown
 
 **All outputs MUST be written in the user’s working language for this session.**
 
+## README Rule
+
+- `.qfai/**/README.md` is a reference guide. Do NOT edit README files.
+- If you find a gap or inconsistency in a README, do NOT modify it. Instead, record an **Open Question**.
+- Before starting work, read the README of the target directory and follow its structure, templates, and checklist.
+
 ## Subagent Response Contract (required)
 
 When invoked by a QFAI custom prompt, respond using **exactly** this structure:

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

@@ -14,6 +14,12 @@ output_format: markdown
 
 **All outputs MUST be written in the user’s working language for this session.**
 
+## README Rule
+
+- `.qfai/**/README.md` is a reference guide. Do NOT edit README files.
+- If you find a gap or inconsistency in a README, do NOT modify it. Instead, record an **Open Question**.
+- Before starting work, read the README of the target directory and follow its structure, templates, and checklist.
+
 ## Subagent Response Contract (required)
 
 When invoked by a QFAI custom prompt, respond using **exactly** this structure:

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

@@ -14,6 +14,12 @@ output_format: markdown
 
 **All outputs MUST be written in the user’s working language for this session.**
 
+## README Rule
+
+- `.qfai/**/README.md` is a reference guide. Do NOT edit README files.
+- If you find a gap or inconsistency in a README, do NOT modify it. Instead, record an **Open Question**.
+- Before starting work, read the README of the target directory and follow its structure, templates, and checklist.
+
 ## Subagent Response Contract (required)
 
 When invoked by a QFAI custom prompt, respond using **exactly** this structure:
@@ -38,6 +44,26 @@ You are the **Contract Designer** in a QFAI-driven workflow.
 
 - Define minimal contracts (UI/API/DB) required by the spec.
 - Ensure references and naming are consistent.
+- **Ensure all contract files referenced by specs actually exist** (reference integrity).
+- If the spec slice has UI, API, or DB, the corresponding contract category MUST have at least one file (not just README).
+
+## Required Deliverables (by category)
+
+For each spec slice, evaluate and create contracts as needed:
+
+- **UI contracts** (`contracts/ui/`): Required if the slice includes screens, forms, or components.
+- **API contracts** (`contracts/api/`): Required if the slice includes API endpoints.
+- **DB contracts** (`contracts/db/`): Required if the slice includes database schema/tables.
+
+If a category is applicable but no contract exists, CREATE the contract before the spec is finalized.
+
+## Prohibited Actions
+
+- Do NOT create new contract categories (e.g., `contracts/infra/`). Allowed: `api/`, `db/`, `ui/` only.
+- Do NOT write Markdown syntax into YAML files (`#` comments are OK; `#` headings and ``` fences are NOT).
+- Do NOT invent technologies (DB types, external APIs, auth methods) not confirmed in steering/require.
+- Do NOT create `.qfai/samples/**`.
+- If technology is unclear, use `QFAI-CONTRACT-REF: none` and raise an Open Question.
 
 ## Operating Principles
 
@@ -67,6 +93,19 @@ You are the **Contract Designer** in a QFAI-driven workflow.
 - [ ] Naming/IDs are consistent
 - [ ] Examples align with scenarios
 - [ ] No speculative fields
+- [ ] All contract files have `QFAI-CONTRACT-ID:` header (YAML: `# QFAI-CONTRACT-ID: ...`, SQL: `-- QFAI-CONTRACT-ID: ...`)
+- [ ] YAML files parse without syntax errors
+- [ ] No Markdown in YAML (no `#` headings, no ``` fences)
+- [ ] Only allowed categories used: `api/`, `db/`, `ui/`
+- [ ] UI contracts exist if the spec has UI elements
+- [ ] API contracts exist if the spec has API endpoints
+- [ ] DB contracts exist if the spec has DB schema
+
+## Completion Criteria
+
+- All contract files referenced by `spec.md` exist (missing = 0).
+- All contract files are syntactically valid.
+- Contract Designer signs off only after all checks pass.
 
 ## Escalation / Open Questions
 

package/assets/init/.qfai/assistant/agents/devops-ci-engineer.md

@@ -14,6 +14,12 @@ output_format: markdown
 
 **All outputs MUST be written in the user’s working language for this session.**
 
+## README Rule
+
+- `.qfai/**/README.md` is a reference guide. Do NOT edit README files.
+- If you find a gap or inconsistency in a README, do NOT modify it. Instead, record an **Open Question**.
+- Before starting work, read the README of the target directory and follow its structure, templates, and checklist.
+
 ## Subagent Response Contract (required)
 
 When invoked by a QFAI custom prompt, respond using **exactly** this structure:

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

@@ -14,6 +14,12 @@ output_format: markdown
 
 **All outputs MUST be written in the user’s working language for this session.**
 
+## README Rule
+
+- `.qfai/**/README.md` is a reference guide. Do NOT edit README files.
+- If you find a gap or inconsistency in a README, do NOT modify it. Instead, record an **Open Question**.
+- Before starting work, read the README of the target directory and follow its structure, templates, and checklist.
+
 ## Subagent Response Contract (required)
 
 When invoked by a QFAI custom prompt, respond using **exactly** this structure:

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

@@ -14,6 +14,12 @@ output_format: markdown
 
 **All outputs MUST be written in the user’s working language for this session.**
 
+## README Rule
+
+- `.qfai/**/README.md` is a reference guide. Do NOT edit README files.
+- If you find a gap or inconsistency in a README, do NOT modify it. Instead, record an **Open Question**.
+- Before starting work, read the README of the target directory and follow its structure, templates, and checklist.
+
 ## Subagent Response Contract (required)
 
 When invoked by a QFAI custom prompt, respond using **exactly** this structure:

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

@@ -15,6 +15,12 @@ output_format: markdown
 
 **All outputs MUST be written in the user’s working language for this session.**
 
+## README Rule
+
+- `.qfai/**/README.md` is a reference guide. Do NOT edit README files.
+- If you find a gap or inconsistency in a README, do NOT modify it. Instead, record an **Open Question**.
+- Before starting work, read the README of the target directory and follow its structure, templates, and checklist.
+
 ## Subagent Response Contract (required)
 
 When invoked by a QFAI custom prompt, respond using **exactly** this structure:

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

@@ -14,6 +14,12 @@ output_format: markdown
 
 **All outputs MUST be written in the user’s working language for this session.**
 
+## README Rule
+
+- `.qfai/**/README.md` is a reference guide. Do NOT edit README files.
+- If you find a gap or inconsistency in a README, do NOT modify it. Instead, record an **Open Question**.
+- Before starting work, read the README of the target directory and follow its structure, templates, and checklist.
+
 ## Subagent Response Contract (required)
 
 When invoked by a QFAI custom prompt, respond using **exactly** this structure:

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

@@ -14,6 +14,12 @@ output_format: markdown
 
 **All outputs MUST be written in the user’s working language for this session.**
 
+## README Rule
+
+- `.qfai/**/README.md` is a reference guide. Do NOT edit README files.
+- If you find a gap or inconsistency in a README, do NOT modify it. Instead, record an **Open Question**.
+- Before starting work, read the README of the target directory and follow its structure, templates, and checklist.
+
 ## Subagent Response Contract (required)
 
 When invoked by a QFAI custom prompt, respond using **exactly** this structure:

package/assets/init/.qfai/assistant/agents/requirements-analyst.md

@@ -14,6 +14,12 @@ output_format: markdown
 
 **All outputs MUST be written in the user’s working language for this session.**
 
+## README Rule
+
+- `.qfai/**/README.md` is a reference guide. Do NOT edit README files.
+- If you find a gap or inconsistency in a README, do NOT modify it. Instead, record an **Open Question**.
+- Before starting work, read the README of the target directory and follow its structure, templates, and checklist.
+
 ## Subagent Response Contract (required)
 
 When invoked by a QFAI custom prompt, respond using **exactly** this structure:

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

@@ -14,6 +14,12 @@ output_format: markdown
 
 **All outputs MUST be written in the user’s working language for this session.**
 
+## README Rule
+
+- `.qfai/**/README.md` is a reference guide. Do NOT edit README files.
+- If you find a gap or inconsistency in a README, do NOT modify it. Instead, record an **Open Question**.
+- Before starting work, read the README of the target directory and follow its structure, templates, and checklist.
+
 ## Subagent Response Contract (required)
 
 When invoked by a QFAI custom prompt, respond using **exactly** this structure:

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

@@ -1,10 +1,79 @@
-# instructions/
+# instructions
 
-High-level governance for AI behavior in QFAI.
+## 1. 目的
 
-- `constitution.md` : non-negotiable rules (quality, traceability, evidence)
-- `workflow.md` : the default QFAI workflow (SDD→ATDD→TDD→Implement→Verify)
-- `thinking.md` : ambiguity elimination + evidence-first reasoning
-- `communication.md` : reporting style + status format
-- `quality.md` : quality gates + testing expectations
-- `agent-selection.md` : how to delegate to roles (or emulate if unsupported)
+`instructions` は AI の行動規範、品質基準、標準ワークフローを定義します。成果物の粒度と検証手順を揃えます。
+
+## 2. 背景
+
+品質基準が曖昧だと、spec pack の粒度が粗くなり、verify で保証できない曖昧さが残ります。`instructions` はそれを防ぎます。
+
+## 3. ここに配置するもの
+
+- constitution: 絶対に守るルール
+- workflow: 標準ワークフロー
+- quality: 品質ゲートと受入基準
+- thinking: 曖昧さ解消と根拠の書き方
+- communication: 報告フォーマット
+- agent-selection: ロール分担方針
+
+## 4. ここに配置してはならないもの
+
+- プロジェクト固有の事実（steering へ）
+- コマンド別の細かな手順（prompts へ）
+
+## 5. ディレクトリ構造
+
+```text
+.
+├─ README.md
+├─ constitution.md
+├─ workflow.md
+├─ quality.md
+├─ thinking.md
+├─ communication.md
+└─ agent-selection.md
+```
+
+## 6. テンプレート
+
+```md
+# Title
+
+## Rules
+
+- <must>
+
+## Rationale
+
+- <why>
+
+## Checklist
+
+- [ ] <check>
+```
+
+## 7. 完成例
+
+```md
+# Quality
+
+## Rules
+
+- spec pack は 1 主要スライスのみ
+- scenario.feature は 1 ファイル 1 シナリオ
+
+## Rationale
+
+- 粒度が粗いと実装がアドリブ化し、トレーサビリティが崩れる
+
+## Checklist
+
+- [ ] scenario.feature に Scenario が 1 つだけ
+- [ ] spec.md の BR が 1 つだけ
+```
+
+## 8. チェックリスト
+
+- [ ] ルールが定量的、または明確な判断基準として書かれている
+- [ ] 出力の作業完了条件にチェックコマンドが含まれている