@multileaf/ai-workflow 0.1.4 → 0.1.5

package/CHANGELOG.md

@@ -4,6 +4,16 @@ All notable changes to this project are documented in this file. The format foll
 
 ## [Unreleased]
 
+## [0.1.5] - 2026-09-12
+
+### Fixed
+
+- Connect SDD capability recommendations through explicit prerequisites so custom selections include required earlier workflow stages.
+- Recommend verification for supported project profiles and test runners, including test commands discovered in monorepo workspaces.
+- Align brainstorming, specification, planning, and verification gates with their matching artifacts; remove references to a nonexistent review gate command.
+- Clarify skill handoffs across brainstorming, requirements, design, planning, implementation, verification, and code review.
+- Correct the project profile path referenced by the project initialization skill.
+
 ## [0.1.4] - 2026-09-12
 
 ### Added
@@ -66,7 +76,8 @@ All notable changes to this project are documented in this file. The format foll
 
 - Path confinement, symlink protection, explicit permission gates, secret redaction, strict parsers, atomic migrations, and immutable execution checkpoints.
 
-[Unreleased]: https://github.com/MultiLeaf/aiw/compare/v0.1.4...HEAD
+[Unreleased]: https://github.com/MultiLeaf/aiw/compare/v0.1.5...HEAD
+[0.1.5]: https://github.com/MultiLeaf/aiw/compare/v0.1.4...v0.1.5
 [0.1.4]: https://github.com/MultiLeaf/aiw/compare/v0.1.3...v0.1.4
 [0.1.3]: https://github.com/MultiLeaf/aiw/compare/v0.1.2...v0.1.3
 [0.1.2]: https://github.com/MultiLeaf/aiw/compare/v0.1.1...v0.1.2

package/README.md

@@ -122,49 +122,52 @@ flowchart TD
     D --> E[(.aiw/recommendations.yml)]
     E --> F{User confirms scope}
     F -->|Revise| B
-    F -->|Proceed| G[Brainstorm]
-
-    G --> H[(generated/specs/brainstorm.md)]
-    H --> I{Brainstorm gate}
-    I -->|Incomplete| G
-    I -->|Complete| J[Write specification]
-
-    J --> K[(generated/specs/specification.md)]
-    K --> L{Specification gate}
-    L -->|Incomplete| J
-    L -->|Complete| M{Architecture decision needed?}
-
-    M -->|Yes| N[Create ADR]
-    N --> O[(.context/adrs/ADR-NNN-title.md)]
-    O --> P[Update ADR index]
-    P --> Q[(.context/adrs/INDEX.md)]
-    M -->|No| R[Create implementation plan]
-    Q --> R
-
-    R --> S[(generated/plans/implementation-plan.md)]
-    S --> T{Plan gate}
-    T -->|Incomplete| R
-    T -->|Ready| U[Implement tasks with TDD]
-
-    U --> V[Write code and tests]
-    V --> W[Run task validation commands]
-    W --> X{Validation passes?}
-    X -->|No| U
-    X -->|Yes| Y[Record completion evidence]
-
-    Y --> Z[(generated/artifacts and checkpoint evidence)]
-    Z --> AA[Verify declared evidence]
-    AA --> AB{Verification gate}
-    AB -->|Missing evidence| U
-    AB -->|Complete| AC[Build traceability graph]
-
-    AC --> AD[Requirement → ADR → Task → Code → Test → Evidence]
-    AD --> AE[(generated artifacts and trace output)]
-    AE --> AF[Run repository self-validation]
-    AF --> AG[(.aiw/checkpoints/self-validation-TICKET.yml)]
-    AG --> AH{Review outcome}
-    AH -->|Changes required| U
-    AH -->|Accepted| AI[Commit and independent integration validation]
+    F -->|Proceed| G{Clarification needed?}
+
+    G -->|Yes| H[Brainstorm]
+    H --> I[(generated/specs/brainstorm.md)]
+    I --> J{Brainstorm gate}
+    J -->|Incomplete| H
+    J -->|Complete| K[Write specification]
+    G -->|No| K
+
+    K --> L[(generated/specs/specification.md)]
+    L --> M{Specification gate}
+    M -->|Incomplete| K
+    M -->|Complete| N{Architecture decision needed?}
+
+    N -->|Yes| O[Create ADR]
+    O --> P[(.context/adrs/ADR-NNN-title.md)]
+    P --> Q[Update ADR index]
+    Q --> R[(.context/adrs/INDEX.md)]
+    N -->|No| S[Create implementation plan]
+    R --> S
+
+    S --> T[(generated/plans/implementation-plan.md)]
+    T --> U{Plan gate}
+    U -->|Incomplete| S
+    U -->|Ready| V[Implement tasks with TDD]
+
+    V --> W[Write code and tests]
+    W --> X[Run task validation commands]
+    X --> Y{Validation passes?}
+    Y -->|No| V
+    Y -->|Yes| Z[Record completion evidence]
+
+    Z --> AA[(generated/artifacts and checkpoint evidence)]
+    AA --> AB[Write verification report]
+    AB --> AC{Verification gate}
+    AC -->|Missing evidence| V
+    AC -->|Complete| AD[Build traceability graph]
+
+    AD --> AE[Requirement → ADR → Task → Code → Test → Evidence]
+    AE --> AF[(generated artifacts and trace output)]
+    AF --> AG[Run code-review skill when installed]
+    AG --> AH{Review findings?}
+    AH -->|Changes required| V
+    AH -->|Clear| AI[Run repository self-validation]
+    AI --> AJ[(.aiw/checkpoints/self-validation-TICKET.yml)]
+    AJ --> AK[Commit and independent integration validation]
 
     B -. command history and evidence .-> LOGS[(.aiw/checkpoints/)]
     D -. command history and evidence .-> LOGS
