@multileaf/ai-workflow 0.1.3 → 0.1.4

package/CHANGELOG.md

@@ -4,6 +4,22 @@ All notable changes to this project are documented in this file. The format foll
 
 ## [Unreleased]
 
+## [0.1.4] - 2026-09-12
+
+### Added
+
+- Guided `/ai-init` onboarding with model-cost guidance, parallel project analysis, monorepo-aware profiles, selectable resource blocks, and project-specific resource personalization.
+- NestJS, Prisma, and Vite capability recommendations with matching skills, agents, and data-access guidance.
+
+### Changed
+
+- Allow recommendation selection by individual resource, including an explicit select-all option.
+- Expand project profiles with workspace-level technologies, quality tools, test runners, architecture, patterns, and evidence.
+
+### Documentation
+
+- Specify onboarding flow, host capabilities, MCP recommendations, safety expectations, and acceptance criteria.
+
 ## [0.1.3] - 2026-09-12
 
 ### Fixed
@@ -50,7 +66,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.3...HEAD
+[Unreleased]: https://github.com/MultiLeaf/aiw/compare/v0.1.4...HEAD
+[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
 [0.1.1]: https://github.com/MultiLeaf/aiw/releases/tag/v0.1.1

package/dist/adapter.js

@@ -40,12 +40,14 @@ This skill is the bootstrap for AI Workflow. The installer intentionally install
 
 ## First-run setup
 
-1. Inspect the repository's existing AI instructions and project structure. Preserve user-authored files and do not expose secrets.
-2. Run \`npx --yes --package=@multileaf/ai-workflow -- aiw scan\`. Explain the detected facts and their evidence; ask the user to confirm uncertain inferences before they influence generated content.
-3. Run \`npx --yes --package=@multileaf/ai-workflow -- aiw recommend\`, then read \`.aiw/recommendations.yml\` and \`.aiw/profile.yml\`. Explain why each suggested skill, rule, agent, hook, or template fits and identify external permissions. Ask which capabilities to install, and ask separately before granting an external permission such as \`network:external\`.
-4. Record the user's choices with \`npx --yes --package=@multileaf/ai-workflow -- aiw recommend --select=id,id\`; use \`npx --yes --package=@multileaf/ai-workflow -- aiw recommend --select=\` when all recommendations are declined. If at least one capability is selected, run \`npx --yes --package=@multileaf/ai-workflow -- aiw sync\`; when the user separately approved external network access, add \`--allow=network:external\`. Sync installs only selected resources and fills supported project rules with detected stack and quality-tool details. Do not add unselected resources or overwrite existing files.
-5. Review the installed resource list and the generated project-specific files with the user. Ask before changing project policy or tailoring any other skill/rule.
-6. Introduce the selected workflow gates: brainstorming → specification → architecture decision when needed → implementation plan → implementation with tests → verification → traceability → review. Use only gates supported by the resources the user chose.
+1. Before scanning, recommend that the user switch to a cheaper model for this onboarding. Ask whether they switched or prefer 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.
+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.
+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.
 
 If the user declines all recommendations, leave the project with only the bootstrap skill and scan state. Do not treat scanning or recommendation as consent to install.
 

package/dist/generator.js

@@ -3,11 +3,13 @@ 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);
-    if (selected.includes("typescript-quality"))
+    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"))
+    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`);
-    if (selected.includes("nextjs-development") || selected.includes("react-best-practices"))
+    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`);

package/dist/profile.d.ts

@@ -3,6 +3,24 @@ export type Tool = {
     name: string;
     command?: string;
 };
+export type ProjectModule = {
+    path: string;
+    name?: string;
+    runtime: {
+        languages: string[];
+    };
+    frameworks: string[];
+    packageManager: string;
+    quality: {
+        linter?: Tool;
+        formatter?: Tool;
+        typecheck?: Tool;
+    };
+    testing?: Tool;
+    architecture?: string[];
+    patterns?: string[];
+    evidence?: string[];
+};
 export type ProjectProfile = {
     runtime: {
         languages: string[];
@@ -17,6 +35,7 @@ export type ProjectProfile = {
     testing?: Tool;
     ci: string[];
     workspaces: string[];
+    modules?: ProjectModule[];
     facts: EvidenceFact[];
 };
 export declare function parseProjectProfile(content: string): ProjectProfile;

package/dist/profile.js

@@ -1,5 +1,5 @@
 import { readFile } from "node:fs/promises";
-import { join } from "node:path";
+import { dirname, join } from "node:path";
 import { scanProject } from "./scanner.js";
 import { buildFacts } from "./evidence.js";
 function scalar(content, key) {
@@ -36,6 +36,15 @@ export function parseProjectProfile(content) {
         const toolName = scalar(content, name);
         return toolName ? { name: toolName, command: scalar(content, command) } : undefined;
     };
+    let modules = [];
+    try {
+        const parsed = JSON.parse(scalar(content, "project_modules") ?? "[]");
+        if (Array.isArray(parsed))
+            modules = parseModules(parsed);
+    }
+    catch {
+        modules = [];
+    }
     return {
         runtime: { languages },
         frameworks,
@@ -48,12 +57,68 @@ export function parseProjectProfile(content) {
         testing: tool("testing", "testing_command"),
         ci: list(content, "ci"),
         workspaces: list(content, "workspaces"),
+        modules,
         facts: [],
     };
 }
+function parseModules(values) {
+    return values.slice(0, 256).flatMap((value) => {
+        if (!value || typeof value !== "object" || Array.isArray(value))
+            return [];
+        const item = value;
+        if (typeof item.path !== "string" || !item.path.trim())
+            return [];
+        const runtime = item.runtime && typeof item.runtime === "object"
+            ? item.runtime
+            : {};
+        const quality = item.quality && typeof item.quality === "object"
+            ? item.quality
+            : {};
+        const tool = (candidate) => {
+            if (!candidate || typeof candidate !== "object" || Array.isArray(candidate))
+                return undefined;
+            const details = candidate;
+            if (typeof details.name !== "string" || !details.name.trim())
+                return undefined;
+            return {
+                name: details.name.slice(0, 180),
+                command: typeof details.command === "string" ? details.command.slice(0, 180) : undefined,
+            };
+        };
+        return [
+            {
+                path: item.path.slice(0, 240),
+                name: typeof item.name === "string" ? item.name.slice(0, 180) : undefined,
+                runtime: { languages: stringArray(runtime.languages) },
+                frameworks: stringArray(item.frameworks),
+                packageManager: typeof item.packageManager === "string" ? item.packageManager.slice(0, 80) : "unknown",
+                quality: {
+                    linter: tool(quality.linter),
+                    formatter: tool(quality.formatter),
+                    typecheck: tool(quality.typecheck),
+                },
+                testing: tool(item.testing),
+                architecture: stringArray(item.architecture),
+                patterns: stringArray(item.patterns),
+                evidence: stringArray(item.evidence),
+            },
+        ];
+    });
+}
+function stringArray(value) {
+    return Array.isArray(value)
+        ? value
+            .filter((item) => typeof item === "string")
+            .slice(0, 32)
+            .map((item) => item.slice(0, 240))
+        : [];
+}
 async function packageManifest(root) {
+    return packageManifestFile(join(root, "package.json"));
+}
+async function packageManifestFile(path) {
     try {
-        return JSON.parse(await readFile(join(root, "package.json"), "utf8"));
+        return JSON.parse(await readFile(path, "utf8"));
     }
     catch {
         return {};
@@ -69,17 +134,21 @@ export async function profileProject(root) {
     const scan = await scanProject(root);
     const manifest = await packageManifest(root);
     const files = scan.files;
+    const moduleManifests = files.filter((file) => /(^|\/)package\.json$/.test(file));
+    const packageDirectories = moduleManifests.map((file) => dirname(file));
+    const modules = await Promise.all(moduleManifests
+        .filter((file) => dirname(file) !== ".")
+        .map((file) => profileModule(root, file, files, scan.evidence, undefined, packageDirectories)));
+    const rootModule = await profileModule(root, "package.json", files, scan.evidence, manifest, packageDirectories);
     const languages = [
-        ...new Set(scan.evidence
-            .filter((item) => item.fact.startsWith("language."))
-            .map((item) => item.fact.replace("language.", ""))),
+        ...new Set([
+            ...rootModule.runtime.languages,
+            ...modules.flatMap((item) => item.runtime.languages),
+        ]),
     ];
     const frameworks = [
-        hasDependency(manifest, "next") ? "nextjs" : "",
-        hasDependency(manifest, "react") ? "react" : "",
-        hasDependency(manifest, "vue") ? "vue" : "",
-        hasDependency(manifest, "express") ? "express" : "",
-    ].filter(Boolean);
+        ...new Set([...rootModule.frameworks, ...modules.flatMap((item) => item.frameworks)]),
+    ];
     const packageManager = files.includes("pnpm-lock.yaml")
         ? "pnpm"
         : files.includes("yarn.lock")
@@ -116,8 +185,74 @@ export async function profileProject(root) {
         testing: testingName ? { name: testingName, command: commandFor(manifest, "test") } : undefined,
         ci: files.some((file) => file.startsWith(".github/workflows/")) ? ["github-actions"] : [],
         workspaces,
+        modules,
         facts: [],
     };
     profile.facts = buildFacts(profile, scan.evidence);
     return profile;
 }
+async function profileModule(root, manifestPath, files, evidence, existingManifest, packageDirectories = []) {
+    const manifest = existingManifest ?? (await packageManifestFile(join(root, manifestPath)));
+    const modulePath = dirname(manifestPath) === "." ? "." : dirname(manifestPath).split("\\").join("/");
+    const prefix = modulePath === "." ? "" : `${modulePath}/`;
+    const childPrefixes = packageDirectories
+        .filter((directory) => directory !== modulePath && directory.startsWith(prefix))
+        .map((directory) => `${directory}/`);
+    const moduleFiles = files.filter((file) => file.startsWith(prefix) && !childPrefixes.some((childPrefix) => file.startsWith(childPrefix)));
+    const languages = [
+        ...new Set(evidence
+            .filter((item) => item.fact.startsWith("language.") && item.source.startsWith(prefix))
+            .map((item) => item.fact.slice("language.".length))),
+    ];
+    const frameworkSet = new Set();
+    const addDependency = (dependency, label) => {
+        if (hasDependency(manifest, dependency))
+            frameworkSet.add(label);
+    };
+    addDependency("next", "nextjs");
+    addDependency("react", "react");
+    addDependency("vue", "vue");
+    addDependency("express", "express");
+    addDependency("@nestjs/core", "nestjs");
+    addDependency("@prisma/client", "prisma");
+    addDependency("prisma", "prisma");
+    addDependency("vite", "vite");
+    addDependency("fastify", "fastify");
+    if (moduleFiles.some((file) => file.startsWith(`${prefix}prisma/`) && file.endsWith(".prisma")))
+        frameworkSet.add("prisma");
+    const testingName = hasDependency(manifest, "vitest")
+        ? "vitest"
+        : hasDependency(manifest, "jest")
+            ? "jest"
+            : hasDependency(manifest, "@playwright/test")
+                ? "playwright"
+                : hasDependency(manifest, "cypress")
+                    ? "cypress"
+                    : undefined;
+    const qualityTool = (dependency, config, script, name) => hasDependency(manifest, dependency) ||
+        moduleFiles.some((file) => file.startsWith(`${prefix}${config}`))
+        ? { name, command: commandFor(manifest, script) }
+        : undefined;
+    const packageManager = moduleFiles.some((file) => file === `${prefix}pnpm-lock.yaml`)
+        ? "pnpm"
+        : moduleFiles.some((file) => file === `${prefix}yarn.lock`)
+            ? "yarn"
+            : moduleFiles.some((file) => file === `${prefix}package-lock.json`)
+                ? "npm"
+                : "unknown";
+    return {
+        path: modulePath,
+        name: typeof manifest.name === "string" ? manifest.name : undefined,
+        runtime: { languages },
+        frameworks: [...frameworkSet],
+        packageManager,
+        quality: {
+            linter: qualityTool("eslint", "eslint.config", "lint", "eslint"),
+            formatter: qualityTool("prettier", "prettier", "format", "prettier"),
+            typecheck: commandFor(manifest, "typecheck")
+                ? { name: "typescript", command: commandFor(manifest, "typecheck") }
+                : undefined,
+        },
+        testing: testingName ? { name: testingName, command: commandFor(manifest, "test") } : undefined,
+    };
+}

package/dist/recommendations.js

@@ -85,6 +85,36 @@ const CATALOG = [
             ? { evidence: ["language:typescript"], confidence: 1 }
             : undefined,
     },
+    {
+        id: "nestjs-backend",
+        provider: "multileaf",
+        rationale: "NestJS is detected in this project; its module, dependency-injection, and test conventions can guide backend work.",
+        permissions: [],
+        resources: local([
+            { type: "skills", id: "nestjs-development" },
+            { type: "agents", id: "nestjs-engineer" },
+            { type: "rules", id: "architecture-policy" },
+            { type: "templates", id: "technical-design" },
+        ]),
+        matches: (profile) => profile.frameworks.includes("nestjs")
+            ? { evidence: projectEvidence(profile, "nestjs"), confidence: 1 }
+            : undefined,
+    },
+    {
+        id: "prisma-data-access",
+        provider: "multileaf",
+        rationale: "Prisma is detected; schema and data-access changes need migration-aware guidance aligned to the owning workspace.",
+        permissions: [],
+        resources: local([
+            { type: "skills", id: "prisma-data-access" },
+            { type: "agents", id: "prisma-engineer" },
+            { type: "rules", id: "data-access-policy" },
+            { type: "rules", id: "security-policy" },
+        ]),
+        matches: (profile) => profile.frameworks.includes("prisma")
+            ? { evidence: projectEvidence(profile, "prisma"), confidence: 1 }
+            : undefined,
+    },
     {
         id: "vitest-testing",
         provider: "multileaf",
@@ -130,6 +160,21 @@ const CATALOG = [
             ? { evidence: ["framework:nextjs"], confidence: 1 }
             : undefined,
     },
+    {
+        id: "vite-frontend",
+        provider: "multileaf",
+        rationale: "Vite is detected; frontend build, test, and module guidance should follow the owning app's framework and scripts.",
+        permissions: [],
+        resources: local([
+            { type: "skills", id: "vite-frontend" },
+            { type: "agents", id: "typescript-engineer" },
+            { type: "rules", id: "quality-gates" },
+            { type: "templates", id: "technical-design" },
+        ]),
+        matches: (profile) => profile.frameworks.includes("vite")
+            ? { evidence: projectEvidence(profile, "vite"), confidence: 1 }
+            : undefined,
+    },
     {
         id: "security-review",
         provider: "multileaf",
@@ -163,15 +208,21 @@ export function recommendCapabilities(profile) {
     });
 }
 export function resourcesForCapabilities(ids) {
-    const selected = new Set(ids);
-    const resources = CATALOG.filter(({ id }) => selected.has(id)).flatMap(({ resources }) => resources);
+    const selectedCapabilities = new Set(CATALOG.filter(({ id }) => ids.includes(id)).map(({ id }) => id));
+    const selectedResources = new Set(ids.filter((id) => id.includes("/")));
+    const resources = CATALOG.flatMap(({ id, resources }) => selectedCapabilities.has(id)
+        ? resources
+        : resources.filter(({ type, id: resourceId }) => selectedResources.has(`${type}/${resourceId}`)));
     return [
         ...new Map(resources.map((resource) => [`${resource.type}/${resource.id}`, resource])).values(),
     ];
 }
 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    evidence: [${item.evidence.map((evidence) => `"${evidence}"`).join(", ")}]\n    rationale: ${item.rationale}`)
