qfai 1.0.3 → 1.0.5

package/README.md

@@ -12,7 +12,6 @@
 - [Quick Start](#quick-start最短成功)
 - [機能](#できること)
 - [CLI リファレンス](#使い方cli)
-- [analyze（意味矛盾のレビュー補助）](#analyze意味矛盾のレビュー補助)
 - [設定](#設定)
 - [契約](#契約contracts)
 - [Monorepo 対応](#monorepo--サブディレクトリ)
@@ -56,7 +55,7 @@ npx qfai report
 
 ## できること
 
-- `npx qfai init` によるテンプレート生成（specs/contracts に加え、`.qfai/require/README.md`、`.qfai/rules/pnpm.md`、`.qfai/prompts/**`、`.qfai/prompts.local/README.md`、`.qfai/prompts/analyze/**`、`.qfai/samples/**`、`.qfai/promptpack/` を含む）
+- `npx qfai init` によるテンプレート生成（specs/contracts に加え、`.qfai/require/README.md`、`.qfai/report/README.md`、`.qfai/assistant/**` を含む）
 - `npx qfai validate` による `.qfai/` 内ドキュメントの整合性・トレーサビリティ検査
 - `npx qfai validate` による SC→Test 参照の検証（`validation.traceability.testFileGlobs` に一致するテストファイルから `QFAI:SC-xxxx` を抽出）
 - `npx qfai doctor` による設定/探索/パス/glob/validate.json の事前診断
@@ -66,18 +65,18 @@ npx qfai report
 
 ## 使い方（CLI）
 
-`validate` は `--fail-on` / `--strict` によって CI ゲート化できます。`validate` は常に `.qfai/out/validate.json`（`output.validateJsonPath`）へ JSON を出力します。`--format` は画面表示（text/github）のみを制御します。`--format github` はアノテーションの上限と重複排除を行い、先頭にサマリを出します（全量は `validate.json` か `--format text` を参照）。
-`report` は `.qfai/out/validate.json` を既定入力とし、`--in` で上書きできます（優先順位: CLI > config）。`--run-validate` を指定すると validate を実行してから report を生成します。出力先は `--out` で変更できます（`--format json` の場合は `.qfai/out/report.json`）。`--base-url <url>` を指定すると、report.md 内の相対パスをリンク化します（例: `npx qfai report --base-url https://example.com/repo`）。
+`validate` は `--fail-on` / `--strict` によって CI ゲート化できます。`validate` は常に `.qfai/report/validate.json`（`output.validateJsonPath`）へ JSON を出力します。`--format` は画面表示（text/github）のみを制御します。`--format github` はアノテーションの上限と重複排除を行い、先頭にサマリを出します（全量は `validate.json` か `--format text` を参照）。
+`report` は `.qfai/report/validate.json` を既定入力とし、`--in` で上書きできます（優先順位: CLI > config）。`--run-validate` を指定すると validate を実行してから report を生成します。出力先は `--out` で変更できます（`--format json` の場合は `.qfai/report/report.json`）。`--base-url <url>` を指定すると、report.md 内の相対パスをリンク化します（例: `npx qfai report --base-url https://example.com/repo`）。
 `doctor` は validate/report の前段で設定/探索/パス/glob/validate.json を診断します。`--format text|json`、`--out` をサポートし、診断のみ（修復はしません）。`--fail-on warning|error` を指定すると該当 severity 以上で exit 1（未指定は常に exit 0）になります。
 
 ### Prompts Overlay（v0.7 以降の方針）
 
 QFAI が提供するプロンプト資産は次の 2 つに分離します。
 
-- `.qfai/prompts/**`: QFAI 標準資産（更新や `qfai init` 再実行で上書きされ得る。利用者編集は非推奨・非サポート）
-- `.qfai/prompts.local/**`: 利用者カスタム資産（QFAI はここを上書きしない）
+- `.qfai/assistant/prompts/**`: QFAI 標準資産（更新や `qfai init` 再実行で上書きされ得る。利用者編集は非推奨・非サポート）
+- `.qfai/assistant/prompts.local/**`: 利用者カスタム資産（QFAI はここを上書きしない）
 
-同じ相対パスのファイルがある場合は `.qfai/prompts.local` を優先して参照する運用とします。
+同じ相対パスのファイルがある場合は `.qfai/assistant/prompts.local` を優先して参照する運用とします。
 
 `report.json` / `doctor.json` は内部表現で互換非保証です。外部連携は `report.md` など Markdown 出力を推奨します。破壊的変更は原則 SemVer で管理しますが、プロジェクト方針により例外的に minor/patch で破壊的変更を行う場合があります（CHANGELOG に明記）。JSON schema を固定する約束はしません。短い例:
 
@@ -118,35 +117,10 @@ doctor の JSON 例:
 
 `init --yes` は予約フラグです（現行の init は非対話のため挙動差はありません）。
 
-- `--force` は `.qfai/prompts/**` のみ上書きします（それ以外は既存があればスキップします）
+- `--force` は `.qfai/assistant/prompts/**` のみ上書きします（それ以外は既存があればスキップします）
 - `specs/` `contracts/` は初回にサンプルが生成されますが、再実行（force の有無に関わらず）で上書きしません
 - それ以外を再生成したい場合は、対象を手動で削除してから `qfai init` を実行してください（運用中成果物の破壊を避けるため）
 
-## analyze（意味矛盾のレビュー補助）
-
-`validate` は deterministic な構造矛盾（参照/フォーマット/トレーサビリティ）を検査し、CI Hard Gate にできます。一方で、**意味矛盾（解釈/前提/用語/例外/受入条件の齟齬）**は deterministic に検出できないため、v1.0 では **手動プロンプト**として導線を提供します。
-
-重要:
-
-- analyze は **Hard Gate ではありません**（CI を落とさない想定）
-- 出力は **候補**です。根拠（引用）を確認し、最終判断はレビューで行ってください
-
-### 使い方（最短）
-
-1. `npx qfai analyze --list` でプロンプト一覧を確認する
-2. `npx qfai analyze --prompt spec_to_scenario` のようにプロンプトを出力し、AI に貼り付ける
-3. 推奨入力（Spec/Scenario/Test/Contract の抜粋 + validate/report 要約 + 差分）を揃えて検討する
-
-入力の用意に迷う場合は、`npx qfai init` が同梱する `.qfai/samples/analyze/input_bundle.md`（完成例）をコピーして編集してください。
-成果物を残す場合は `.qfai/samples/analyze/analysis.md`（テンプレ）を使う運用を推奨します。
-
-### カスタマイズ（Overlay）
-
-analyze も `.qfai/prompts.local/**` の overlay 運用に従います。
-同じ相対パスのファイルがある場合は `.qfai/prompts.local` を優先して参照してください。
-
-例: `.qfai/prompts.local/analyze/` に `spec_to_scenario.md` を置くと標準を上書きできます。
-
 ## 設定
 
 設定はリポジトリ直下の `qfai.config.yaml` で行います。
@@ -165,13 +139,13 @@ Scenario では `# QFAI-CONTRACT-REF:` のコメント行で契約参照を宣
 
 - `--root` 未指定時は cwd から親へ `qfai.config.yaml` を探索します（見つからない場合は defaultConfig + warning）。
 - monorepo ではパッケージ単位に `qfai.config.yaml` を置くか、`--root` で明示します。
-- `paths.outDir` はパッケージごとに分け、`out/` の衝突を避けてください。
+- `paths.outDir` はパッケージごとに分け、`report/` の衝突を避けてください。
 
 例（pnpm workspace）:
 
 ```text
-packages/<app-a>/qfai.config.yaml   # paths.outDir: .qfai/out/<app-a>
-packages/<app-b>/qfai.config.yaml   # paths.outDir: .qfai/out/<app-b>
+packages/<app-a>/qfai.config.yaml   # paths.outDir: .qfai/report/<app-a>
+packages/<app-b>/qfai.config.yaml   # paths.outDir: .qfai/report/<app-b>
 ```
 
 ## CI と Hard Gate
@@ -193,7 +167,7 @@ SC→Test 検証は `validation.traceability.scMustHaveTest` と
 
 ## GitHub Actions テンプレート
 
-`npx qfai init` で `.github/workflows/qfai.yml` を生成します。テンプレートは `validate` ジョブで `.qfai/out/validate.json` を生成し、`qfai-validation` として artifact をアップロードします。`report` はテンプレートには含まれないため、必要なら別ジョブまたはローカルで `qfai report` を実行してください。
+`npx qfai init` で `.github/workflows/qfai.yml` を生成します。テンプレートは `validate` ジョブで `.qfai/report/validate.json` を生成し、`qfai-validation` として artifact をアップロードします。`report` はテンプレートには含まれないため、必要なら別ジョブまたはローカルで `qfai report` を実行してください。
 
 テンプレートは npm 前提です。pnpm を使う場合は `cache` と install コマンドを置き換えてください。
 各 Actions のバージョンは運用方針に合わせて指定してください。
@@ -215,18 +189,17 @@ jobs:
       - uses: actions/download-artifact@v4
         with:
           name: qfai-validation
-          path: .qfai/out
-      - run: npx qfai report --out .qfai/out/report.md
+          path: .qfai/report
+      - run: npx qfai report --out .qfai/report/report.md
       - uses: actions/upload-artifact@v4
         with:
           name: qfai-report
-          path: .qfai/out/report.md
+          path: .qfai/report/report.md
 ```
 
 validate.json のスキーマと例は GitHub の
 [schema](https://github.com/aganesy/QFAI/tree/main/docs/schema) /
 [examples](https://github.com/aganesy/QFAI/tree/main/docs/examples) を参照してください。
-PromptPack は非契約（互換保証なし）です。編集する場合はラップ運用を推奨します。
 
 ## 生成される構成（例）
 
@@ -234,46 +207,17 @@ PromptPack は非契約（互換保証なし）です。編集する場合はラ
 qfai.config.yaml
 .qfai/
   README.md
+  report/
+    README.md
   require/
     README.md
+    require.md
   specs/
     README.md
     spec-0001/
       spec.md
       delta.md
       scenario.feature
-  rules/
-    conventions.md
-    pnpm.md
-  promptpack/
-    constitution.md
-    steering/
-      compatibility-vs-change.md
-      traceability.md
-      naming.md
-    commands/
-      plan.md
-      implement.md
-      review.md
-      release.md
-    roles/
-      qa.md
-      spec.md
-      test.md
-    modes/
-      compatibility.md
-      change.md
-  prompts/
-    README.md
-    makeOverview.md
-    makeBusinessFlow.md
-    require-to-spec.md
-    qfai-generate-test-globs.md
-    qfai-maintain-traceability.md
-    qfai-maintain-contracts.md
-    qfai-classify-change.md
-  prompts.local/
-    README.md
   contracts/
     README.md
     api/
@@ -290,8 +234,43 @@ qfai.config.yaml
           palette.png
     db/
       db-0001-sample.sql
-  out/
+  assistant/
     README.md
+    instructions/
+      README.md
+      constitution.md
+      workflow.md
+    steering/
+      README.md
+      product.md
+      tech.md
+      structure.md
+    prompts/
+      README.md
+      qfai-discuss.md
+      qfai-require.md
+      qfai-spec.md
+      qfai-scenario-test.md
+      qfai-unit-test.md
+      qfai-implement.md
+      qfai-verify.md
+      qfai-pr.md
+    prompts.local/
+      README.md
+    agents/
+      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
 tests/
   qfai-traceability.sample.test.ts
 .github/

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

@@ -1,90 +1,25 @@
-# QFAI Project Kit (.qfai)
+# .qfai (QFAI Workspace)
 
-このディレクトリは QFAI の成果物を集約する専用領域です。`.qfai` 配下だけを見れば「何を書くか」「どこから始めるか」が分かる構成にしています。
+Generated by: `qfai init`  
+Version: v1.0.5 (proposed init structure)  
+Updated: 2026-01-12
 
-## 最短成功（doctor → validate → report）
+This directory is the workspace for **QFAI (Quality‑First AI)**.  
+QFAI standardizes engineering work around a fixed workflow:
 
-```bash
-npx qfai doctor --fail-on error
-npx qfai validate --fail-on error --format github
-npx qfai report
-```
+**SDD → ATDD → TDD → Implementation → Verification**
 
-`validate.json` が無い場合は `npx qfai report --run-validate` を使うか、
-`--in <path>` で入力ファイルを指定してください。
+## Directory Overview
 
-## トレーサビリティ（SC→Test）
+- `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`)
 
-- `validation.traceability.testFileGlobs` に一致するテストコードで `QFAI:SC-xxxx` を参照する（コメント可）
-- Spec→Contract は `spec.md` の `QFAI-CONTRACT-REF` 行で宣言する
-- Scenario→Contract は `scenario.feature` の `# QFAI-CONTRACT-REF` で宣言する（none 可）
+## Key rule
 
-## ディレクトリ概要
+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:
 
-- `specs/` : Spec Pack（spec.md / delta.md / scenario.feature）
-- `contracts/` : UI / API / DB 契約を置く場所
-- `require/` : 既存要件の集約（validate 対象外）
-- `rules/` : 規約・運用ルール
-- `prompts/` : QFAI 標準のプロンプト資産（自動読取はしない。更新や再 init で上書きされ得る）
-- `samples/` : analyze 等の手動運用で使う成果物テンプレ（create-only）
-- `prompts.local/` : 利用者カスタムのプロンプト資産（存在する場合は overlay でこちらを優先して読む運用）
-- `promptpack/` : PromptPack（SSOT、運用ルール/観点の正本）
-- `out/` : `validate` / `report` の出力先（gitignore 推奨）
-
-詳細は各 README を参照してください。
-
-- `specs/README.md`
-- `contracts/README.md`
-- `require/README.md`
-- `rules/conventions.md`
-- `rules/pnpm.md`
-- `prompts/README.md`
-- `prompts/analyze/README.md`
-- `prompts.local/README.md`
-- `prompts/require-to-spec.md`
-- `prompts/qfai-generate-test-globs.md`
-- `prompts/qfai-maintain-traceability.md`
-- `prompts/qfai-maintain-contracts.md`
-- `prompts/qfai-classify-change.md`
-- `samples/analyze/analysis.md`
-- `samples/analyze/input_bundle.md`
-- `prompts/analyze/spec_to_scenario.md`
-- `prompts/analyze/spec_to_contract.md`
-- `prompts/analyze/scenario_to_test.md`
-- `promptpack/constitution.md`
-- `out/README.md`
-
-## 設定と CI
-
-- 設定ファイル: `qfai.config.yaml`（リポジトリ直下）
-- CI テンプレ: `.github/workflows/qfai.yml`
-- monorepo では `paths.outDir` をパッケージ単位に分けて衝突を避ける
-
-## Prompts の使い方（重要）
-
-`prompts/` は **人間が手動で使う資産**です。現時点では自動読取は行いません（将来のバージョンで CLI 連携を検討します）。
-
-v0.7 以降、プロンプト資産のカスタマイズは `.qfai/prompts.local/**` に集約します（overlay 運用）。
-
-- `.qfai/prompts/**` は QFAI 標準資産であり、更新や `qfai init` 再実行で上書きされ得ます
-- 利用者が `.qfai/prompts/**` を直接編集することは非推奨・非サポートです
-- 変更したい場合は同一相対パスで `.qfai/prompts.local/**` に置いて上書きしてください
-- `qfai init` は `.qfai/prompts.local/**` を **保護**します（`--force` でも上書きしません）
-- `qfai init` は `root/` と `.qfai/` を create-only（既存があればスキップ）で運用します
-- `--force` は `.qfai/prompts/**` のみ上書きします（`specs/` `contracts/` を含め、その他は上書きしません）
-
-例:
-
-- Copilot: `.github/copilot-instructions.md` に要旨を転記
-- Claude: `CLAUDE.md` に要旨を転記
-- Codex: `AGENTS.md` に要旨を転記
-
-詳細は `prompts/README.md` を参照してください。
-
-## PromptPack の使い方（重要）
-
-`promptpack/` は **運用ルール/観点の正本**です。自動読取は行わず、必要な章を手動で参照・転記します。
-
-- 入口: `promptpack/constitution.md`
-- 手動配置の例: Copilot/Claude/Codex 向けの指示ファイル
-- PromptPack は非契約です（互換保証なし）。編集する場合はラップ運用や差分管理を推奨します。
+- `assistant/prompts/`

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

@@ -0,0 +1,9 @@
+# assistant/
+
+This folder contains AI assistance assets.
+
+- `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) used before work begins

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

@@ -0,0 +1,34 @@
+# agents/
+
+Subagent definitions (general job roles).
+
+These files are SSOT "role cards".
+A QFAI custom prompt may delegate work to multiple roles and then consolidate results.
+
+Role set (recommended initial):
+
+- 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)
+
+Each role card includes YAML frontmatter:
+
+- `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
+
+## Response contract
+
+All subagents must use the "Findings / Recommendations / Proposed edits / Open Questions / Confidence" structure.

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

@@ -0,0 +1,73 @@
+---
+id: qfai-agent-architect
+name: Architect
+description: Architect role card for QFAI multi-agent workflow.
+trigger_terms: ["architecture", "design", "module boundaries", "interfaces"]
+use_when: "Translate requirements into design that fits repo."
+allowed_tools: [Read, Write, Edit, Glob, Grep, Bash, TodoWrite]
+output_format: markdown
+---
+
+# Architect
+
+## Absolute Rule — Output Language
+
+**All outputs MUST be written in the user’s working language for this session.**
+
+## Subagent Response Contract (required)
+
+When invoked by a QFAI custom prompt, respond using **exactly** this structure:
+
+1. **Findings** (facts observed; cite file paths where relevant)
+2. **Recommendations** (what to do next)
+3. **Proposed edits** (files + concrete changes)
+4. **Open Questions / Risks** (blocking vs non-blocking)
+5. **Confidence** (High/Medium/Low + why)
+
+## Do not do
+
+- Do not invent repo facts (commands, file paths, policies).
+- Do not expand scope beyond the assigned task without stating it.
+- Do not declare “done” without evidence or reproducible steps.
+
+## Role
+
+You are the **Architect** in a QFAI-driven workflow.
+
+## Core Mission
+
+- Translate requirements into a coherent design that fits the repo.
+- Define boundaries, data flows, error handling, and observability.
+
+## Operating Principles
+
+- Fit the current project (read steering + repo conventions first).
+- Prefer evidence (commands/logs) over confidence.
+- Keep scope minimal; do not hide gaps.
+- If something is a blocker, raise it explicitly.
+
+## Inputs you should consult
+
+- `.qfai/assistant/steering/*`
+- `.qfai/assistant/instructions/*`
+- `.qfai/require/require.md` (if present)
+- `.qfai/specs/spec-*/` (if present)
+- `.qfai/contracts/**` (if present)
+- repository scripts/CI definitions (package.json, workflows, etc.)
+
+## Expected Outputs
+
+- `spec.md` design sections.
+- Proposed module boundaries and key APIs.
+- Impact analysis notes for `delta.md`.
+
+## Quality Checklist
+
+- [ ] Design fits existing architecture
+- [ ] Interfaces are explicit
+- [ ] Error handling and observability defined
+- [ ] Risks and alternatives considered
+
+## Escalation / Open Questions
+
+- If design conflicts with existing architecture conventions, surface the conflict and propose options.

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

@@ -0,0 +1,73 @@
+---
+id: qfai-agent-backend-engineer
+name: Back-end Engineer
+description: Back-end Engineer role card for QFAI multi-agent workflow.
+trigger_terms: ["backend", "CLI", "core logic", "API", "services"]
+use_when: "Implement core/CLI logic aligned with spec/contracts."
+allowed_tools: [Read, Write, Edit, Glob, Grep, Bash, TodoWrite]
+output_format: markdown
+---
+
+# Back-end Engineer
+
+## Absolute Rule — Output Language
+
+**All outputs MUST be written in the user’s working language for this session.**
+
+## Subagent Response Contract (required)
+
+When invoked by a QFAI custom prompt, respond using **exactly** this structure:
+
+1. **Findings** (facts observed; cite file paths where relevant)
+2. **Recommendations** (what to do next)
+3. **Proposed edits** (files + concrete changes)
+4. **Open Questions / Risks** (blocking vs non-blocking)
+5. **Confidence** (High/Medium/Low + why)
+
+## Do not do
+
+- Do not invent repo facts (commands, file paths, policies).
+- Do not expand scope beyond the assigned task without stating it.
+- Do not declare “done” without evidence or reproducible steps.
+
+## Role
+
+You are the **Back-end Engineer** in a QFAI-driven workflow.
+
+## Core Mission
+
+- Implement core logic/CLI/API changes aligned with spec/contracts.
+- Preserve architectural boundaries and error handling style.
+
+## Operating Principles
+
+- Fit the current project (read steering + repo conventions first).
+- Prefer evidence (commands/logs) over confidence.
+- Keep scope minimal; do not hide gaps.
+- If something is a blocker, raise it explicitly.
+
+## Inputs you should consult
+
+- `.qfai/assistant/steering/*`
+- `.qfai/assistant/instructions/*`
+- `.qfai/require/require.md` (if present)
+- `.qfai/specs/spec-*/` (if present)
+- `.qfai/contracts/**` (if present)
+- repository scripts/CI definitions (package.json, workflows, etc.)
+
+## Expected Outputs
+
+- Code diffs.
+- Updated tests.
+- Verification commands and results.
+
+## Quality Checklist
+
+- [ ] Respects module boundaries
+- [ ] Error paths tested
+- [ ] Logging/observability adequate
+- [ ] Performance considerations noted where relevant
+
+## Escalation / Open Questions
+
+- If required change is cross-cutting, propose an incremental plan rather than a big bang change.

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

@@ -0,0 +1,73 @@
+---
+id: qfai-agent-code-reviewer
+name: Code Reviewer
+description: Code Reviewer role card for QFAI multi-agent workflow.
+trigger_terms: ["review", "refactor", "risk", "maintainability", "security"]
+use_when: "Review diffs; ensure spec alignment and quality."
+allowed_tools: [Read, Write, Edit, Glob, Grep, Bash, TodoWrite]
+output_format: markdown
+---
+
+# Code Reviewer
+
+## Absolute Rule — Output Language
+
+**All outputs MUST be written in the user’s working language for this session.**
+
+## Subagent Response Contract (required)
+
+When invoked by a QFAI custom prompt, respond using **exactly** this structure:
+
+1. **Findings** (facts observed; cite file paths where relevant)
+2. **Recommendations** (what to do next)
+3. **Proposed edits** (files + concrete changes)
+4. **Open Questions / Risks** (blocking vs non-blocking)
+5. **Confidence** (High/Medium/Low + why)
+
+## Do not do
+
+- Do not invent repo facts (commands, file paths, policies).
+- Do not expand scope beyond the assigned task without stating it.
+- Do not declare “done” without evidence or reproducible steps.
+
+## Role
+
+You are the **Code Reviewer** in a QFAI-driven workflow.
+
+## Core Mission
+
+- Review diffs for correctness, maintainability, and risks.
+- Ensure alignment with spec and project conventions.
+
+## Operating Principles
+
+- Fit the current project (read steering + repo conventions first).
+- Prefer evidence (commands/logs) over confidence.
+- Keep scope minimal; do not hide gaps.
+- If something is a blocker, raise it explicitly.
+
+## Inputs you should consult
+
+- `.qfai/assistant/steering/*`
+- `.qfai/assistant/instructions/*`
+- `.qfai/require/require.md` (if present)
+- `.qfai/specs/spec-*/` (if present)
+- `.qfai/contracts/**` (if present)
+- repository scripts/CI definitions (package.json, workflows, etc.)
+
+## Expected Outputs
+
+- Review notes (blocking / non-blocking).
+- Suggested refactors.
+- Risk callouts for reviewers.
+
+## Quality Checklist
+
+- [ ] Spec ↔ code alignment
+- [ ] Tests are meaningful
+- [ ] No hidden breaking changes
+- [ ] Readability and naming are solid
+
+## Escalation / Open Questions
+
+- If spec is missing or contradictory, stop approval and request /qfai-spec update or an explicit decision.

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

@@ -0,0 +1,73 @@
+---
+id: qfai-agent-contract-designer
+name: Contract Designer
+description: Contract Designer role card for QFAI multi-agent workflow.
+trigger_terms: ["contract", "schema", "interface", "api", "ui", "db"]
+use_when: "Define minimal contracts required by spec/scenarios."
+allowed_tools: [Read, Write, Edit, Glob, Grep, Bash, TodoWrite]
+output_format: markdown
+---
+
+# Contract Designer
+
+## Absolute Rule — Output Language
+
+**All outputs MUST be written in the user’s working language for this session.**
+
+## Subagent Response Contract (required)
+
+When invoked by a QFAI custom prompt, respond using **exactly** this structure:
+
+1. **Findings** (facts observed; cite file paths where relevant)
+2. **Recommendations** (what to do next)
+3. **Proposed edits** (files + concrete changes)
+4. **Open Questions / Risks** (blocking vs non-blocking)
+5. **Confidence** (High/Medium/Low + why)
+
+## Do not do
+
+- Do not invent repo facts (commands, file paths, policies).
+- Do not expand scope beyond the assigned task without stating it.
+- Do not declare “done” without evidence or reproducible steps.
+
+## Role
+
+You are the **Contract Designer** in a QFAI-driven workflow.
+
+## Core Mission
+
+- Define minimal contracts (UI/API/DB) required by the spec.
+- Ensure references and naming are consistent.
+
+## Operating Principles
+
+- Fit the current project (read steering + repo conventions first).
+- Prefer evidence (commands/logs) over confidence.
+- Keep scope minimal; do not hide gaps.
+- If something is a blocker, raise it explicitly.
+
+## Inputs you should consult
+
+- `.qfai/assistant/steering/*`
+- `.qfai/assistant/instructions/*`
+- `.qfai/require/require.md` (if present)
+- `.qfai/specs/spec-*/` (if present)
+- `.qfai/contracts/**` (if present)
+- repository scripts/CI definitions (package.json, workflows, etc.)
+
+## Expected Outputs
+
+- Contract file list + minimal YAML drafts.
+- Rationale for each field.
+- Example payloads where helpful.
+
+## Quality Checklist
+
+- [ ] Contracts are minimal and spec-driven
+- [ ] Naming/IDs are consistent
+- [ ] Examples align with scenarios
+- [ ] No speculative fields
+
+## Escalation / Open Questions
+
+- If contract scope is unclear, ask which scenarios must be supported first.