@@ -180,7 +183,7 @@ npx @multileaf/ai-workflow scan
 npx @multileaf/ai-workflow recommend
 
 # In CI, provide comma-separated recommendation IDs detected for that project.
-npx @multileaf/ai-workflow recommend --select=typescript-quality,vitest-testing
+npx @multileaf/ai-workflow recommend --select=typescript-quality,verification
 
 # Create structured product artifacts.
 npx @multileaf/ai-workflow brainstorm --title="Feature name"
@@ -188,13 +191,18 @@ npx @multileaf/ai-workflow spec --title="Feature requirements"
 npx @multileaf/ai-workflow adr --id=001 --title="Technical decision"
 npx @multileaf/ai-workflow plan --title="Implementation plan"
 
-# Fill the generated scaffold sections before running their quality gates.
+# Optional, after creating a brainstorm artifact for an unclear request:
+npx @multileaf/ai-workflow gate brainstorming
+# After filling the specification and plan scaffolds shown above:
 npx @multileaf/ai-workflow gate specification
+npx @multileaf/ai-workflow gate plan
+# After writing .aiw/generated/reports/verification-report.md from the verification report template:
+npx @multileaf/ai-workflow gate verification
 npx @multileaf/ai-workflow verify
 npx @multileaf/ai-workflow trace
 ```
 
-Scaffold commands write deterministic files at fixed paths and a repeated invocation replaces that scaffold. Complete and review each artifact before advancing. Requirements use stable identifiers and Given/When/Then acceptance criteria. Plans link tasks to requirements, tests, risks, dependencies, and expected evidence. `gate` performs textual completeness checks, `verify` validates the expected verification fields rather than running a test command, and `trace` records declared links between requirements, decisions, tasks, code, tests, and evidence.
+Scaffold commands write deterministic files at fixed paths and a repeated invocation replaces that scaffold. Complete and review each artifact before advancing. Requirements use stable identifiers and Given/When/Then acceptance criteria. Plans link tasks to requirements, tests, risks, dependencies, and expected evidence. Each `gate` validates the artifact named by its stage. `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.
 
 ## Project intelligence
 

package/dist/adapter.js

@@ -44,8 +44,8 @@ This skill is the bootstrap for AI Workflow. The installer intentionally install
 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. Use the host's native selection widget. First offer three choices: install all recommendations, customize, or install none. If the user chooses customization, show the install plan in separate selectable blocks for skills, rules, agents, hooks, templates, and MCPs, with each item, its rationale, project-specific changes, and dependencies visible. If the host lacks a multi-select widget, use a numbered all/custom/none prompt and grouped checklists. MCP selection does not grant permission to execute the server or use external access; ask separately for those permissions.
