qfai 1.4.4 → 1.4.7

package/README.md

@@ -31,7 +31,7 @@ npx qfai report
 ## What you can do (CLI commands)
 
 - `npx qfai init`
-  - Creates the QFAI workspace under `.qfai/` (requirements/specs/contracts/report) and installs the AI assistant kit (`assistant/` with skills, instructions, agents, and steering templates), plus a default GitHub Actions workflow and `qfai.config.yaml`.
+  - Creates the QFAI workspace under `.qfai/` (requirements/specs/contracts/report) and installs the AI assistant kit (`assistant/` with skills, instructions, agents, and steering templates), plus `qfai.config.yaml`.
 - `npx qfai validate`
   - Validates specs/contracts/scenarios/traceability and writes `.qfai/report/validate.json`; use `--fail-on error` (or `--fail-on warning`) to turn it into a CI gate, and `--format github` to emit GitHub-friendly annotations. Use `--phase refinement` only for local refinement checks; CI should use default/full validation.
 - `npx qfai report`
@@ -42,7 +42,7 @@ npx qfai report
 ## Operating model (skills-driven workflow)
 
 QFAI assumes you operate the project primarily via prepared custom skills.
-A custom skill is a reusable task instruction set for your AI coding agent (for example, IDE/CLI skill wrappers that link to canonical QFAI skills).
+A custom skill is a reusable task instruction set for your AI coding agent.
 The agent reads QFAI assets under `.qfai/assistant/` and produces or updates SDD/ATDD/TDD artifacts and code.
 
 ### Where the skills live
