qfai 1.0.3 → 1.0.5

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

@@ -0,0 +1,218 @@
+<!--
+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-pr
+title: QFAI PR (Prepare PR Description)
+description: "Generate a PR description that matches the project template and includes evidence."
+argument-hint: "<title> [--auto]"
+allowed-tools: [Read, Glob, Write, Task]
+roles: [Planner, QAEngineer, DevOpsCIEngineer, CodeReviewer]
+mode: doc-focused
+
+---
+
+# /qfai-pr — Prepare PR Description
+
+## Purpose
+
+Generate a PR description that helps reviewers approve quickly:
+
+- What changed / why
+- Impact and migration notes
+- How to verify (commands + evidence)
+- Risk areas to pay attention to
+
+## Success Criteria
+
+- PR body matches the repository’s PR template (if any).
+- Includes verification evidence from /qfai-verify.
+
+## 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 — Locate PR template
+
+Search for:
+
+- `PULL_REQUEST_TEMPLATE.md`
+- `.github/PULL_REQUEST_TEMPLATE.md`
+- repo-specific templates
+
+If none exists, use the standard structure in Step 3.
+
+## Step 2 — Collect evidence
+
+Read the latest verification evidence (from /qfai-verify output or logs).
+
+## Step 3 — Write PR body
+
+Use this structure (adapt to template if present):
+
+### Summary
+
+### Motivation / Context
+
+### Changes
+
+### Impact / Migration
+
+### Verification
+
+(copy‑paste commands + results)
+
+### Risks / Notes
+
+### Reviewer Focus
+
+(what to review carefully)
+
+## Step 4 — Final review
+
+- QA: acceptance coverage and risk notes
+- Code Reviewer: clarity, missing information, misleading claims
+
+## Output
+
+- Ready-to-paste PR title + body

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

@@ -0,0 +1,273 @@
+<!--
+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-require
+title: QFAI Require (Create Requirements Artifact)
+description: "Generate a concrete requirements artifact (EARS + NFR) as a project deliverable."
+argument-hint: "<work-item-name> [--auto]"
+allowed-tools: [Read, Glob, Write, TodoWrite, Task]
+roles: [RequirementsAnalyst, Interviewer, QAEngineer, CodeReviewer, Planner]
+mode: approval-gated
+
+---
+
+# /qfai-require — Create Requirements Artifact
+
+## Purpose
+
+Turn the Requirements Seed (from /qfai-discuss or user input) into a **versioned, reviewable requirements artifact** under `.qfai/require/`.
+
+## Success Criteria (Definition of Done)
+
+- `.qfai/require/require.md` exists and is readable by a newcomer.
+- Requirements are **testable** (EARS style) and include **NFR** (security/performance/etc).
+- Blocking Open Questions are explicitly listed with requested answers.
+
+## 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 — Ensure repository location
+
+Create (or update) these files:
+
+- `.qfai/require/README.md` — what this folder is, how to use it
+- `.qfai/require/require.md` — the requirements artifact (single-file SSOT)
+
+## Step 2 — Requirements format: EARS (Requirements Analyst)
+
+Use EARS patterns (inspired by SDD frameworks):
+
+- **Ubiquitous**: “The system shall …”
+- **Event‑driven**: “When <event>, the system shall …”
+- **State‑driven**: “While <state>, the system shall …”
+- **Unwanted behavior**: “If <undesired>, the system shall …”
+- **Optional feature**: “Where <feature>, the system shall …”
+
+### Requirement ID scheme
+
+Use stable IDs:
+
+- `REQ-FUNC-###` for functional requirements
+- `REQ-NFR-SEC-###`, `REQ-NFR-PERF-###`, `REQ-NFR-REL-###` etc for non-functional
+
+IDs must be unique and never reused.
+
+## Step 3 — Write `require.md` with this template
+
+Use this exact structure:
+
+# Requirements
+
+## 1. Overview
+
+- Problem / opportunity
+- Target users
+- Success definition (business + technical)
+
+## 2. Scope
+
+### In scope
+
+### Out of scope
+
+## 3. Constraints & Assumptions
+
+- Constraints
+- Assumptions (explicit)
+
+## 4. Glossary (optional but recommended)
+
+## 5. Functional Requirements (EARS)
+
+### REQ-FUNC-001: <title>
+
+- Statement (EARS)
+- Rationale
+- Acceptance criteria (testable)
+- Notes / edge cases
+
+(repeat)
+
+## 6. Non‑Functional Requirements
+
+### Security
+
+### Performance
+
+### Reliability / Availability
+
+### Observability
+
+### Compliance / Privacy (if relevant)
+
+## 7. Acceptance Criteria (summary)
+
+A bullet list of what must be true to accept the change.
+
+## 8. Open Questions
+
+### Blocking
+
+### Non‑blocking
+
+## Step 4 — Review cycle (QA + Code Reviewer)
+
+- QA Engineer checks testability and missing failure cases.
+- Code Reviewer checks ambiguity, contradictions, and “non‑testable language”.
+
+## Step 5 — Approval gate
+
+If interactive mode:
+
+- Ask the user for approval: “Approve requirements? (yes/no)”
+- If no: update and repeat.
+  If `--auto`:
+- Proceed, but highlight assumptions and warn about rework risk.
+
+## Output
+
+- Updated `.qfai/require/README.md`
+- Updated `.qfai/require/require.md`
+- A short “next command” suggestion (typically /qfai-spec)