-6. Record all recommendations with \`npx --yes --package=@multileaf/ai-workflow -- aiw recommend --select=all\`; for customized item-level choices, pass the selected resource references such as \`skills/verification,rules/tdd-policy,agents/test-engineer\`. Use \`npx --yes --package=@multileaf/ai-workflow -- aiw recommend --select=\` when none are chosen. If any AI Workflow resources are selected, run \`npx --yes --package=@multileaf/ai-workflow -- aiw sync\`, adding \`--allow=network:external\` only after separate approval. Install only 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.
+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 choices: install all recommendations, customize, or install none. 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, use a numbered all/custom/none prompt and grouped checklists. MCP selection does not grant permission to execute the server or use external access; ask separately for those permissions.
+6. Record all recommendations with \`npx --yes --package=@multileaf/ai-workflow -- aiw recommend --select=all\`; for customized item-level choices, pass the selected resource references such as \`skills/verification,rules/tdd-policy,agents/test-engineer\`. Use \`npx --yes --package=@multileaf/ai-workflow -- aiw recommend --select=\` when none are chosen. If any AI Workflow resources are selected, run \`npx --yes --package=@multileaf/ai-workflow -- aiw sync\` without extra permissions first. It installs selected bundled resources and reports any external resource that is still pending approval. Only if the user separately approves external access, rerun with \`--allow=network:external\` to install that pending external resource. Install only 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 → traceability → review.
 
@@ -53,11 +53,11 @@ If the user declines all recommendations, leave the project with only the bootst
 
 ## For each feature request after setup
 
-- Start with the brainstorming skill when scope, users, constraints, or assumptions are unclear.
-- Create and complete a specification with stable requirement IDs and Given/When/Then acceptance criteria; pass \`npx --yes --package=@multileaf/ai-workflow -- aiw gate specification\` before planning.
-- Record consequential architecture choices as ADRs. Create an implementation plan that links tasks to requirements, tests, risks, and validation commands; pass \`npx --yes --package=@multileaf/ai-workflow -- aiw gate plan\` before coding.
-- Follow the TDD policy and project quality rules. Use specialist agents for requirements, architecture, implementation, tests, security, documentation, and review when useful.
-- Run the declared checks, then \`npx --yes --package=@multileaf/ai-workflow -- aiw verify\`, \`npx --yes --package=@multileaf/ai-workflow -- aiw trace\`, and the review gate. Do not claim completion without evidence.
+- Use the brainstorming skill when scope, users, constraints, or assumptions are unclear; create its artifact with \`npx --yes --package=@multileaf/ai-workflow -- aiw brainstorm\`, then validate it with \`npx --yes --package=@multileaf/ai-workflow -- aiw gate brainstorming\`.
+- Create a specification with stable requirement IDs and Given/When/Then acceptance criteria; pass \`npx --yes --package=@multileaf/ai-workflow -- aiw gate specification\` before planning.
+- For changes with architecture impact, use technical design, record consequential choices as ADRs with \`npx --yes --package=@multileaf/ai-workflow -- aiw adr\`, and link those decisions to the requirements. Then create an implementation plan with \`npx --yes --package=@multileaf/ai-workflow -- aiw plan\`, linking tasks to requirements, tests, risks, and validation commands; pass \`npx --yes --package=@multileaf/ai-workflow -- aiw gate plan\` before coding.
+- When TDD resources are installed and the project has a test workflow, follow the TDD policy; otherwise use the project's existing validation methods. Follow installed project quality rules and use specialist agents only when they are installed and useful.
+- Run the declared checks, write \`.aiw/generated/reports/verification-report.md\` using the verification-report template, and pass \`npx --yes --package=@multileaf/ai-workflow -- aiw gate verification\`. Then run \`npx --yes --package=@multileaf/ai-workflow -- aiw verify\` and \`npx --yes --package=@multileaf/ai-workflow -- aiw trace\`. Use the code-review skill when installed and record its findings; AI Workflow does not provide a separate review gate. Do not claim completion without evidence.
 
 ## Language policy
 

package/dist/generator.js

@@ -2,18 +2,28 @@ import { resolveGeneratedPath } from "./drift.js";
 export function generateProjectResources(profile, selected, write) {
     const linterCommand = safeInlineValue(profile.quality.linter?.command);
     const formatterCommand = safeInlineValue(profile.quality.formatter?.command);
-    const testCommand = safeInlineValue(profile.testing?.command);
+    const testCommands = [
+        ...(profile.testing?.command ? [{ scope: "project", command: profile.testing.command }] : []),
+        ...(profile.modules ?? []).flatMap((module) => module.testing?.command
+            ? [{ scope: `workspace ${module.path}`, command: module.testing.command }]
+            : []),
+    ].map(({ scope, command }) => ({ scope, command: safeInlineValue(command) }));
+    const uniqueTestCommands = [
+        ...new Map(testCommands
+            .filter(({ command }) => command)
+            .map(({ scope, command }) => [`${scope}:${command}`, { scope, command }])).values(),
+    ];
     if (selected.includes("typescript-quality") || selected.includes("rules/project-quality"))
         write(resolveGeneratedPath("rules/project-quality.md"), `# Project Quality Rules\n\n- Use ${profile.runtime.languages.map((language) => (language === "typescript" ? "TypeScript" : language)).join(", ")} with strict typing.\n${linterCommand ? `- Run \`${linterCommand}\` before completion.\n` : ""}${formatterCommand ? `- Run \`${formatterCommand}\` before review.\n` : ""}- Keep all generated AI Workflow artifacts in English.\n`);
     if (selected.includes("tdd-development") || selected.includes("rules/tdd-project-policy"))
