@multileaf/ai-workflow 0.2.0 → 0.2.1

package/CHANGELOG.md

@@ -4,6 +4,13 @@ All notable changes to this project are documented in this file. The format foll
 
 ## [Unreleased]
 
+## [0.2.1] - 2026-09-13
+
+### Changed
+
+- Require host-native blocking question widgets for onboarding decisions and every SDD approval gate when available, with explicit unselected choices and a safe chat fallback.
+- Clarify that the CLI persists approval state but cannot prove that a host widget was used or verify respondent identity.
+
 ## [0.2.0] - 2026-09-13
 
 ### Added

package/README.md

@@ -230,7 +230,7 @@ npx @multileaf/ai-workflow approve traceability
 npx @multileaf/ai-workflow workflow complete
 ```
 
-Scaffold commands write deterministic files at fixed paths and a repeated invocation replaces that scaffold. Each applicable workflow stage requires two separate checks: its automated quality gate (when available), then explicit human approval. After presenting the artifact or evidence, the agent must stop and wait for the human before invoking the next skill, command, scaffold, or implementation action. A passing `aiw gate` validates artifact completeness only; it never records or implies human approval. Requirements use stable identifiers and Given/When/Then acceptance criteria. Plans link tasks to requirements, tests, risks, dependencies, and expected evidence. `verify` checks that the specification has acceptance criteria and the plan links requirements to validation; it does not execute project test commands. `trace` records declared links between requirements, decisions, tasks, code, tests, and evidence. Code review is performed with the `code-review` skill when installed; there is no separate review gate command, but the human must accept the review outcome before completion.
+Scaffold commands write deterministic files at fixed paths and a repeated invocation replaces that scaffold. Each applicable workflow stage requires two separate checks: its automated quality gate (when available), then explicit human approval. When the host provides a blocking question widget, the agent must use it with unselected approve, request-changes, and reject choices; it must wait for an actual submission before invoking the next skill, command, scaffold, or implementation action. A numbered chat prompt is only the fallback when no blocking widget exists. A passing `aiw gate` validates artifact completeness only; it never records or implies human approval. Requirements use stable identifiers and Given/When/Then acceptance criteria. Plans link tasks to requirements, tests, risks, dependencies, and expected evidence. `verify` checks that the specification has acceptance criteria and the plan links requirements to validation; it does not execute project test commands. `trace` records declared links between requirements, decisions, tasks, code, tests, and evidence. Code review is performed with the `code-review` skill when installed; there is no separate review gate command, but the human must accept the review outcome before completion.
 
 ## Project intelligence
 

package/dist/adapter.js

@@ -42,14 +42,16 @@ This skill is the bootstrap for AI Workflow. The installer intentionally install
 
 ### Mandatory interaction checkpoints
 
-This setup is gated by explicit user replies. A question is a blocking checkpoint, not narration: ask it, end your current response/turn immediately, and do no further analysis, tool calls, commands, or file changes until the user replies in a later turn. Never answer your own question, infer an answer from silence, or continue because a widget has a preselected value. If the host cannot pause for an answer, stop and ask the user to continue the setup after replying.
+This setup is gated by explicit user replies. At every human decision, call the host's native blocking question widget/tool; do not replace it with a prose question when the widget is available. Use the selection widget for multi-select decisions. Leave every choice unselected by default. Do not continue, call tools, run commands, or change files while a widget is awaiting submission. Only its actual submitted response is consent; never answer your own question or infer consent from silence, ambiguity, cancellation, or a preselected value. If the host has no blocking question widget, ask one concise numbered question in chat, end the turn, and wait for an explicit reply in a later turn. This is an interaction requirement for the agent; the AI Workflow CLI cannot independently verify which UI produced an approval.
 
-1. Before scanning, recommend that the user switch to a cheaper model. Ask whether they switched or explicitly want to continue with the current model; never change model settings yourself. Explain that analysis is read-only and optional resources will not be installed without their selection. Then stop the turn and wait. Do not launch analysis agents or run \`aiw scan\` until the user replies. If the reply is unclear, ask again and stop; proceed only after an explicit answer to continue (including an explicit choice to keep the current model).
+Use that widget for the model choice, confirmation of uncertain scan findings, all/custom/none recommendation selection, approval of the exact sync preview, external network or remote-skill consent, and each separate MCP configuration/execution/credential permission. For a single decision, offer explicit choices with no default; for “request changes,” “correct this finding,” or “other,” collect the user's free-text details in a follow-up widget before acting.
+
+1. Before scanning, recommend that the user switch to a cheaper model. Use a blocking question widget with no default choice to offer “I switched; continue”, “Keep this model; continue”, or “Stop setup”; never change model settings yourself. Explain that analysis is read-only and optional resources will not be installed without their selection. Wait for and evaluate the widget’s explicit response. Do not launch analysis agents or run \`aiw scan\` until the widget returns an explicit continue choice. If the widget is dismissed or the reply is unclear, ask again with the widget and stop; proceed only after an explicit answer to continue (including an explicit choice to keep the current model).
 2. Use the host's native subagent mechanism to launch these read-only analyses in parallel: (a) technologies, root and nested manifests, workspaces, and monorepo boundaries; (b) architecture, modules, entry points, and recurring code patterns; (c) tests, quality commands, CI, and developer tools. Keep the main agent as orchestrator. Wait for all results, verify important claims against cited project files, reconcile disagreements, and consolidate one evidence-backed project profile. Do not inspect secrets, ignored files, dependency directories such as \`node_modules\`, or generated output; inspect declared dependencies in project manifests. If subagents are unavailable, perform the same analyses directly and disclose the fallback.
 3. Run \`npx --yes --package=@multileaf/ai-workflow -- aiw scan\` and read \`.aiw/profile.yml\`. Treat this deterministic scan as another evidence source, not as a replacement for workspace-level analysis. Summarize each workspace separately; do not assume root dependencies or commands apply to every module. Ask the user to confirm uncertain or conflicting facts before using them as project policy. Add confirmed architecture and recurring patterns to the matching entries in the \`project_modules\` JSON array in \`.aiw/profile.yml\`, including file-path evidence; create a root-level entry when only the root project exists. Preserve existing detected fields and never store secrets or source-code excerpts there.
 4. Run \`npx --yes --package=@multileaf/ai-workflow -- aiw recommend\` and read \`.aiw/recommendations.yml\`. Combine catalog results with the consolidated project profile. Recommend matching skills, rules, agents, hooks, templates, and MCP servers. For every MCP, disclose its publisher/source, purpose, capabilities, permissions, transport, and credential needs; verify them against current official host and server documentation. Recommend only integrations supported by project evidence and never invent credentials.
 5. Present recommendations as concise tables grouped by category: skills, rules, agents, hooks, templates, and MCPs. Include one row per recommended item and columns for the item, a short project-specific reason for the recommendation, and relevant evidence. For MCP rows, also summarize purpose, source, permissions, transport, and credential needs (use a separate table if needed). Do not show a flat list without category headings or generic reasons such as “useful for this project.” After the tables, use the host's native selection widget to offer three explicit choices: install all recommendations, customize, or install none. The widget must start with no choice selected; never accept a default or preselected value as the user's answer. If the user customizes, show selectable category blocks and individual items, keeping each item's short reason and declared prerequisites visible. Read \`requires\` from \`.aiw/recommendations.yml\`; explain that choosing a stage auto-selects its prerequisite capabilities and their resources. If the host lacks a multi-select widget, ask a numbered all/custom/none question and stop the turn to wait for the reply. Do not run a selection command or install anything until a reply/explicit widget submission arrives in a later turn. A dismissed widget, empty answer, silence, or ambiguous answer means no consent; ask again or stop without installing. MCP selection does not grant permission to execute the server or use external access; ask separately for those permissions.
-6. Only after receiving the user's explicit all/custom/none choice, record it: use \`npx --yes --package=@multileaf/ai-workflow -- aiw recommend --select=all\` for an explicit all choice; for customized item-level choices, pass only the selected resource references such as \`skills/verification,rules/tdd-policy,agents/test-engineer\`; use \`npx --yes --package=@multileaf/ai-workflow -- aiw recommend --select=\` for an explicit none choice. Before syncing a non-empty selection, show the exact selected resources and their prerequisites. Run \`npx --yes --package=@multileaf/ai-workflow -- aiw sync --preview\` and show the complete plan, including additions, updates, preserved files, conflicts, and any external permissions. Ask the user to approve this exact plan and stop the turn. Run sync only after that confirmation arrives in a later turn. Only after a later explicit approval, rerun preview if selection or project files changed, then run \`npx --yes --package=@multileaf/ai-workflow -- aiw sync --approve-plan=<fingerprint>\` using the fingerprint from the approved preview. A changed plan or conflict must stop without writes. Remote skills are not installed by sync: ask separately for network access and installation approval, then use \`npx --yes --package=@multileaf/ai-workflow -- aiw skills install --source=vercel-labs/agent-skills --skill=vercel-react-best-practices --allow=network:external\`. MCP configuration, server execution, and credentials each require separate consent. Install only confirmed selected resources and declared dependencies. Tailor instructions only where project evidence changes their usefulness (such as test commands, workspace boundaries, framework patterns, or module architecture). Preserve existing files, configuration, and secrets; report conflicts rather than overwriting them.
+6. Only after receiving the user's explicit all/custom/none choice, record it: use \`npx --yes --package=@multileaf/ai-workflow -- aiw recommend --select=all\` for an explicit all choice; for customized item-level choices, pass only the selected resource references such as \`skills/verification,rules/tdd-policy,agents/test-engineer\`; use \`npx --yes --package=@multileaf/ai-workflow -- aiw recommend --select=\` for an explicit none choice. Before syncing a non-empty selection, show the exact selected resources and their prerequisites. Run \`npx --yes --package=@multileaf/ai-workflow -- aiw sync --preview\` and show the complete plan, including additions, updates, preserved files, conflicts, and any external permissions. Use the blocking question widget to approve this exact plan, request changes, or cancel. Run sync only after that confirmation arrives from an explicit widget submission. Only after a later explicit approval, rerun preview if selection or project files changed, then run \`npx --yes --package=@multileaf/ai-workflow -- aiw sync --approve-plan=<fingerprint>\` using the fingerprint from the approved preview. A changed plan or conflict must stop without writes. Remote skills are not installed by sync: ask separately for network access and installation approval, then use \`npx --yes --package=@multileaf/ai-workflow -- aiw skills install --source=vercel-labs/agent-skills --skill=vercel-react-best-practices --allow=network:external\`. MCP configuration, server execution, and credentials each require separate consent. Install only confirmed selected resources and declared dependencies. Tailor instructions only where project evidence changes their usefulness (such as test commands, workspace boundaries, framework patterns, or module architecture). Preserve existing files, configuration, and secrets; report conflicts rather than overwriting them.
 7. For selected MCPs, add only the selected servers to the host's supported project configuration. Check current official host and server documentation for the configuration format, merge existing settings without replacing unrelated entries, and use environment-variable references instead of literal credentials. Do not run server install/start/authentication commands without separate approval. If the target requires user-level changes or safe configuration cannot be validated, give the user exact manual steps and report the MCP as pending rather than installed.
 8. Report installed resources by block, project-specific changes, skipped recommendations, MCP trust/authentication steps, and conflicts. Recommend restarting or reloading the coding-agent session so it discovers newly installed resources; follow known host behavior if it reloads changes automatically. Introduce only the gates supported by installed resources: brainstorming → specification → architecture decision when needed → implementation plan → implementation with tests → verification → code review → traceability.
 
@@ -59,7 +61,9 @@ If the user declines all recommendations, leave the project with only the bootst
 
 ### Mandatory human gates between stages
 
-For every CLI command below, use \`npx --yes --package=@multileaf/ai-workflow -- aiw <command>\`; do not assume a global \`aiw\` binary exists. Start each feature request with \`npx --yes --package=@multileaf/ai-workflow -- aiw workflow start\` and check progress with \`npx --yes --package=@multileaf/ai-workflow -- aiw workflow status\`. Complete it with \`npx --yes --package=@multileaf/ai-workflow -- aiw workflow complete\` only after all stages resolve. The \`aiw gate <stage>\` command checks evidence and records a pending review; a passing result is not human approval. At every stage boundary—brainstorming, specification, technical design, plan, implementation, verification, code review, and traceability—present the exact artifact/evidence, ask whether the user approves proceeding, end the turn, and wait for an explicit reply in a later turn. On approval, record it with \`npx --yes --package=@multileaf/ai-workflow -- aiw approve <stage>\`; if the user asks for changes, record the rejection first with \`npx --yes --package=@multileaf/ai-workflow -- aiw reject <stage> --reason=<feedback>\`, then revise and rerun the gate. Do not invoke the next skill, create its scaffold, run its commands, or edit its artifacts before approval is recorded or the pending stage is rejected. Silence, an ambiguous reply, an automated gate pass, or earlier approval never counts. Brainstorming and technical design may be skipped only after explaining why and receiving explicit human acceptance; record each skip with \`npx --yes --package=@multileaf/ai-workflow -- aiw skip <stage> --reason=<accepted reason>\`.
+At every stage gate, use the host's native blocking question widget and present the exact evidence with these unselected choices: “Approve and continue”, “Request changes”, and “Reject/stop”. For optional brainstorming or technical-design skips, use a separate widget with “Accept this skip” and “Do not skip”; collect the reason before recording an accepted skip. Do not run \`aiw approve\`, \`aiw reject\`, or \`aiw skip\` until the relevant widget has returned an explicit submission. A request for changes must collect the feedback in a follow-up question widget, record rejection, then revise and rerun the gate. If no blocking question widget exists, use a numbered chat prompt and end the turn until an explicit reply arrives. A widget submission is the agent's required interaction signal; the CLI cannot prove the widget was used.
+
+For every CLI command below, use \`npx --yes --package=@multileaf/ai-workflow -- aiw <command>\`; do not assume a global \`aiw\` binary exists. Start each feature request with \`npx --yes --package=@multileaf/ai-workflow -- aiw workflow start\` and check progress with \`npx --yes --package=@multileaf/ai-workflow -- aiw workflow status\`. Complete it with \`npx --yes --package=@multileaf/ai-workflow -- aiw workflow complete\` only after all stages resolve. The \`aiw gate <stage>\` command checks evidence and records a pending review; a passing result is not human approval. At every stage boundary—brainstorming, specification, technical design, plan, implementation, verification, code review, and traceability—present the exact artifact/evidence, ask using the blocking question widget and wait for its explicit submission before proceeding; end the turn only when the widget is unavailable. On approval, record it with \`npx --yes --package=@multileaf/ai-workflow -- aiw approve <stage>\`; if the user asks for changes, record the rejection first with \`npx --yes --package=@multileaf/ai-workflow -- aiw reject <stage> --reason=<feedback>\`, then revise and rerun the gate. Do not invoke the next skill, create its scaffold, run its commands, or edit its artifacts before approval is recorded or the pending stage is rejected. Silence, an ambiguous reply, an automated gate pass, or earlier approval never counts. Brainstorming and technical design may be skipped only after explaining why and receiving explicit human acceptance; record each skip with \`npx --yes --package=@multileaf/ai-workflow -- aiw skip <stage> --reason=<accepted reason>\`.
 
 - Use the brainstorming skill when scope, users, constraints, or assumptions are unclear; create its artifact with \`npx --yes --package=@multileaf/ai-workflow -- aiw brainstorm\`, validate it with \`npx --yes --package=@multileaf/ai-workflow -- aiw gate brainstorming\`, present it, wait, then record the reply with \`npx --yes --package=@multileaf/ai-workflow -- aiw approve brainstorming\` before specification. If unnecessary, ask to skip and record explicit acceptance with \`npx --yes --package=@multileaf/ai-workflow -- aiw skip brainstorming --reason=...\`.
 - Create a specification with stable requirement IDs and Given/When/Then acceptance criteria; pass \`npx --yes --package=@multileaf/ai-workflow -- aiw gate specification\`, present it, wait, and record approval before design or planning.

package/docs/ai-init-workflow-spec.md

@@ -6,13 +6,13 @@ Make `/ai-init` a guided, evidence-backed onboarding flow. The initial `npx` ins
 
 ## User flow
 
-1. **Model and consent.** Before repository analysis, recommend switching to a lower-cost model. Do not change model settings. Ask whether the user switched or explicitly wants to continue with the current model. End the agent turn after asking and wait for a reply before scanning, launching subagents, or calling tools. Silence, ambiguity, or a preselected widget value is not consent.
+1. **Model and consent.** Before repository analysis, recommend switching to a lower-cost model. Do not change model settings. Use the host's native blocking question widget, with no preselected value, to ask whether the user switched, wants to continue with the current model, or wants to stop. Do not scan or launch subagents until the widget has an explicit continue response. Silence, ambiguity, dismissal, or a default value is not consent.
 2. **Parallel project analysis.** Use the host's native subagent mechanism to start independent read-only scans in parallel. Assign separate work to (a) technologies and package/workspace topology, (b) architecture, modules, and code patterns, and (c) tests, quality tools, and CI. The initiating agent is the orchestrator: it consolidates findings, resolves conflicts using repository evidence, and records paths for every material conclusion. If the host cannot start subagents, do the same scans directly and say so.
 3. **Monorepo coverage.** Discover root and nested project manifests, workspace definitions, package boundaries, framework configs, tests, and module entry points. Analyze each workspace separately, then summarize shared tooling and cross-workspace relationships. Never infer that root dependencies apply to every workspace.
-4. **Scan record.** Run the deterministic AI Workflow scan and combine it with the parallel analysis. Present technologies, architecture, patterns, modules, tests, quality commands, workspace topology, confidence, and source evidence. Do not include secret values. Ask for confirmation where conflicting or uncertain findings would affect installed guidance.
+4. **Scan record.** Run the deterministic AI Workflow scan and combine it with the parallel analysis. Present technologies, architecture, patterns, modules, tests, quality commands, workspace topology, confidence, and source evidence. Do not include secret values. Use the native blocking question widget to confirm, correct, or leave unresolved any conflicting or uncertain finding that would affect installed guidance.
 5. **Recommendations.** Match catalog capabilities to the consolidated project profile. Show concise tables grouped by resource category (skills, rules, agents, hooks, templates, and MCPs), with one row per item and a short, project-specific reason plus supporting evidence. Include resource types, required permissions, and project-specific configuration steps where relevant. Recommend an MCP only when repository evidence supports its use; disclose its publisher/source, capabilities, access, transport, and credential needs. Never invent credentials or silently enable an MCP.
 6. **Selection.** After the recommendation tables, use the coding host's native selection widget when it supports one. First offer: install all recommendations, customize, or install none. No option may be preselected or inferred. Wait for an explicit submission; a dismissed widget, blank response, silence, or ambiguity must stop progress without selecting or installing anything. For customization, show selectable blocks grouped by resource type, then the individual recommended items in each selected block; retain each item's concise reason and evidence in the selection details. Include MCPs as a separate block. Keep dependencies visible and select required dependencies together. If the host has no selection widget, ask an equivalent numbered prompt, end the turn, and wait for an explicit all/custom/none reply.
-7. **Install and personalize.** After an explicit non-empty selection, show the exact resources and prerequisite capabilities that will be installed, ask for confirmation, end the turn, and wait. Install only after that confirmation arrives in a later turn. For “all”, install every recommendation that does not require an unapproved external permission. A missing external permission must not block independent bundled resources; report the external item as pending and give the user the exact retry command. For custom selection, install only selected items and their declared dependencies. Personalize resources only when project evidence materially changes their instructions (for example, test commands, workspace/module layout, framework patterns, or architectural boundaries). Preserve existing files and secrets; report conflicts rather than overwriting. MCP setup must use the selected host's supported project-level configuration, preserve existing configuration, use environment-variable references for secrets, and request separate approval for permissions or external execution.
+7. **Install and personalize.** After an explicit non-empty selection, show the exact resources and prerequisite capabilities that will be installed. Use the native blocking question widget with no default choice to approve the exact preview, request changes, or cancel. Do not sync while the widget is unanswered. For “all”, install every recommendation that does not require an unapproved external permission. A missing external permission must not block independent bundled resources; report the external item as pending and give the user the exact retry command. For custom selection, install only selected items and their declared dependencies. Personalize resources only when project evidence materially changes their instructions (for example, test commands, workspace/module layout, framework patterns, or architectural boundaries). Preserve existing files and secrets; report conflicts rather than overwriting. Use separate blocking question widgets to authorize MCP configuration, server execution, external access, and credentials; never combine these permissions.
 8. **Completion.** Report installed resources by block, project-specific changes, skipped recommendations, conflicts, MCP authentication/trust steps, and validation performed. Recommend restarting/reloading the coding-agent session so newly installed resources are discovered. Do not claim a restart is required when the host loads changes immediately; distinguish host behavior where known.
 
 ## Safety and compatibility
@@ -23,6 +23,7 @@ Make `/ai-init` a guided, evidence-backed onboarding flow. The initial `npx` ins
 - Selection and external permissions are separate decisions. Selecting an MCP is not permission to execute it or to expose credentials.
 - Resource writes use target adapters, ownership tracking, safe paths, atomic updates, and conflict reporting.
 - Host-specific capabilities (subagents, selection widgets, MCP configuration, restart semantics) are detected or described accurately; provide a safe manual fallback where unavailable.
+- Every human decision uses the host's native blocking question widget when available, with no default choice; a prose prompt is permitted only as a documented fallback when the host has no blocking widget.
 
 ## Acceptance criteria
 
@@ -39,9 +40,10 @@ Make `/ai-init` a guided, evidence-backed onboarding flow. The initial `npx` ins
 - **AIINIT-010:** CLI tests cover mixed-stack monorepos, all/custom/none selection, permission gating, MCP config merging, personalization, conflicts, and completion output.
 - **AIINIT-011:** Custom selections can choose individual resource references by block, while `--select=all` selects every recommended capability and `--select=` selects none.
 - **AIINIT-013:** Sync previews exact additions, updates, preserved files, conflicts, and external permissions without writing; apply is bound to the approved plan fingerprint and is transactional. External skills and MCP actions require separate approvals, so network denial cannot partially apply local resources.
-- **AIINIT-014:** The bootstrap pauses the agent turn at the model choice, recommendation selection, and final install confirmation; no scan or install proceeds from silence, ambiguity, cancellation, or a default/preselected choice.
-- **AIINIT-015:** Every applicable SDD stage has a mandatory human approval checkpoint before the next stage; automated quality gates are explicitly distinct from human approval, and the agent must stop the turn until an explicit decision arrives.
+- **AIINIT-014:** The bootstrap uses a blocking question widget for model choice, uncertain scan facts, recommendation selection, and final install confirmation; no scan or install proceeds from silence, ambiguity, cancellation, or a default/preselected choice.
+- **AIINIT-015:** Every applicable SDD stage has a mandatory human approval checkpoint before the next stage; the agent uses the native blocking question widget with explicit approve/request-changes/reject choices, and automated quality gates remain distinct from human approval.
 - **AIINIT-016:** A versioned per-workflow approval ledger binds each human decision to the exact evidence fingerprint, blocks out-of-order commands, invalidates downstream approvals when evidence changes, and explains the next action in workflow status.
+- **AIINIT-017:** Every human checkpoint uses the host's native blocking question widget when available, leaves choices unselected, and acts only after an explicit submission. If unavailable, the agent uses a numbered chat prompt and waits for a later explicit reply. The CLI must describe that it cannot independently prove which UI produced an approval.
 
 ## Delivery slices
 

package/docs/architecture.md

@@ -47,7 +47,7 @@ Project analysis is hybrid: deterministic detectors establish observable facts,
 
 The SDD approval contract models the ordered stages brainstorming, specification, technical design, plan, implementation, verification, review, and traceability. Brainstorming and technical design are optional; skipping either requires a human-accepted reason. Every other stage must be approved. Automated quality-gate results are stored separately from human decisions and can only move an artifact to pending review, never directly to approved.
 
-Each approval is scoped to one workflow ID and bound to a SHA-256 fingerprint of the exact artifact reviewed, so a later feature cannot reuse earlier approvals. A content change or rejection makes that stage and its descendants stale. The CLI persists the versioned ledger in `.aiw/approvals.yml`, blocks stage commands when prerequisites are unresolved, and keeps passing quality gates distinct from human approval. Approval records provide an audit trail but cannot prove the identity of a person who responded in a host conversation.
+Each approval is scoped to one workflow ID and bound to a SHA-256 fingerprint of the exact artifact reviewed, so a later feature cannot reuse earlier approvals. A content change or rejection makes that stage and its descendants stale. The CLI persists the versioned ledger in `.aiw/approvals.yml`, blocks stage commands when prerequisites are unresolved, and keeps passing quality gates distinct from human approval. The generated bootstrap and stage skills require the host's native blocking question widget for human decisions when available, with a waiting chat prompt as fallback. Approval records provide an audit trail but cannot prove the identity of a respondent or independently verify that the host widget was used.
 
 Every stage has a stable evidence path and an automated completeness gate. Design, implementation, review, and traceability use explicit report templates; a passing completeness check still leaves the stage pending until a human accepts the exact evidence.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@multileaf/ai-workflow",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "description": "Portable spec-driven development workflow for AI coding agents",
   "license": "MIT",
   "repository": {

package/resources/skills/brainstorming.md

@@ -5,6 +5,8 @@ description: Turn an early product idea into structured goals, assumptions, cons
 
 # Brainstorming
 
+For every approval or optional skip, use the host's native blocking question widget, not a prose-only prompt when the widget is available. Leave choices unselected and offer “Approve and continue”, “Request changes”, and “Reject/stop”; for a skip, offer “Accept skip” or “Do not skip”. Wait for an actual submission before running `aiw approve`, `aiw reject`, or `aiw skip` or proceeding. Collect revision/skip reasons in a follow-up free-text widget. If the host has no blocking widget, use a numbered chat prompt and end the turn until an explicit reply arrives. The CLI records the decision but cannot verify that a widget was used.
+
 Separate facts, hypotheses, decisions, and open questions. Identify users, desired outcomes, constraints, risks, and non-goals. Do not prematurely prescribe implementation. Produce a versioned brainstorm artifact in English.
 
 Start an AI Workflow session for each feature with `npx --yes --package=@multileaf/ai-workflow -- aiw workflow start` unless one is already active. When the request is already clear, explain why brainstorming can be skipped, ask the human to accept the skip, stop, and record only an explicit acceptance with `aiw skip brainstorming --reason=<accepted reason>`. Otherwise create `.aiw/generated/specs/brainstorm.md`, run `aiw gate brainstorming`, present the exact artifact and a concise summary, and ask whether to proceed to requirements. Stop the turn and wait. Only after an explicit approval, record it with `aiw approve brainstorming`; do not start or scaffold requirements before that command succeeds. If changes are requested, first record `aiw reject brainstorming --reason=<feedback>`, then revise the artifact, rerun its gate, and ask again. Use `npx --yes --package=@multileaf/ai-workflow -- aiw <command>` when no global CLI is available.

package/resources/skills/code-review.md

@@ -5,6 +5,8 @@ description: Review code for correctness, maintainability, design quality, and r
 
 # Code Review
 
+For every approval, rejection, or optional skip, use the host's native blocking question widget, not a prose-only prompt when the widget is available. Leave choices unselected and offer “Approve and continue”, “Request changes”, and “Reject/stop”; for a skip, offer “Accept skip” or “Do not skip”. Wait for an actual submission before running `aiw approve`, `aiw reject`, or `aiw skip` or proceeding. Collect revision/skip reasons in a follow-up free-text widget. If the host has no blocking widget, use a numbered chat prompt and end the turn until an explicit reply arrives. The CLI records the decision but cannot verify that a widget was used.
+
 Review behavior, boundaries, cohesion, naming, types, error handling, duplication, complexity, tests, and documentation. Prioritize actionable findings with severity and evidence.
 
 Write `.aiw/generated/reports/code-review.md` with the scope, findings (including an explicit `None` when clear), checks, residual risks, and decision. Run `aiw gate review`, present the exact report, and ask whether to address findings or accept the residual risk. Stop and wait for an explicit decision. Only after approval, record it with `aiw approve review`; do not start traceability before it succeeds. If changes are requested, first record `aiw reject review --reason=<feedback>`, return to implementation, and require verification and review again. Review completeness is an automated gate; it does not replace human approval. Invoke commands through `npx --yes --package=@multileaf/ai-workflow -- aiw <command>` when no global binary exists.

package/resources/skills/implementation-planning.md

@@ -5,6 +5,8 @@ description: Break an approved design into independently verifiable implementati
 
 # Implementation Planning
 
+For every approval, rejection, or optional skip, use the host's native blocking question widget, not a prose-only prompt when the widget is available. Leave choices unselected and offer “Approve and continue”, “Request changes”, and “Reject/stop”; for a skip, offer “Accept skip” or “Do not skip”. Wait for an actual submission before running `aiw approve`, `aiw reject`, or `aiw skip` or proceeding. Collect revision/skip reasons in a follow-up free-text widget. If the host has no blocking widget, use a numbered chat prompt and end the turn until an explicit reply arrives. The CLI records the decision but cannot verify that a widget was used.
+
 Create small ordered tasks. Each task must reference requirements, affected modules, tests, commands, dependencies, and completion evidence.
 
 Write `.aiw/generated/plans/implementation-plan.md` with ordered tasks, requirement links, affected modules, tests, validation, dependencies, risks, and completion evidence. After `aiw gate plan` passes, present the exact plan to the human and ask for explicit approval. Stop and wait; a gate pass is not approval. Do not edit implementation files until approval arrives and `aiw approve plan` succeeds. If changes are requested, first record `aiw reject plan --reason=<feedback>`, then revise the plan, rerun its gate, and ask again. After approval, implement in task order. Use `tdd-development` when installed and the project has a test workflow; otherwise use existing validation. When implementation is complete, write `.aiw/generated/reports/implementation-report.md` with changed files, tests, validation results, and deviations; run `aiw gate implementation`, present the diff and evidence to the human, stop, and wait for explicit approval. Record approval with `aiw approve implementation` before verification. Invoke CLI commands through `npx --yes --package=@multileaf/ai-workflow -- aiw <command>` when no global binary exists.

package/resources/skills/project-init.md

@@ -5,4 +5,6 @@ description: Inspect a repository, build a project profile, and prepare AI Workf
 
 # Project Initialization
 
+Use the host's native blocking question widget for uncertain project facts and setup decisions when available. Leave choices unselected; offer to confirm the evidence, correct it, or leave it unresolved. Do not make an uncertain inference project policy until the widget is explicitly submitted. If the host has no blocking widget, ask one numbered question in chat and wait for an explicit response before proceeding.
+
 Inspect structure and configuration safely. Detect languages, frameworks, package managers, scripts, tests, quality tools, CI, and conventions. Record evidence and confidence in `.aiw/profile.yml`. Ask for confirmation before treating uncertain inferences as facts. Recommend capabilities with rationale, permissions, and conflicts.

package/resources/skills/requirements-specification.md

@@ -5,6 +5,8 @@ description: Convert a product idea into testable, traceable requirements.
 
 # Requirements Specification
 
+For every approval, rejection, or optional skip, use the host's native blocking question widget, not a prose-only prompt when the widget is available. Leave choices unselected and offer “Approve and continue”, “Request changes”, and “Reject/stop”; for a skip, offer “Accept skip” or “Do not skip”. Wait for an actual submission before running `aiw approve`, `aiw reject`, or `aiw skip` or proceeding. Collect revision/skip reasons in a follow-up free-text widget. If the host has no blocking widget, use a numbered chat prompt and end the turn until an explicit reply arrives. The CLI records the decision but cannot verify that a widget was used.
+
 Give each requirement a stable identifier. Define observable behavior, acceptance criteria, constraints, and unresolved questions. Link requirements to their source brainstorm and distinguish confirmed facts from assumptions. Do not approve ambiguous critical requirements.
 
 Create `.aiw/generated/specs/specification.md` and run `aiw gate specification`. Present the exact requirements and unresolved questions to the human and ask for explicit approval. Stop the turn and wait; a passing gate is not approval. Only after approval, run `aiw approve specification`; do not create design or plan artifacts before it succeeds. If changes are requested, first record `aiw reject specification --reason=<feedback>`, then revise the specification, rerun its gate, and ask again. After approval, use `technical-design` when the change affects architecture or has consequential design choices. Otherwise explain why design can be skipped, ask the human to accept, stop, and record an explicit acceptance with `aiw skip technical-design --reason=<accepted reason>` before planning. Invoke commands through `npx --yes --package=@multileaf/ai-workflow -- aiw <command>` if `aiw` is not installed globally.

package/resources/skills/tdd-development.md

@@ -5,6 +5,8 @@ description: Implement repository changes through test-first development.
 
 # TDD Development
 
+For implementation approval or rejection, use the host's native blocking question widget, not a prose-only prompt when the widget is available. Leave choices unselected and offer “Approve and continue”, “Request changes”, and “Reject/stop”. Wait for an actual submission before running `aiw approve` or `aiw reject` or starting verification. Collect requested changes in a follow-up free-text widget. If the host has no blocking widget, use a numbered chat prompt and end the turn until an explicit reply arrives. The CLI records the decision but cannot verify that a widget was used.
+
 Follow Red, Green, Refactor, Verify. Write a failing behavioral test first, implement the smallest change, refactor for clarity and design quality, then run the relevant quality gate. Never weaken a test to make an implementation pass.
 
 After implementation tasks are green and refactored, write `.aiw/generated/reports/implementation-report.md` with changed files, tests, validation results, and deviations. Run `aiw gate implementation`, present the diff, changed requirements, test commands, and exact evidence to the human. Ask for explicit approval to proceed to verification, end the turn, and wait. Do not invoke verification until the human approves and `aiw approve implementation` succeeds. If changes are requested, first record `aiw reject implementation --reason=<feedback>`, remain in implementation, repeat relevant tests, update the report, rerun its gate, and ask again. Invoke CLI commands through `npx --yes --package=@multileaf/ai-workflow -- aiw <command>` when no global binary exists.

package/resources/skills/technical-design.md

@@ -5,6 +5,8 @@ description: Design modular technical solutions from approved requirements.
 
 # Technical Design
 
+For every approval, rejection, or optional skip, use the host's native blocking question widget, not a prose-only prompt when the widget is available. Leave choices unselected and offer “Approve and continue”, “Request changes”, and “Reject/stop”; for a skip, offer “Accept skip” or “Do not skip”. Wait for an actual submission before running `aiw approve`, `aiw reject`, or `aiw skip` or proceeding. Collect revision/skip reasons in a follow-up free-text widget. If the host has no blocking widget, use a numbered chat prompt and end the turn until an explicit reply arrives. The CLI records the decision but cannot verify that a widget was used.
+
 Map requirements to components, interfaces, data flows, and validation strategy. Compare meaningful alternatives and record decisions with rationale, risks, and consequences. Prefer small cohesive modules, explicit contracts, dependency inversion, and reversible changes.
 
 Write the reviewable design to `.aiw/generated/reports/technical-design.md` using the technical-design template. Link each design and ADR to affected requirements. Run `aiw gate technical-design`, present the exact design and decisions to the human, and ask for explicit approval. Stop and wait; do not create an implementation plan until approval arrives. Only after approval, record it with `aiw approve technical-design`. If changes are requested, first record `aiw reject technical-design --reason=<feedback>`, then revise the design/ADRs, rerun the gate, and ask again. If no technical design is needed, obtain explicit human acceptance and record `aiw skip technical-design --reason=<accepted reason>`. Use `npx --yes --package=@multileaf/ai-workflow -- aiw <command>` when no global CLI is available.

package/resources/skills/verification.md

@@ -5,6 +5,8 @@ description: Verify implementation against requirements and produce traceable ev
 
 # Verification
 
+For every approval or rejection, use the host's native blocking question widget, not a prose-only prompt when the widget is available. Leave choices unselected and offer “Approve and continue”, “Request changes”, and “Reject/stop”. Wait for an actual submission before running `aiw approve` or `aiw reject` or proceeding to the next stage. Collect requested changes in a follow-up free-text widget. If the host has no blocking widget, use a numbered chat prompt and end the turn until an explicit reply arrives. The CLI records the decision but cannot verify that a widget was used.
+
 Check every acceptance criterion, quality gate, security requirement, and affected adapter. Report passed checks, missing evidence, failures, and residual risks. A task is not complete when required evidence is missing.
 
 Write `.aiw/generated/reports/verification-report.md` using the verification-report template and validate it with `npx --yes --package=@multileaf/ai-workflow -- aiw gate verification`. Present the exact report, checks, missing evidence, and residual risks to the human. Ask for explicit approval to proceed, end the turn, and wait; an automated gate pass is not human acceptance. Only after approval, record it with `aiw approve verification`. Do not start code review or final traceability before that command succeeds. If verification fails or changes are requested, record `aiw reject verification --reason=<feedback>` before editing the report or returning to implementation, then repeat verification, update the report, rerun the gate, and ask again. Use npx package invocation for other `aiw` commands when no global binary exists.