+        .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
+        .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}`)
         .join("\n")}\n`;
 }
 function hasProjectSignals(profile) {
@@ -182,7 +233,15 @@ function hasProjectSignals(profile) {
         profile.quality.linter ||
         profile.ci.length);
 }
-function projectEvidence(profile) {
+function projectEvidence(profile, framework) {
+    const moduleEvidence = (profile.modules ?? [])
+        .filter((module) => !framework || module.frameworks.includes(framework))
+        .flatMap((module) => [
+        `workspace:${module.path}`,
+        ...module.frameworks.map((name) => `framework:${name}`),
+        ...(module.testing ? [`testing:${module.testing.name}`] : []),
+        ...(module.testing?.command ? [`test-command:${module.testing.command}`] : []),
+    ]);
     return [
         ...profile.runtime.languages.map((language) => `language:${language}`),
         ...profile.frameworks.map((framework) => `framework:${framework}`),
@@ -190,5 +249,6 @@ function projectEvidence(profile) {
         ...(profile.testing ? [`testing:${profile.testing.name}`] : []),
         ...(profile.quality.linter ? [`linter:${profile.quality.linter.name}`] : []),
         ...(profile.ci.length ? profile.ci.map((system) => `ci:${system}`) : []),
+        ...moduleEvidence,
     ];
 }

package/dist/selection.js

@@ -1,6 +1,12 @@
 export async function selectRecommendations(items, answer, selectedIds) {
+    const available = new Set(items.flatMap((item) => [
+        item.id,
+        ...(item.resources ?? []).map(({ type, id }) => `${type}/${id}`),
+    ]));
+    if (selectedIds?.includes("all"))
+        return items.map(({ id }) => id);
     if (selectedIds)
-        return selectedIds.filter((id) => items.some((item) => item.id === id));
+        return [...new Set(selectedIds.filter((id) => available.has(id)))];
     const selected = [];
     for (const item of items) {
         const response = (await answer(`Install ${item.id}? [Y/n] `)).trim().toLowerCase();

package/dist/workflow.js

@@ -290,7 +290,7 @@ export async function runCommand(args, root, fs, services = {}) {
             const evidence = profile.facts
                 .map((fact) => `  - key: ${fact.key}\n    value: ${fact.value}\n    state: ${fact.state}\n    method: ${fact.method}\n    confidence: ${fact.confidence}${fact.requiresConfirmation === undefined ? "" : `\n    requires_confirmation: ${fact.requiresConfirmation}`}\n    evidence: [${fact.evidence.map((item) => `"${item.source}"`).join(", ")}]`)
                 .join("\n");
-            fs.write(join(aiw, "profile.yml"), `schema: 1\nstatus: scanned\nfacts:\n${evidence}\nruntime:\n  languages: [${profile.runtime.languages.join(", ")}]\nframeworks: [${profile.frameworks.join(", ")}]\npackage_manager: ${profile.packageManager}\nquality:\n  linter: ${profile.quality.linter?.name ?? "unknown"}\n  linter_command: ${profile.quality.linter?.command ?? "unknown"}\n  formatter: ${profile.quality.formatter?.name ?? "unknown"}\n  formatter_command: ${profile.quality.formatter?.command ?? "unknown"}\n  typecheck: ${profile.quality.typecheck?.name ?? "unknown"}\n  typecheck_command: ${profile.quality.typecheck?.command ?? "unknown"}\ntesting: ${profile.testing?.name ?? "unknown"}\ntesting_command: ${profile.testing?.command ?? "unknown"}\nci: [${profile.ci.join(", ")}]\nworkspaces: [${profile.workspaces.join(", ")}]\npolicies:\n  artifact_language: en\n`);
+            fs.write(join(aiw, "profile.yml"), `schema: 1\nstatus: scanned\nfacts:\n${evidence}\nruntime:\n  languages: [${profile.runtime.languages.join(", ")}]\nframeworks: [${profile.frameworks.join(", ")}]\npackage_manager: ${profile.packageManager}\nquality:\n  linter: ${profile.quality.linter?.name ?? "unknown"}\n  linter_command: ${profile.quality.linter?.command ?? "unknown"}\n  formatter: ${profile.quality.formatter?.name ?? "unknown"}\n  formatter_command: ${profile.quality.formatter?.command ?? "unknown"}\n  typecheck: ${profile.quality.typecheck?.name ?? "unknown"}\n  typecheck_command: ${profile.quality.typecheck?.command ?? "unknown"}\ntesting: ${profile.testing?.name ?? "unknown"}\ntesting_command: ${profile.testing?.command ?? "unknown"}\nci: [${profile.ci.join(", ")}]\nworkspaces: [${profile.workspaces.join(", ")}]\nproject_modules: ${JSON.stringify(profile.modules ?? [])}\npolicies:\n  artifact_language: en\n`);
             return { exitCode: 0, output: "Project profile generated." };
         }
         if (command === "target") {
@@ -1630,7 +1630,19 @@ function syncSelectedResources(fs, root, aiw, profile, selected) {
     };
 }
 function personalizeBundledResource(type, id, content, profile) {
-    if (type !== "rules" || !["quality-gates", "tdd-policy", "dependency-policy"].includes(id))
+    const contextual = (type === "rules" &&
+        [
+            "quality-gates",
+            "tdd-policy",
+            "dependency-policy",
+            "architecture-policy",
+            "data-access-policy",
+        ].includes(id)) ||
+        (type === "skills" &&
+            ["nestjs-development", "prisma-data-access", "vite-frontend"].includes(id)) ||
+        (type === "agents" &&
+            ["technical-architect", "typescript-engineer", "nestjs-engineer", "prisma-engineer"].includes(id));
+    if (!contextual)
         return content;
     const signals = [
         profile.runtime.languages.length ? `- Languages: ${profile.runtime.languages.join(", ")}` : "",
@@ -1647,6 +1659,24 @@ function personalizeBundledResource(type, id, content, profile) {
         profile.quality.formatter?.command
             ? `- Format command: \`${safeProjectSignal(profile.quality.formatter.command)}\``
             : "",
+        ...(profile.modules ?? []).map((module) => {
+            const parts = [
+                module.name
+                    ? `${safeProjectSignal(module.name)} (${safeProjectSignal(module.path)})`
+                    : safeProjectSignal(module.path),
+                module.frameworks.length ? `frameworks: ${module.frameworks.join(", ")}` : "",
+                ...(module.architecture ?? []).map((item) => `architecture: ${safeProjectSignal(item)}`),
+                ...(module.patterns ?? []).map((item) => `patterns: ${safeProjectSignal(item)}`),
+                module.testing
+                    ? `tests: ${module.testing.name}${module.testing.command ? ` (${safeProjectSignal(module.testing.command)})` : ""}`
+                    : "",
+                module.quality.linter
+                    ? `linter: ${module.quality.linter.name}${module.quality.linter.command ? ` (${safeProjectSignal(module.quality.linter.command)})` : ""}`
+                    : "",
+            ].filter(Boolean);
+            const evidence = (module.evidence ?? []).slice(0, 8).map(safeProjectSignal);
+            return `- Module ${parts.join("; ")}${evidence.length ? `; evidence: ${evidence.join(", ")}` : ""}`;
+        }),
     ].filter(Boolean);
     return signals.length
         ? `${content.trimEnd()}\n\n## Detected project context\n\n${signals.join("\n")}\n`
@@ -1666,11 +1696,20 @@ function readSelectedRecommendations(fs, aiw) {
     if (!fs.exists(join(aiw, "recommendations.yml")))
         return [];
     const content = fs.read(join(aiw, "recommendations.yml"));
-    return content
+    const selections = content
         .split(/^\s{2}- id: /m)
         .slice(1)
-        .filter((block) => block.includes("selected: true"))
-        .map((block) => block.split("\n", 1)[0].trim());
+        .flatMap((block) => {
+        const id = block.split("\n", 1)[0].trim();
+        const selectedCapability = /^\s{4}selected: true$/m.test(block) ? [id] : [];
+        const selectedResources = block
+            .match(/^\s{4}selected_resources: \[([^\]]*)\]$/m)?.[1]
+            ?.split(",")
+            .map((resource) => resource.trim())
+            .filter(Boolean) ?? [];
+        return [...selectedCapability, ...selectedResources];
+    });
+    return [...new Set(selections)];
 }
 function parseApprovedPermissions(args) {
     return args

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

@@ -0,0 +1,45 @@
+# AI Init Project Onboarding Specification
+
+## Goal
+
+Make `/ai-init` a guided, evidence-backed onboarding flow. The initial `npx` install remains a small bootstrap; `/ai-init` analyzes the repository, recommends project-matched capabilities, gets an explicit selection, installs only that selection, and reports any restart needed to load it.
+
+## 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 wants to continue with the current model. Explain that repository analysis is read-only until resource selection.
+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.
+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
+
+- Bootstrap installation alone must not activate optional project resources.
+- Analysis agents must be read-only and must not inspect ignored, generated, dependency, secret, or credential files.
+- The orchestrator treats agent output as untrusted evidence, checks paths and key findings against the repository, and does not merge unsupported claims into project policy.
+- 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.
+
+## Acceptance criteria
+
+- **AIINIT-001:** A fresh install writes only the `ai-init` bootstrap and neutral AI Workflow state.
+- **AIINIT-002:** The bootstrap asks about using a lower-cost model before analysis and never changes model settings itself.
+- **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-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.
+
+## Delivery slices
+
+1. Bootstrap orchestration, host-native selection, model-cost prompt, and completion/reload guidance.
+2. Deterministic monorepo profiles, stack-specific capability recommendations, resource-level selection, and context-aware sync.
+3. MCP catalog provenance, per-target project configuration/merge support, credential placeholders, ownership, and config validation.

package/docs/product-requirements.md

@@ -24,6 +24,7 @@
 - Selected resources must be customized using confirmed project facts.
 - `/ai-init` must orchestrate scan → recommendations → user selection → selected-resource sync and summarize what it added.
 - The bootstrap must invoke CLI operations through the package runner; it cannot assume `aiw` is installed globally or in the consuming project's dependencies.
+- The complete onboarding behavior and acceptance criteria are defined in [`ai-init-workflow-spec.md`](./ai-init-workflow-spec.md).
 
 ### Development workflow
 

package/package.json

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

package/resources/agents/nestjs-engineer.md

@@ -0,0 +1,3 @@
+# NestJS Engineer
+
+Analyze the target NestJS module and its tests before proposing changes. Report relevant controllers, providers, dependency-injection relationships, DTO validation, and module boundaries with file evidence. Implement only within the assigned scope, preserve existing patterns, and return changed paths plus the exact workspace checks run. Do not access secrets or run migrations.

package/resources/agents/prisma-engineer.md

@@ -0,0 +1,3 @@
+# Prisma Engineer
+
+Inspect the active Prisma schema, generated-client usage, migrations, and data-access tests. Explain the impact of proposed schema/query changes and preserve the project's transaction and migration conventions. Never reset, migrate, or access a database without explicit approval. Return evidence paths, changed paths, and workspace-scoped validation results; do not include connection strings or credentials.

package/resources/package.yaml

@@ -28,6 +28,9 @@ resources:
     - { id: documentation-maintenance, version: 0.1.0, path: skills/documentation-maintenance.md }
     - { id: adapter-development, version: 0.1.0, path: skills/adapter-development.md }
     - { id: skill-authoring, version: 0.1.0, path: skills/skill-authoring.md }
+    - { id: nestjs-development, version: 0.1.0, path: skills/nestjs-development.md }
+    - { id: prisma-data-access, version: 0.1.0, path: skills/prisma-data-access.md }
+    - { id: vite-frontend, version: 0.1.0, path: skills/vite-frontend.md }
   rules:
     - { id: language-policy, version: 0.1.0, path: rules/language-policy.md }
     - { id: tdd-policy, version: 0.1.0, path: rules/tdd-policy.md }
@@ -39,6 +42,7 @@ resources:
     - { id: documentation-policy, version: 0.1.0, path: rules/documentation-policy.md }
     - { id: self-validation, version: 0.1.0, path: rules/self-validation.md }
     - { id: completion-validation, version: 0.1.0, path: rules/completion-validation.md }
+    - { id: data-access-policy, version: 0.1.0, path: rules/data-access-policy.md }
   agents:
     - { id: requirements-analyst, version: 0.1.0, path: agents/requirements-analyst.md }
     - { id: technical-architect, version: 0.1.0, path: agents/technical-architect.md }
@@ -48,6 +52,8 @@ resources:
     - { id: security-reviewer, version: 0.1.0, path: agents/security-reviewer.md }
     - { id: adapter-engineer, version: 0.1.0, path: agents/adapter-engineer.md }
     - { id: documentation-writer, version: 0.1.0, path: agents/documentation-writer.md }
+    - { id: nestjs-engineer, version: 0.1.0, path: agents/nestjs-engineer.md }
+    - { id: prisma-engineer, version: 0.1.0, path: agents/prisma-engineer.md }
   hooks:
     - { id: pre-implementation, version: 0.1.0, path: hooks/pre-implementation.md }
     - { id: post-implementation, version: 0.1.0, path: hooks/post-implementation.md }
@@ -66,8 +72,62 @@ resources:
     - { id: security-review, version: 0.1.0, path: templates/security-review.md }
     - { id: migration-report, version: 0.1.0, path: templates/migration-report.md }
 provides:
-  skills: [project-init, brainstorming, requirements-specification, technical-design, implementation-planning, tdd-development, verification, code-review, security-review, documentation-maintenance, adapter-development, skill-authoring]
-  rules: [language-policy, tdd-policy, architecture-policy, quality-gates, security-policy, dependency-policy, generated-files, documentation-policy, self-validation, completion-validation]
-  agents: [requirements-analyst, technical-architect, typescript-engineer, test-engineer, quality-reviewer, security-reviewer, adapter-engineer, documentation-writer]
+  skills:
+    [
+      project-init,
+      brainstorming,
+      requirements-specification,
+      technical-design,
+      implementation-planning,
+      tdd-development,
+      verification,
+      code-review,
+      security-review,
+      documentation-maintenance,
+      adapter-development,
+      skill-authoring,
+      nestjs-development,
+      prisma-data-access,
+      vite-frontend,
+    ]
+  rules:
+    [
+      language-policy,
+      tdd-policy,
+      architecture-policy,
+      quality-gates,
+      security-policy,
+      dependency-policy,
+      generated-files,
+      documentation-policy,
+      self-validation,
+      completion-validation,
+      data-access-policy,
+    ]
+  agents:
+    [
+      requirements-analyst,
+      technical-architect,
+      typescript-engineer,
+      test-engineer,
+      quality-reviewer,
+      security-reviewer,
+      adapter-engineer,
+      documentation-writer,
+      nestjs-engineer,
+      prisma-engineer,
+    ]
   hooks: [pre-implementation, post-implementation, pre-commit, post-change, pre-release]
-  templates: [brainstorm, specification, technical-design, decision-record, implementation-plan, task, test-plan, verification-report, security-review, migration-report]
+  templates:
+    [
+      brainstorm,
+      specification,
+      technical-design,
+      decision-record,
+      implementation-plan,
+      task,
+      test-plan,
+      verification-report,
+      security-review,
+      migration-report,
+    ]

package/resources/rules/data-access-policy.md

@@ -0,0 +1,7 @@
+# Data Access Policy
+
+- Follow the repository's existing data-access and transaction boundaries.
+- Scope commands and tests to the workspace that owns the database schema or query.
+- Review migration contents before applying them; never run destructive database commands without explicit approval.
+- Keep credentials in the project's approved secret store or environment, never in source, logs, or generated AI instructions.
+- Validate data-access changes with relevant tests and report any migration or compatibility impact.

package/resources/skills/nestjs-development.md

@@ -0,0 +1,8 @@
+---
+name: nestjs-development
+description: Implement and review NestJS services using the repository's module boundaries and conventions.
+---
+
+# NestJS Development
+
+Inspect the relevant NestJS module before editing. Follow the project's established controller, provider, dependency-injection, guard, pipe, interceptor, and DTO patterns; do not introduce a new architectural layer without evidence or approval. Keep transport concerns in controllers and business behavior in the existing service/domain boundaries. Validate external input with the project's configured validation approach. Add focused unit or integration tests using the test runner configured for this workspace, and run that workspace's declared quality commands.

package/resources/skills/prisma-data-access.md

@@ -0,0 +1,8 @@
+---
+name: prisma-data-access
+description: Change Prisma schemas and data access safely within the repository's database conventions.
+---
+
+# Prisma Data Access
+
+Read the active Prisma schema, client setup, existing migrations, and callers before changing data access. Preserve naming, relation, transaction, and repository patterns already used by the project. Do not apply migrations, reset databases, or run destructive commands without explicit approval. When schema changes are selected, explain migration impact, add or update tests around affected queries, and use the exact Prisma and test commands declared by the relevant workspace. Never copy connection strings or credentials into generated instructions.

package/resources/skills/vite-frontend.md

@@ -0,0 +1,8 @@
+---
+name: vite-frontend
+description: Build and verify Vite frontends using the repository's framework, module, and test conventions.
+---
+
+# Vite Frontend
+
+Inspect the Vite entry point, framework plugins, route/component structure, and workspace-local scripts before making changes. Follow the existing component, state, styling, accessibility, and API-client patterns. Keep frontend configuration scoped to the correct workspace. Add focused tests with the configured runner and verify the workspace's declared lint, typecheck, and build commands. Do not assume that a root-level command applies to every app in a monorepo.