-        write(resolveGeneratedPath("rules/tdd-project-policy.md"), `# TDD Project Policy\n\n${testCommand ? `- Run \`${testCommand}\` for verification.\n` : ""}- Write a failing behavioral test before implementation.\n- Refactor only after the test is green.\n`);
+        write(resolveGeneratedPath("rules/tdd-project-policy.md"), `# TDD Project Policy\n\n${uniqueTestCommands.map(({ scope, command }) => `- Run the ${scope} test command \`${command}\` for verification.`).join("\n")}${uniqueTestCommands.length ? "\n" : ""}- Write a failing behavioral test before implementation.\n- Refactor only after the test is green.\n`);
     if (selected.includes("nextjs-development") ||
         selected.includes("react-best-practices") ||
         selected.includes("rules/architecture-policy"))
         write(resolveGeneratedPath("agents/project-context.md"), `# Project Context\n\nThis project uses ${profile.frameworks.map((framework) => (framework === "nextjs" ? "Next.js" : framework)).join(", ")}. Follow the detected project structure and existing framework conventions.\n`);
     if (selected.length > 0) {
         write(resolveGeneratedPath("context/project-profile.md"), `# Confirmed Project Profile\n\n- Languages: ${profile.runtime.languages.join(", ") || "none detected"}\n- Frameworks: ${profile.frameworks.join(", ") || "none detected"}\n- Package manager: ${profile.packageManager}\n- All generated content is in English.\n`);
-        write(resolveGeneratedPath("hooks/quality-check.md"), `# Quality Check Hook\n\nRun the available project quality commands before completion.${linterCommand ? `\n\n- Linter: \`${linterCommand}\`` : ""}${formatterCommand ? `\n- Formatter: \`${formatterCommand}\`` : ""}${testCommand ? `\n- Tests: \`${testCommand}\`` : ""}\n`);
+        write(resolveGeneratedPath("hooks/quality-check.md"), `# Quality Check Hook\n\nRun the available project quality commands before completion.${linterCommand ? `\n\n- Linter: \`${linterCommand}\`` : ""}${formatterCommand ? `\n- Formatter: \`${formatterCommand}\`` : ""}${uniqueTestCommands.map(({ scope, command }) => `\n- ${scope} tests: \`${command}\``).join("")}\n`);
     }
 }
 function safeInlineValue(value) {

package/dist/quality-gates.d.ts

@@ -1,2 +1,2 @@
-export type QualityGateStage = "specification" | "plan" | "verification";
+export type QualityGateStage = "brainstorming" | "specification" | "plan" | "verification";
 export declare function evaluateQualityGate(stage: QualityGateStage, content: string): string[];

package/dist/quality-gates.js

@@ -11,7 +11,7 @@ function requireSections(content, artifact, headings) {
     });
 }
 export function evaluateQualityGate(stage, content) {
-    if (stage === "specification")
+    if (stage === "brainstorming")
         return requireSections(content, "Brainstorm", [
             "Goal",
             "Users",
@@ -19,7 +19,7 @@ export function evaluateQualityGate(stage, content) {
             "Risks",
             "Non-goals",
         ]);
-    if (stage === "plan") {
+    if (stage === "specification") {
         const issues = [];
         if (!/REQ-\d+/.test(content))
             issues.push("Specification must define a stable REQ-### ID.");
@@ -29,12 +29,21 @@ export function evaluateQualityGate(stage, content) {
             issues.push("Requirement acceptance criteria must use Given, When, and Then.");
         return issues;
     }
-    const fields = ["Requirement", "Code", "Tests", "Validation", "Evidence"];
-    const issues = !/TASK-\d+/.test(content)
-        ? ["Implementation plan must define a TASK-### ID."]
-        : [];
-    for (const field of fields)
-        if (!new RegExp(`^[ \\t]*-?[ \\t]*${field}:[ \\t]*\\S+`, "im").test(content))
-            issues.push(`Implementation plan task must define ${field}.`);
-    return issues;
+    if (stage === "plan") {
+        const fields = ["Requirement", "Code", "Tests", "Validation", "Evidence"];
+        const issues = !/TASK-\d+/.test(content)
+            ? ["Implementation plan must define a TASK-### ID."]
+            : [];
+        for (const field of fields)
+            if (!new RegExp(`^[ \\t]*-?[ \\t]*${field}:[ \\t]*\\S+`, "im").test(content))
+                issues.push(`Implementation plan task must define ${field}.`);
+        return issues;
+    }
+    return requireSections(content, "Verification Report", [
+        "Requirements Checked",
+        "Checks Passed",
+        "Missing Evidence",
+        "Residual Risks",
+        "Decision",
+    ]);
 }

package/dist/recommendations.d.ts

@@ -13,6 +13,7 @@ export type CapabilityRecommendation = {
     permissions: string[];
     conflicts: string[];
     resources: RecommendedResource[];
+    requires?: string[];
 };
 export declare function recommendCapabilities(profile: ProjectProfile): CapabilityRecommendation[];
 export declare function resourcesForCapabilities(ids: string[]): RecommendedResource[];

package/dist/recommendations.js

@@ -38,10 +38,26 @@ const CATALOG = [
             { type: "agents", id: "technical-architect" },
             { type: "templates", id: "implementation-plan" },
         ]),
+        requires: ["requirements-specification"],
         matches: (profile) => hasProjectSignals(profile)
             ? { evidence: projectEvidence(profile), confidence: 0.88 }
             : undefined,
     },
+    {
+        id: "technical-design",
+        provider: "multileaf",
+        rationale: "Architecture changes benefit from explicit alternatives, trade-offs, and decision records.",
+        permissions: [],
+        resources: local([
+            { type: "skills", id: "technical-design" },
+            { type: "agents", id: "technical-architect" },
+            { type: "templates", id: "technical-design" },
+            { type: "templates", id: "decision-record" },
+        ]),
+        matches: (profile) => hasProjectSignals(profile)
+            ? { evidence: projectEvidence(profile), confidence: 0.82 }
+            : undefined,
+    },
     {
         id: "code-review",
         provider: "multileaf",
@@ -51,6 +67,7 @@ const CATALOG = [
             { type: "skills", id: "code-review" },
             { type: "agents", id: "quality-reviewer" },
         ]),
+        requires: ["verification"],
         matches: (profile) => profile.runtime.languages.length
             ? { evidence: projectEvidence(profile), confidence: 0.86 }
             : undefined,
@@ -68,9 +85,25 @@ const CATALOG = [
             { type: "hooks", id: "post-implementation" },
             { type: "templates", id: "test-plan" },
         ]),