@@ -58,12 +58,12 @@ QFAI includes a small set of custom skills (stored under `.qfai/assistant/skills
 - **qfai-discuss**: Turn an idea into clear requirements by discussing scope, constraints, risks, and open questions.
 - **qfai-require**: Produce `.qfai/require/REQUIRE-XXXX/*` from your idea or discussion output.
 - **qfai-sdd**: Produce/update the full spec pack (`01_Spec.md` to `18_delta.md`) in one workflow (Outline -> Slice -> Plan finalize -> Delta).
-- **qfai-spec**: Deprecated alias of `qfai-sdd` for backward compatibility.
-- **qfai-scenario-test**: Implement acceptance tests (ATDD) driven by specs/scenarios.
-- **qfai-unit-test**: Implement unit tests (TDD) driven by specs/scenarios.
-- **qfai-implement**: Implement the feature; iterate test→fix until all quality gates are green.
-- **qfai-verify**: Run/interpret the local quality gates and produce a PR-ready summary.
-- **qfai-pr**: Draft a PR description aligned with the repository’s PR template.
+- **qfai-prototyping**: Build a contract-aligned skeleton implementation before deep coding.
+- **qfai-atdd**: Implement acceptance tests driven by specs/scenarios.
+- **qfai-tdd-red**: Add failing unit/component tests from the approved acceptance scenarios.
+- **qfai-tdd-green**: Implement production code to satisfy failing tests.
+- **qfai-tdd-refactor**: Refactor while keeping all tests green.
+- **qfai-verify**: Run/interpret the local quality gates and produce a release-ready summary.
 
 ### Workflow sequence (example)
 
@@ -100,24 +100,39 @@ AG->>Q: Read .qfai/assistant/skills/qfai-sdd/SKILL.md
 AG->>R: Create/refine spec pack (01..18) + contracts + 17_Plan.md
 AG-->>U: SDD artifacts ready
 
-U->>AG: Run /qfai-scenario-test
-AG->>Q: Read .qfai/assistant/skills/qfai-scenario-test/SKILL.md
+U->>AG: Run /qfai-prototyping
+AG->>Q: Read .qfai/assistant/skills/qfai-prototyping/SKILL.md
+AG->>R: Build contract-aligned implementation skeleton
+AG-->>U: Prototype ready
+
+U->>AG: Run /qfai-atdd
+AG->>Q: Read .qfai/assistant/skills/qfai-atdd/SKILL.md
 AG->>R: Implement acceptance tests
-AG-->>U: Scenario tests ready
+AG-->>U: ATDD tests ready
 
-U->>AG: Run /qfai-unit-test
-AG->>Q: Read .qfai/assistant/skills/qfai-unit-test/SKILL.md
-AG->>R: Implement unit tests
-AG-->>U: Unit tests ready
+U->>AG: Run /qfai-tdd-red
+AG->>Q: Read .qfai/assistant/skills/qfai-tdd-red/SKILL.md
+AG->>R: Add failing unit/component tests
+AG-->>U: RED state ready
 
-U->>AG: Run /qfai-implement
-AG->>Q: Read .qfai/assistant/skills/qfai-implement/SKILL.md
+U->>AG: Run /qfai-tdd-green
+AG->>Q: Read .qfai/assistant/skills/qfai-tdd-green/SKILL.md
 loop Implement and fix until green
 AG->>R: Implement code changes
 AG->>R: Run project tests locally
 end
 AG-->>U: Working implementation (quality gates passing)
 
+U->>AG: Run /qfai-tdd-refactor
+AG->>Q: Read .qfai/assistant/skills/qfai-tdd-refactor/SKILL.md
+AG->>R: Refactor with tests green
+AG-->>U: Refactor complete
+
+U->>AG: Run /qfai-verify
+AG->>Q: Read .qfai/assistant/skills/qfai-verify/SKILL.md
+AG->>R: Run quality gates and summarize evidence
+AG-->>U: Verification summary ready
+
 U->>R: Run npx qfai validate
 U->>R: Run npx qfai report
 R-->>U: Traceability checks and report artifacts
@@ -126,6 +141,7 @@ R-->>U: Traceability checks and report artifacts
 Operational notes.
 
 - Each custom skill must output in the user’s language (absolute requirement).
+- Each custom skill must end with a completion message that enumerates all available next actions and clearly states what to do for each option.
 - Except `qfai-discuss`, each skill must analyze the project context (architecture, tech stack, test framework, repo structure) before generating artifacts or code.
 - Skills should delegate work to multiple role-based sub-agents (Planner, Architect, Contract Designer, QA, Code Reviewer, etc.) to emulate a real delivery flow.
 - Change classification (Primary/Tags) is required in `18_delta.md` and recommended in PRs. See `.qfai/assistant/instructions/change-classification.md`.
@@ -191,7 +207,7 @@ flowchart LR
 - Contracts SSOT: `.qfai/contracts/**`
 - Report outputs (`.qfai/report/**`) are derived artifacts and not SSOT.
 
-## Minimal tutorial (v1.4.4)
+## Minimal tutorial (v1.4.7)
 
 1. `npx qfai init`
 2. Run `/qfai-discuss` to structure scope and open questions.
@@ -215,17 +231,22 @@ Release gate behavior:
 - Q: release_candidate validation fails due open questions.
   - A: In `15_Open-questions.md`, change `status: open` to `resolved` or `deferred` and keep evidence.
 
-## Continuous integration (GitHub Actions)
+## Continuous integration
 
-(GitHub Actions)
+QFAI v1.4.7 no longer generates `.github/**` assets.
+Configure CI in your own platform and run:
 
-`npx qfai init` generates `.github/workflows/qfai.yml` which runs `npx qfai validate --fail-on error` on pull requests and on pushes to `main`, and uploads `.qfai/report/validate.json` as an artifact.
+```bash
+pnpm ci:local
+# or, minimum gate only:
+npx qfai validate --fail-on error
+```
 
-What works out-of-the-box.
+Recommended baseline.
 
-- The generated workflow is npm-oriented (`npm ci`); if your repository uses pnpm/yarn/bun, replace the install/cache steps accordingly.
-- The default validate gate fails only on `error`; use `--fail-on warning` or `--strict` if you want a stricter gate.
 - Keep CI on default/full validation (`qfai validate --fail-on error`); do not use `--phase refinement` in CI.
+- Add a report step (`npx qfai report`) when you need a human-readable artifact.
+- Tune traceability globs in `qfai.config.yaml` to match your test layout.
 
 Waiver policy.
 
@@ -236,9 +257,8 @@ Waiver policy.
 
 Typical customizations.
 
-- Add a second job to generate `report.md` from the uploaded `validate.json`.
 - Add a `doctor` step before validate if you want to fail fast on path/glob/config issues.
-- Tune traceability globs in `qfai.config.yaml` to match your test layout.
+- Publish `.qfai/report/validate.json` and `report.md` as CI artifacts.
 
 ## Generated structure
 
@@ -246,50 +266,6 @@ Typical customizations.
 
 ```text
 .
-├── .claude
-│   └── skills
-│       ├── qfai-configure
-│       │   └── SKILL.md
-│       ├── qfai-discuss
-│       │   └── SKILL.md
-│       ├── qfai-require
-│       │   └── SKILL.md
-│       └── ...
-├── .codex
-│   └── skills
-│       ├── qfai-configure
-│       │   └── SKILL.md
-│       ├── qfai-discuss
-│       │   └── SKILL.md
-│       ├── qfai-implement
-│       │   └── SKILL.md
-│       ├── qfai-pr
-│       │   └── SKILL.md
-│       ├── qfai-require
-│       │   └── SKILL.md
-│       ├── qfai-scenario-test
-│       │   └── SKILL.md
-│       ├── qfai-sdd
-│       │   └── SKILL.md
-│       ├── qfai-spec
-│       │   └── SKILL.md
-│       ├── qfai-unit-test
-│       │   └── SKILL.md
-│       └── qfai-verify
-│           └── SKILL.md
-├── .github
-│   ├── skills
-│   │   ├── qfai-configure
-│   │   │   └── SKILL.md
-│   │   ├── qfai-discuss
-│   │   │   └── SKILL.md
-│   │   ├── qfai-require
-│   │   │   └── SKILL.md
-│   │   └── ...
-│   ├── workflows
-│   │   └── qfai.yml
-│   ├── copilot-instructions.md
-│   └── PULL_REQUEST_TEMPLATE.md
 ├── .qfai
 │   ├── assistant
 │   │   ├── agents
@@ -319,9 +295,22 @@ Typical customizations.
 │   │   │   │   └── SKILL.md
 │   │   │   ├── qfai-discuss
 │   │   │   │   └── SKILL.md
+│   │   │   ├── qfai-prototyping
+│   │   │   │   └── SKILL.md
 │   │   │   ├── qfai-require
 │   │   │   │   └── SKILL.md
-│   │   │   └── ...
+│   │   │   ├── qfai-sdd
+│   │   │   │   └── SKILL.md
+│   │   │   ├── qfai-atdd
+│   │   │   │   └── SKILL.md
+│   │   │   ├── qfai-tdd-red
+│   │   │   │   └── SKILL.md
+│   │   │   ├── qfai-tdd-green
+│   │   │   │   └── SKILL.md
+│   │   │   ├── qfai-tdd-refactor
+│   │   │   │   └── SKILL.md
+│   │   │   └── qfai-verify
+│   │   │       └── SKILL.md
 │   │   ├── skills.local
 │   │   │   └── README.md
 │   │   ├── steering
@@ -352,27 +341,17 @@ Typical customizations.
 │   │   │   ├── 00_Summary.md
 │   │   │   ├── ...
 │   │   │   └── 07_Open-questions.md
-│   │   ├── glossary.md        # legacy compatibility
-│   │   ├── actors.md          # legacy compatibility
-│   │   ├── business-flows.md  # legacy compatibility
-│   │   ├── require.md         # legacy compatibility
-│   │   └── open-questions.md  # legacy compatibility
+│   │   └── README.md
 │   ├── specs
 │   │   └── README.md
 │   └── README.md
 └── qfai.config.yaml
 ```
 
-## Agent integrations (Copilot / Claude Code / Codex)
-
-`npx qfai init` also installs lightweight integration stubs so your AI coding agent can invoke QFAI custom skills directly.
-
-- **GitHub Copilot Agent skills**: `.github/skills/*/SKILL.md`.
-- **GitHub Copilot repository instructions**: `.github/copilot-instructions.md` (baseline behavior guidance for Copilot in this repo).
-- **Claude Code skills**: `.claude/skills/*/SKILL.md`.
-- **OpenAI Codex skills**: `.codex/skills/*/SKILL.md` (invoke as Codex skills; each skill points to the canonical QFAI skill doc).
+## Agent integrations
 
-Each of these files is intentionally thin and forwards to the canonical source of truth under `.qfai/assistant/skills/**`.
+`npx qfai init` installs only canonical skills under `.qfai/assistant/skills/**`.
+If your toolchain needs wrapper files, manage them in your own repository convention and keep `.qfai/assistant/skills/**` as SSOT.
 
 ## Contributing (for QFAI maintainers)
 

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

@@ -31,12 +31,6 @@ flowchart TD
 .qfai/
 ├── README.md
 ├── discuss/
-│   ├── README.md
-│   └── DISCUSS-0001/
-│       ├── 00_Summary.md
-│       ├── ...
-│       └── 07_Open-questions.md
-├── discussions/              # legacy compatibility
 │   └── README.md
 ├── assistant/
 │   ├── skills/               # canonical skills (SSOT)
@@ -45,37 +39,20 @@ flowchart TD
 │   ├── steering/             # project steering inputs
 │   └── instructions/         # workflow and guardrail docs
 ├── require/
-│   ├── README.md
-│   ├── REQUIRE-0001/
-│   │   ├── 00_Summary.md
-│   │   ├── ...
-│   │   └── 07_Open-questions.md
-│   ├── glossary.md           # legacy compatibility
-│   ├── actors.md             # legacy compatibility
-│   ├── business-flows.md     # legacy compatibility
-│   ├── require.md            # legacy compatibility
-│   └── open-questions.md     # legacy compatibility
+│   └── README.md
 ├── contracts/
 │   ├── README.md
 │   ├── api/
-│   │   ├── README.md
-│   │   └── api-0001-sample.yaml
+│   │   └── README.md
 │   ├── db/
-│   │   ├── README.md
-│   │   └── db-0001-sample.sql
+│   │   └── README.md
 │   └── ui/
-│       ├── README.md
-│       └── ui-0001-sample.yaml
+│       └── README.md
 ├── specs/
-│   ├── README.md
-│   └── spec-0001/
-│       ├── 01_Spec.md
-│       ├── 02_Objective.md
-│       ├── ...
-│       ├── 17_Plan.md
-│       └── 18_delta.md
+│   └── README.md
 └── evidence/
     ├── README.md
+    ├── .gitignore
     └── <skill>-<run>.md
 ```
 
@@ -108,10 +85,15 @@ It is useful for local review but should not pollute version control.
 - Traceability links are written in `16_Traceability-ledger.md`.
 - Derived outputs under `.qfai/report/**` are non-SSOT.
 
+### R5. init is an empty scaffold
+
+- `qfai init` creates README-centric directories for `discuss`, `require`, `contracts`, and `specs`.
+- Sample artifacts are provided under skill templates (for example, `assistant/skills/qfai-sdd/templates/contracts/`).
+
 ## Skills (SSOT)
 
 `assistant/skills/**` is the canonical source.
-Tool-specific wrappers (`.claude/skills`, `.github/skills`, `.codex/skills`) should point to this tree.
+Invoke canonical skills from this tree directly.
 
 ## Where to look next
 

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

@@ -10,7 +10,7 @@
 - .qfai/assistant/instructions/\*
 - .qfai/assistant/steering/\*
 - .qfai/specs/spec-\*/delta.md (Decision Records; check rejected)
-- Existing discussion records under `.qfai/discussions/`
+- Existing discussion records under `.qfai/discuss/`
 - .qfai/require/REQUIRE-XXXX/\* (preferred if present)
 - .qfai/require/require.md (legacy compatibility)
 

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

@@ -9,7 +9,7 @@
 - .qfai/assistant/instructions/\*
 - .qfai/assistant/steering/\*
 - .qfai/specs/spec-\*/delta.md (Decision Records; check rejected)
-- Existing discussion records under `.qfai/discussions/`
+- Existing discussion records under `.qfai/discuss/`
 - .qfai/require/REQUIRE-XXXX/\* (preferred if present)
 - .qfai/require/require.md (legacy compatibility)
 

package/assets/init/.qfai/assistant/agents/option-explorer.md

@@ -14,7 +14,7 @@
 - .qfai/specs/spec-\*/spec.md
 - .qfai/specs/spec-\*/delta.md (draft)
 - .qfai/contracts/\*\*
-- Existing discussion records under `.qfai/discussions/`
+- Existing discussion records under `.qfai/discuss/`
 
 ## Deliverables (MANDATORY)
 

package/assets/init/.qfai/assistant/agents/oq-harvester.md

@@ -15,7 +15,7 @@
 - .qfai/specs/spec-\*/spec.md
 - .qfai/specs/spec-\*/delta.md
 - .qfai/contracts/\*\*
-- Existing discussion records under `.qfai/discussions/`
+- Existing discussion records under `.qfai/discuss/`
 
 ## Deliverables (MANDATORY)
 

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

@@ -11,7 +11,7 @@
 - .qfai/specs/spec-\*/delta.md (Decision Records; check rejected)
 - .qfai/require/REQUIRE-XXXX/\* (preferred if present)
 - .qfai/require/require.md (legacy compatibility)
-- Discussion records under `.qfai/discussions/`
+- Discussion records under `.qfai/discuss/`
 - .qfai/specs/spec-\*/spec.md (if available)
 
 ## Deliverables (MANDATORY)

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

@@ -10,7 +10,7 @@
 - .qfai/assistant/steering/\*
 - .qfai/specs/spec-\*/delta.md (Decision Records; check rejected)
 - User-provided idea/problem statement
-- Existing discussion records under `.qfai/discussions/`
+- Existing discussion records under `.qfai/discuss/`
 
 ## Deliverables (MANDATORY)
 

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

@@ -2,7 +2,7 @@
 
 QFAI standardizes work into a fixed pipeline:
 
-**SDD → ATDD → TDD → Implementation → Verification**
+**SDD → ATDD → TDD → Verification**
 
 This file defines the canonical stages and delegation expectations.
 
@@ -50,14 +50,14 @@ Do not proceed without a declared Change Type.
 1. Discussion (optional): clarify idea → requirement seed
 2. Requirements: requirements document in `.qfai/require/`
 3. Specification (SDD): `.qfai/specs/spec-XXXX/`
-4. Scenario tests (ATDD): runnable scenario tests derived from `scenario.feature`
-5. Unit tests (TDD): runnable unit tests enforcing the spec
-6. Implementation: implement to satisfy spec + tests
+4. Prototyping (optional): contract-aligned implementation skeleton
+5. Scenario tests (ATDD): runnable scenario tests derived from `scenario.feature`
+6. TDD: red/green/refactor loop enforcing spec + tests
 7. Verify: run quality gates and provide evidence
 
 ### Stage 0 — Steering refresh contract (mandatory)
 
-At the beginning of each stage (`qfai-discuss`, `qfai-require`, `qfai-sdd`, `qfai-atdd`, `qfai-tdd-*`, `qfai-implement`, `qfai-verify`):
+At the beginning of each stage (`qfai-discuss`, `qfai-require`, `qfai-sdd`, `qfai-prototyping`, `qfai-atdd`, `qfai-tdd-*`, `qfai-verify`):
 
 1. Check these steering files:
    - `.qfai/assistant/steering/manifest.md`

package/assets/init/.qfai/assistant/skills/qfai-atdd/SKILL.md

@@ -692,3 +692,22 @@ When you declare DONE, include:
 - [ ] All mandatory checks were executed and recorded.
 - [ ] No untracked gaps remain (or they are explicitly documented).
 - [ ] Completion approved by a reviewer who did not implement the tests.
+
+## Completion Checklist (MUST)
+
+- [ ] This skill's Definition of Done is satisfied.
+- [ ] Required artifacts were produced or updated (if applicable).
+- [ ] Open questions were logged to the proper OQ file (if applicable).
+- [ ] The completion message was presented to the user.
+- [ ] Next actions were enumerated for all available options.
+
+## Completion Message & Next Actions (MUST)
+
+When this skill is complete, provide a final user-facing completion message and enumerate all actionable next steps.
+
+- Proceed (recommended): `/qfai-tdd-red`.
+  Action: derive unit/component RED tests from acceptance scenarios.
+- Acceptance tests need fixes: rerun `/qfai-atdd`.
+  Action: correct scenario coverage gaps and rerun test evidence.
+- Implementation phase: `/qfai-tdd-green`.
+  Action: implement code to satisfy failing tests.

package/assets/init/.qfai/assistant/skills/qfai-configure/SKILL.md

@@ -452,3 +452,22 @@ When you declare DONE, include:
 - [ ] All mandatory checks were executed and recorded.
 - [ ] No untracked gaps remain (or they are explicitly documented).
 - [ ] Completion approved by a reviewer who did not modify the config.
+
+## Completion Checklist (MUST)
+
+- [ ] This skill's Definition of Done is satisfied.
+- [ ] Required artifacts were produced or updated (if applicable).
+- [ ] Open questions were logged to the proper OQ file (if applicable).
+- [ ] The completion message was presented to the user.
+- [ ] Next actions were enumerated for all available options.
+
+## Completion Message & Next Actions (MUST)
+
+When this skill is complete, provide a final user-facing completion message and enumerate all actionable next steps.
+
+- Proceed (recommended): `/qfai-require`.
+  Action: run it to formalize requirements from the configured project context.
+- Requirements are still unclear: `/qfai-discuss`.
+  Action: collect missing scope, constraints, and assumptions first.
+- Configuration needs refinement: rerun `/qfai-configure`.
+  Action: provide additional include/exclude evidence and update `qfai.config.yaml`.

package/assets/init/.qfai/assistant/skills/qfai-discuss/SKILL.md

@@ -29,7 +29,6 @@ mode: interactive-by-default
   - `.qfai/contracts/**/README.md`
   - `.qfai/evidence/README.md`
 - Keep templates as source of truth; do not invent alternate sections.
-- Legacy path `.qfai/discussions/discuss-XXXX.md` is deprecated.
 
 ## Sub-agent Delegation (MANDATORY)
 
@@ -207,3 +206,27 @@ When done, report:
 - [ ] No lower-layer IDs (`AC/BR/EX/TC`) were written in discuss outputs.
 - [ ] Evidence file exists and includes Work Orders Summary + Reviewer result.
 - [ ] Reviewer returned `PASS`.
+
+## Completion Checklist (MUST)
+
+- [ ] Core interview set is complete.
+- [ ] Optional deep dive was executed only when triggered (or explicitly marked as not needed).
+- [ ] Unresolved items were logged to `07_Open-questions.md`.
+- [ ] Discuss deliverables `00..07` were produced.
+- [ ] The `/qfai-require` handoff sentence was shown as the final line in the user's language.
+
+## Completion Message & Next Actions (MUST)
+
+You MUST end the user-facing output with a handoff sentence to `/qfai-require` in the active user language.
+
+- Japanese output (use this exact sentence):
+  質問が完了しました。他に要望などがあればご提示ください。問題なければ『/qfai-require』と入力してください。
+- Non-Japanese output:
+  Use the same meaning in the user's language, and keep `/qfai-require` as a literal command token.
+
+- Proceed (recommended): `/qfai-require`.
+  Action: run it to convert interview outcomes into structured requirements.
+- Additional requests exist:
+  Action: provide the new requests, assumptions, and constraints as a bullet list.
+- Interview needs correction: rerun `/qfai-discuss`.
+  Action: add missing main flow, branch flow, and exception flow details before rerun.

package/assets/init/.qfai/assistant/skills/qfai-prototyping/SKILL.md

@@ -364,3 +364,22 @@ When you declare DONE, include:
 - [ ] Manual verification log is complete.
 - [ ] No test automation was added.
 - [ ] Completion approved by a reviewer who did not implement the code.
+
+## Completion Checklist (MUST)
+
+- [ ] This skill's Definition of Done is satisfied.
+- [ ] Required artifacts were produced or updated (if applicable).
+- [ ] Open questions were logged to the proper OQ file (if applicable).
+- [ ] The completion message was presented to the user.
+- [ ] Next actions were enumerated for all available options.
+
+## Completion Message & Next Actions (MUST)
+
+When this skill is complete, provide a final user-facing completion message and enumerate all actionable next steps.
+
+- Proceed (recommended): `/qfai-atdd`.
+  Action: create acceptance tests against the prototype behavior.
+- Unit-first alternative: `/qfai-tdd-red`.
+  Action: author failing unit/component tests for critical slices.
+- Prototype behavior is insufficient: rerun `/qfai-prototyping`.
+  Action: refine contract coverage and runtime interaction evidence.

package/assets/init/.qfai/assistant/skills/qfai-require/SKILL.md

@@ -201,3 +201,22 @@ When done, report:
 - [ ] All `TBD` items are mirrored in `07_Open-questions.md`.
 - [ ] Evidence file exists and includes Work Orders Summary + Reviewer result.
 - [ ] Reviewer returned `PASS`.
+
+## Completion Checklist (MUST)
+
+- [ ] This skill's Definition of Done is satisfied.
+- [ ] Required artifacts were produced or updated (if applicable).
+- [ ] Open questions were logged to the proper OQ file (if applicable).
+- [ ] The completion message was presented to the user.
+- [ ] Next actions were enumerated for all available options.
+
+## Completion Message & Next Actions (MUST)
+
+When this skill is complete, provide a final user-facing completion message and enumerate all actionable next steps.
+
+- Proceed (recommended): `/qfai-sdd`.
+  Action: generate the spec pack (`01..18`) from finalized requirements.
+- Upstream assumptions need review: `/qfai-discuss`.
+  Action: revisit unresolved business context and constraints first.
+- Requirement details are incomplete: rerun `/qfai-require`.
+  Action: add missing acceptance criteria, contracts, and OQ updates.

package/assets/init/.qfai/assistant/skills/qfai-sdd/SKILL.md

@@ -161,6 +161,7 @@ Rules:
 - This is the unified SDD skill. Do not split work into deprecated refinement/planning skills.
 - Use only skill-local templates:
   - `.qfai/assistant/skills/qfai-sdd/templates/spec-pack/`
+  - `.qfai/assistant/skills/qfai-sdd/templates/contracts/`
 - Scenario specification in `09_Examples.feature` is strict:
   - exactly one `Feature:`
   - one or more tagged `Scenario:`
@@ -330,3 +331,24 @@ When declaring DONE, include:
 - [ ] Quality gate checks are recorded in evidence.
 - [ ] Evidence file exists and is complete.
 - [ ] Reviewer approval is recorded.
+
+## Completion Checklist (MUST)
+
+- [ ] This skill's Definition of Done is satisfied.
+- [ ] Required artifacts were produced or updated (if applicable).
+- [ ] Open questions were logged to the proper OQ file (if applicable).
+- [ ] The completion message was presented to the user.
+- [ ] Next actions were enumerated for all available options.
+
+## Completion Message & Next Actions (MUST)
+
+When this skill is complete, provide a final user-facing completion message and enumerate all actionable next steps.
+
+- Proceed (recommended): `/qfai-prototyping`.
+  Action: build contract-aligned skeleton implementation before deeper coding.
+- Test-first path: `/qfai-atdd`.
+  Action: implement acceptance tests from the finalized spec pack.
+- Want to add contracts:
+  Action: create files under `.qfai/contracts/(api|db|ui)/` from `templates/contracts/*` and declare `QFAI-CONTRACT-ID`.
+- Spec pack needs correction: rerun `/qfai-sdd`.
+  Action: fix `01..18` consistency and decision records, then regenerate evidence.

package/assets/init/.qfai/assistant/skills/qfai-tdd-green/SKILL.md

@@ -719,3 +719,22 @@ When you declare DONE, include:
 - [ ] All mandatory checks were executed and recorded.
 - [ ] No untracked gaps remain (or they are explicitly documented).
 - [ ] Completion approved by a reviewer who did not implement the code.
+
+## Completion Checklist (MUST)
+
+- [ ] This skill's Definition of Done is satisfied.
+- [ ] Required artifacts were produced or updated (if applicable).
+- [ ] Open questions were logged to the proper OQ file (if applicable).
+- [ ] The completion message was presented to the user.
+- [ ] Next actions were enumerated for all available options.
+
+## Completion Message & Next Actions (MUST)
+
+When this skill is complete, provide a final user-facing completion message and enumerate all actionable next steps.
+
+- Proceed (recommended): `/qfai-tdd-refactor`.
+  Action: refactor safely while keeping all tests green.
+- Additional RED cases are needed: `/qfai-tdd-red`.
+  Action: add missing failing tests before further implementation.
+- Verify gates now: `/qfai-verify`.
+  Action: run format/lint/types/tests and record evidence.

package/assets/init/.qfai/assistant/skills/qfai-tdd-red/SKILL.md

@@ -646,3 +646,22 @@ When you declare DONE, include:
 - [ ] All mandatory checks were executed and recorded.
 - [ ] No untracked gaps remain (or they are explicitly documented).
 - [ ] Completion approved by a reviewer who did not implement the tests.
+
+## Completion Checklist (MUST)
+
+- [ ] This skill's Definition of Done is satisfied.
+- [ ] Required artifacts were produced or updated (if applicable).
+- [ ] Open questions were logged to the proper OQ file (if applicable).
+- [ ] The completion message was presented to the user.
+- [ ] Next actions were enumerated for all available options.
+
+## Completion Message & Next Actions (MUST)
+
+When this skill is complete, provide a final user-facing completion message and enumerate all actionable next steps.
+
+- Proceed (recommended): `/qfai-tdd-green`.
+  Action: implement the minimal production code required to pass tests.
+- RED evidence is insufficient: rerun `/qfai-tdd-red`.
+  Action: strengthen failing-test quality and scope guardrails.
+- Acceptance coverage needs updates: `/qfai-atdd`.
+  Action: align acceptance scenarios before continuing implementation.

package/assets/init/.qfai/assistant/skills/qfai-tdd-refactor/SKILL.md

@@ -644,3 +644,22 @@ When you declare DONE, include:
 - [ ] All mandatory checks were executed and recorded.
 - [ ] No untracked gaps remain (or they are explicitly documented).
 - [ ] Completion approved by a reviewer who did not implement the refactor.
+
+## Completion Checklist (MUST)
+
+- [ ] This skill's Definition of Done is satisfied.
+- [ ] Required artifacts were produced or updated (if applicable).
+- [ ] Open questions were logged to the proper OQ file (if applicable).
+- [ ] The completion message was presented to the user.
+- [ ] Next actions were enumerated for all available options.
+
+## Completion Message & Next Actions (MUST)
+
+When this skill is complete, provide a final user-facing completion message and enumerate all actionable next steps.
+
+- Proceed (recommended): `/qfai-verify`.
+  Action: run all required gates and confirm PASS with evidence.
+- Regression was introduced: `/qfai-tdd-green`.
+  Action: restore behavior and re-pass the failing tests.
+- Refactor scope remains: rerun `/qfai-tdd-refactor`.
+  Action: continue incremental cleanup with gate checks each step.