-        matches: (profile) => profile.testing
-            ? { evidence: [`testing:${profile.testing.name}`], confidence: 1 }
-            : undefined,
+        requires: ["verification"],
+        matches: (profile) => {
+            const runners = [
+                ...(profile.testing ? [profile.testing] : []),
+                ...(profile.modules ?? []).flatMap((module) => module.testing ? [{ ...module.testing, module: module.path }] : []),
+            ];
+            return runners.length
+                ? {
+                    evidence: [
+                        ...new Set(runners.flatMap((runner) => [
+                            ...("module" in runner ? [`workspace:${runner.module}`] : []),
+                            `testing:${runner.name}`,
+                            ...(runner.command ? [`test-command:${runner.command}`] : []),
+                        ])),
+                    ],
+                    confidence: 1,
+                }
+                : undefined;
+        },
     },
     {
         id: "typescript-quality",
@@ -116,18 +149,19 @@ const CATALOG = [
             : undefined,
     },
     {
-        id: "vitest-testing",
+        id: "verification",
         provider: "multileaf",
-        rationale: "Vitest is configured and can be used by the verification skill and test specialist.",
+        rationale: "Verification guidance can use the project's detected test runner and quality commands.",
         permissions: [],
         resources: local([
             { type: "skills", id: "verification" },
-            { type: "agents", id: "test-engineer" },
+            { type: "agents", id: "quality-reviewer" },
             { type: "templates", id: "test-plan" },
             { type: "templates", id: "verification-report" },
         ]),
-        matches: (profile) => profile.testing?.name === "vitest"
-            ? { evidence: ["testing:vitest"], confidence: 1 }
+        requires: ["implementation-planning"],
+        matches: (profile) => hasProjectSignals(profile)
+            ? { evidence: projectEvidence(profile), confidence: profile.testing ? 1 : 0.84 }
             : undefined,
     },
     {
@@ -208,8 +242,9 @@ export function recommendCapabilities(profile) {
     });
 }
 export function resourcesForCapabilities(ids) {
-    const selectedCapabilities = new Set(CATALOG.filter(({ id }) => ids.includes(id)).map(({ id }) => id));
-    const selectedResources = new Set(ids.filter((id) => id.includes("/")));
+    const normalizedIds = ids.map((id) => (id === "vitest-testing" ? "verification" : id));
+    const selectedCapabilities = new Set(CATALOG.filter(({ id }) => normalizedIds.includes(id)).map(({ id }) => id));
+    const selectedResources = new Set(normalizedIds.filter((id) => id.includes("/")));
     const resources = CATALOG.flatMap(({ id, resources }) => selectedCapabilities.has(id)
         ? resources
         : resources.filter(({ type, id: resourceId }) => selectedResources.has(`${type}/${resourceId}`)));
@@ -219,7 +254,7 @@ export function resourcesForCapabilities(ids) {
 }
 export function serializeRecommendations(items, selected = []) {
     return `schema: 1\nrecommendations:\n${items
-        .map((item) => `  - id: ${item.id}\n    provider: ${item.provider}\n    confidence: ${item.confidence}\n    selected: ${selected.includes(item.id)}\n    resources: [${item.resources.map(({ type, id }) => `${type}/${id}`).join(", ")}]\n    selected_resources: [${item.resources
+        .map((item) => `  - id: ${item.id}\n    provider: ${item.provider}\n    confidence: ${item.confidence}\n    selected: ${selected.includes(item.id)}\n    requires: [${(item.requires ?? []).join(", ")}]\n    resources: [${item.resources.map(({ type, id }) => `${type}/${id}`).join(", ")}]\n    selected_resources: [${item.resources
         .filter(({ type, id }) => selected.includes(`${type}/${id}`))
         .map(({ type, id }) => `${type}/${id}`)
         .join(", ")}]\n    evidence: [${item.evidence.map((evidence) => `"${evidence}"`).join(", ")}]\n    rationale: ${item.rationale}`)

package/dist/selection.js

@@ -3,15 +3,45 @@ export async function selectRecommendations(items, answer, selectedIds) {
         item.id,
         ...(item.resources ?? []).map(({ type, id }) => `${type}/${id}`),
     ]));
+    available.add("vitest-testing");
     if (selectedIds?.includes("all"))
         return items.map(({ id }) => id);
     if (selectedIds)
-        return [...new Set(selectedIds.filter((id) => available.has(id)))];
+        return includeRequirements(items, selectedIds
+            .filter((id) => available.has(id))
+            .map((id) => (id === "vitest-testing" ? "verification" : id)));
     const selected = [];
     for (const item of items) {
         const response = (await answer(`Install ${item.id}? [Y/n] `)).trim().toLowerCase();
         if (response === "" || response === "y" || response === "yes")
             selected.push(item.id);
     }
-    return selected;
+    return includeRequirements(items, selected);
+}
+function includeRequirements(items, selectedIds) {
+    const selected = new Set(selectedIds);
+    const byId = new Map(items.map((item) => [item.id, item]));
+    const owners = new Map();
+    for (const item of items)
+        for (const resource of item.resources ?? [])
+            owners.set(`${resource.type}/${resource.id}`, item.id);
+    const visit = (capabilityId, visited) => {
+        if (visited.has(capabilityId))
+            return;
+        visited.add(capabilityId);
+        const capability = byId.get(capabilityId);
+        if (!capability)
+            return;
+        for (const requirement of capability.requires ?? []) {
+            if (!byId.has(requirement))
+                continue;
+            selected.add(requirement);
+            visit(requirement, visited);
+        }
+    };
+    const initial = [...selected];
+    const visited = new Set();
+    for (const id of initial)
+        visit(byId.has(id) ? id : (owners.get(id) ?? ""), visited);
+    return [...selected];
 }

package/dist/workflow.js

@@ -749,6 +749,36 @@ export async function runCommand(args, root, fs, services = {}) {
                 : await profileProject(root);
             const selectedArg = args.find((arg) => arg.startsWith("--select="))?.split("=", 2)[1];
             const selected = selectedArg?.split(",") ?? (command === "sync" ? readSelectedRecommendations(fs, aiw) : []);
+            if (command === "sync") {
+                const result = syncSelectedResources(fs, root, aiw, profile, selected);
+                if (result.error)
+                    return { exitCode: 1, error: result.error };
+                const messages = [result.output ?? "Selected bundled resources synchronized."];
+                if (selected.includes("react-best-practices")) {
+                    const approvedPermissions = parseApprovedPermissions(args);
+                    if (!approvedPermissions.includes("network:external")) {
+                        messages.push("Remote skill pending: network:external was not approved. Bundled resources were installed; rerun sync with --allow=network:external only if you approve external access.");
+                    }
+                    else {
+                        try {
+                            enforceConfiguredOrganizationPolicy(fs, aiw, {
+                                provider: "vercel-skills",
+                                source: "vercel-labs/agent-skills",
+                                permissions: ["network:external"],
+                            });
+                            const target = parseManifest(fs.read(join(aiw, "manifest.yml"))).target.active;
+                            await installVercelSkill(services.externalSkills ?? nodeCommandExecutor, "vercel-labs/agent-skills", "vercel-react-best-practices", target);
+                            writeVercelSkillLock(fs, root, aiw, "vercel-labs/agent-skills", "vercel-react-best-practices");
+                            messages.push("Remote React best-practices skill installed.");
+                        }
+                        catch (error) {
+                            const reason = error instanceof Error ? error.message : String(error);
+                            messages.push(`Remote skill pending: ${reason}`);
+                        }
+                    }
+                }
+                return { exitCode: 0, output: messages.join(" ") };
+            }
             if (selected.includes("react-best-practices")) {
                 const approvedPermissions = parseApprovedPermissions(args);
                 if (!approvedPermissions.includes("network:external"))
@@ -765,12 +795,6 @@ export async function runCommand(args, root, fs, services = {}) {
                 await installVercelSkill(services.externalSkills ?? nodeCommandExecutor, "vercel-labs/agent-skills", "vercel-react-best-practices", target);
                 writeVercelSkillLock(fs, root, aiw, "vercel-labs/agent-skills", "vercel-react-best-practices");
             }
-            if (command === "sync") {
-                const result = syncSelectedResources(fs, root, aiw, profile, selected);
-                return result.error
-                    ? { exitCode: 1, error: result.error }
-                    : { exitCode: 0, output: result.output };
-            }
             const conflicts = [];
             generateProjectResources(profile, selected, (path, content) => {
                 const destination = join(aiw, path);
@@ -1019,12 +1043,16 @@ export async function runCommand(args, root, fs, services = {}) {
                 return { exitCode: 1, error: "Run `aiw install` first." };
             const stage = args[1];
             const requirements = {
-                specification: "generated/specs/brainstorm.md",
-                plan: "generated/specs/specification.md",
-                verification: "generated/plans/implementation-plan.md",
+                brainstorming: "generated/specs/brainstorm.md",
+                specification: "generated/specs/specification.md",
+                plan: "generated/plans/implementation-plan.md",
+                verification: "generated/reports/verification-report.md",
             };
-            if (!stage || !(stage in requirements))
-                return { exitCode: 1, error: "Usage: aiw gate <specification|plan|verification>" };
+            if (!stage || !Object.hasOwn(requirements, stage))
+                return {
+                    exitCode: 1,
+                    error: "Usage: aiw gate <brainstorming|specification|plan|verification>",
+                };
             const gateStage = stage;
             const artifact = requirements[gateStage];
             if (!fs.exists(join(aiw, artifact)))

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

@@ -10,9 +10,9 @@ Make `/ai-init` a guided, evidence-backed onboarding flow. The initial `npx` ins
 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.
-5. **Recommendations.** Match catalog capabilities to the consolidated project profile. Show each recommendation with its purpose, evidence, resource types (skills, rules, agents, hooks, templates), required permissions, MCP server/source, and project-specific configuration steps. 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.** Use the coding host's native selection widget when it supports one. First offer: install all recommendations, customize, or install none. For customization, show selectable blocks grouped by resource type, then the individual recommended items in each selected block. Include MCPs as a separate block. Keep dependencies visible and select required dependencies together. If the host has no selection widget, use an equivalent numbered prompt and accept all/custom/none explicitly.
-7. **Install and personalize.** Install only the confirmed selection. For “all”, install every recommendation. 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.
+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. 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, use an equivalent numbered prompt and accept all/custom/none explicitly.
+7. **Install and personalize.** Install only the confirmed selection. 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.
 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
@@ -31,12 +31,14 @@ Make `/ai-init` a guided, evidence-backed onboarding flow. The initial `npx` ins
 - **AIINIT-003:** On supported hosts, three independent read-only analysis agents start in parallel and the orchestrator consolidates their evidence; unsupported hosts use a disclosed sequential fallback.
 - **AIINIT-004:** Scans include separate summaries for every detected monorepo workspace and do not attribute root dependencies to all packages.
 - **AIINIT-005:** Recommendations identify matching evidence, resource blocks, dependencies, MCP sources, and permissions.
+- **AIINIT-012:** Recommendations are displayed in concise tables grouped by category, and each item has a project-specific reason and supporting evidence before selection.
 - **AIINIT-006:** The selection UI offers install-all, custom, and none; custom selections can choose individual items by skills, rules, agents, hooks, templates, and MCPs.
 - **AIINIT-007:** Installation activates only selected resources and required dependencies, personalizes only context-sensitive content, and preserves unowned or edited files.
 - **AIINIT-008:** MCP setup is target-aware, merges safely with existing configuration, never stores literal secrets, and requires separate permission approval.
 - **AIINIT-009:** Completion lists changes and recommends a session restart/reload to discover installed resources.
 - **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:** A selected remote resource without approved network access does not block independent bundled resource sync; sync reports the remote item as pending and preserves unrelated project files.
 
 ## Delivery slices
 

package/docs/backlog.md

@@ -43,6 +43,7 @@ Priority levels: **P0** blocks the product or makes it unsafe; **P1** is require
 - [x] **SDD-005** Implement verification skill. _Acceptance:_ missing evidence and untested requirements are reported.
 - [x] **SDD-006** Implement requirement-to-evidence traceability graph. _Acceptance:_ requirement → decision → task → code → test → evidence is queryable.
 - [x] **SDD-007** Add quality gates between workflow stages. _Acceptance:_ incomplete artifacts block progression with actionable feedback.
+- [x] **SDD-008** Connect workflow recommendations and quality gates to the SDD sequence. _Acceptance:_ selected later stages include declared prerequisites; verification is recommended for supported project profiles and test runners; each gate checks the matching artifact; review instructions do not refer to a nonexistent CLI gate.
 
 ## Adapters and migration — P1/P2
 

package/package.json

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

package/resources/skills/brainstorming.md

@@ -7,3 +7,4 @@ description: Turn an early product idea into structured goals, assumptions, cons
 
 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.
 
+When the request is already clear, skip brainstorming. Once the goal and constraints are clear, hand off to `requirements-specification` and link the specification to this brainstorm when one exists.

package/resources/skills/code-review.md

@@ -7,3 +7,4 @@ description: Review code for correctness, maintainability, design quality, and r
 
 Review behavior, boundaries, cohesion, naming, types, error handling, duplication, complexity, tests, and documentation. Prioritize actionable findings with severity and evidence.
 
+If findings require changes, send them back to implementation and require verification again. If there are no blocking findings, record the review result and complete traceability. This skill is a review checklist, not a CLI quality gate.

package/resources/skills/implementation-planning.md

@@ -7,3 +7,4 @@ description: Break an approved design into independently verifiable implementati
 
 Create small ordered tasks. Each task must reference requirements, affected modules, tests, commands, dependencies, and completion evidence.
 
+After the plan passes its gate, implement in task order. Use `tdd-development` when it is installed and the project has a test workflow; otherwise use the repository's existing validation methods. Hand completed work to `verification`.

package/resources/skills/project-init.md

@@ -5,5 +5,4 @@ description: Inspect a repository, build a project profile, and prepare AI Workf
 
 # Project Initialization
 
-Inspect structure and configuration safely. Detect languages, frameworks, package managers, scripts, tests, quality tools, CI, and conventions. Record evidence and confidence in `.ai-workflow/profile.yaml`. Ask for confirmation before treating uncertain inferences as facts. Recommend capabilities with rationale, permissions, and conflicts.
-
+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

@@ -7,3 +7,4 @@ description: Convert a product idea into testable, traceable requirements.
 
 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.
 
+After requirements are confirmed, use `technical-design` when the change affects architecture or has consequential design choices; otherwise hand off to `implementation-planning`.

package/resources/skills/tdd-development.md

@@ -7,3 +7,4 @@ description: Implement repository changes through test-first development.
 
 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, hand off to `verification` with the changed requirements, test commands, and evidence.

package/resources/skills/technical-design.md

@@ -7,3 +7,4 @@ description: Design modular technical solutions from approved requirements.
 
 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.
 
+Link each design and ADR to the affected requirements. Once decisions are recorded, hand off to `implementation-planning`.

package/resources/skills/verification.md

@@ -7,3 +7,4 @@ description: Verify implementation against requirements and produce traceable ev
 
 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.
 
+Create the verification report and validate it with `npx --yes --package=@multileaf/ai-workflow -- aiw gate verification`. Then hand off to `code-review` when installed; after review, update traceability and completion evidence.