@multileaf/ai-workflow 0.1.1 → 0.1.3

package/CHANGELOG.md

@@ -4,6 +4,20 @@ All notable changes to this project are documented in this file. The format foll
 
 ## [Unreleased]
 
+## [0.1.3] - 2026-09-12
+
+### Fixed
+
+- Invoke AI Workflow through `npx` in the generated `ai-init` instructions so fresh projects do not need a globally installed `aiw` binary.
+
+## [0.1.2] - 2026-09-12
+
+### Fixed
+
+- Keep first install limited to the `ai-init` bootstrap and neutral AI Workflow state; install optional capabilities only after the project scan and explicit user selection.
+- Materialize only selected skills, rules, agents, hooks, and templates, and personalize supported rules with detected project commands.
+- Allow non-interactive recommendation previews without silently selecting or installing capabilities.
+
 ## [0.1.1] - 2026-09-12
 
 ### Fixed
@@ -36,6 +50,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.1...HEAD
+[Unreleased]: https://github.com/MultiLeaf/aiw/compare/v0.1.3...HEAD
+[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
 [0.1.0]: https://github.com/MultiLeaf/aiw/releases/tag/v0.1.0

package/README.md

@@ -25,13 +25,15 @@ The published package supports Node.js 18 or newer. Full development checks requ
 npx @multileaf/ai-workflow install --target codex
 ```
 
+Then run `/ai-init` in Codex. The bootstrap scans the repository, explains project-specific recommendations, and waits for the user's selections before installing optional resources.
+
 Supported targets are `codex`, `claude`, `cursor`, `gemini`, `copilot`, and `universal`. Every command uses the same entry point:
 
 ```bash
 npx @multileaf/ai-workflow <command> <options>
 ```
 
-The initial installation creates workflow state and a target-specific `ai-init` skill. Run it in a repository that does not already use the reserved paths shown below: first installation currently writes the base ADR index and target `ai-init` file at those paths. Reinstallation detects existing AI Workflow state and preserves it.
+The initial installation creates workflow state and a target-specific `ai-init` skill. Run it in a repository that does not already use the reserved bootstrap paths shown below: first installation currently writes the base ADR index and target `ai-init` file at those paths. Reinstallation detects existing AI Workflow state and preserves it.
 
 ## What gets created
 
@@ -40,15 +42,7 @@ For a Codex installation, the base layout is:
 ```text
 .agents/
 └── skills/
-    ├── ai-init/SKILL.md
-    ├── brainstorming/SKILL.md
-    ├── requirements-specification/SKILL.md
-    ├── tdd-development/SKILL.md
-    └── ...
-.agents/agents/       # specialist agent definitions
-.agents/hooks/        # lifecycle guidance and compatibility resources
-.agents/rules/        # quality, security, and project rules
-.agents/templates/    # SDD artifact templates
+    └── ai-init/SKILL.md
 .context/
 └── adrs/
     └── INDEX.md
@@ -65,9 +59,9 @@ For a Codex installation, the base layout is:
 └── profile.yml
 ```
 
-`.aiw/` stores the provider-neutral manifest, profile, lockfile, checkpoints, and generated working artifacts. ADRs are stored under `.context/adrs/`. The initial `ai-init` resource is rendered directly to the selected target; installed neutral package resources can be rendered through adapters to paths such as `.claude/skills`, `.cursor/rules`, or `.github/copilot-instructions.md`.
+`.aiw/` stores the provider-neutral manifest, profile, lockfile, checkpoints, bootstrap skill, selected resources, and generated working artifacts. ADRs are stored under `.context/adrs/`. The installer intentionally adds only `ai-init` and the base project state.
 
-The installer activates the bundled workflow package for the selected target, including its skills, rules, agents, hooks, and templates. `ai-init` guides the agent through scanning, recommendations, user selection, synchronization, and the SDD gates. Existing conflicting target resources stop first installation with an actionable error; review or move those files before retrying. Hook resources are rendered according to each adapter's native or compatibility support.
+Run `/ai-init` in the selected coding agent to scan the project and review evidence-based recommendations for skills, rules, agents, hooks, and templates. AI Workflow installs only the resources the user selects, then generates project-specific quality guidance from the detected stack and tools. Existing user files are preserved; conflicts are reported instead of overwritten. Hook resources are rendered according to each adapter's native or compatibility support.
 
 The installer does not modify `.gitignore`. Add `.aiw/generated/` yourself if generated specifications, plans, and artifacts should remain local. Versioned files under `.aiw/checkpoints/` are designed to remain reviewable project history.
 

package/dist/adapter.js

@@ -36,26 +36,26 @@ description: Initialize AI Workflow and run its specification-driven development
 
 # AI Workflow Initialization
 
-Set up the repository's AI-assisted development workflow. Do not stop after scanning or writing configuration: activate the installed skills, rules, agents, hooks, and templates, then guide the user through the project gates.
-
-Analyze the repository safely, confirm uncertain facts, and recommend project-specific capabilities.
+This skill is the bootstrap for AI Workflow. The installer intentionally installs only this skill and the provider-neutral project state. Do not copy or activate the full resource package automatically.
 
 ## First-run setup
 
-1. Inspect the repository and existing AI instructions. Preserve user-authored files and ask before replacing conflicts.
-2. Run \`aiw scan\` and review detected facts and evidence. Confirm uncertain inferences with the user before treating them as project policy.
-3. Run \`aiw recommend\`. Explain each recommendation and its permissions, then install only the capabilities the user selects. Do not approve network or shell permissions implicitly.
-4. Run \`aiw sync\` to generate the selected project-specific resources. Resolve drift or conflicts with the user instead of overwriting them.
-5. Show the available workflow resources and explain how to use them: brainstorming → specification → architecture decision when needed → implementation plan → implementation with tests → verification → traceability → review.
-6. Before advancing each stage, run its matching \`aiw gate <stage>\`. Record validation evidence with \`aiw verify\` and link requirements, decisions, tasks, code, tests, and evidence with \`aiw trace\`.
+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.
+
+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.
 
-## For each feature request
+## 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 \`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 \`aiw gate plan\` before coding.
+- 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 \`aiw verify\`, \`aiw trace\`, and the review gate. Do not claim completion without evidence.
+- 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.
 
 ## Language policy
 

package/dist/{bootstrap-resources.d.ts → bundled-resources.d.ts}

@@ -6,4 +6,4 @@ export type BootstrapResource = {
     path: string;
     content: string;
 };
-export declare function loadBootstrapResources(target: Target): BootstrapResource[];
+export declare function loadBundledResources(target: Target): BootstrapResource[];

package/dist/{bootstrap-resources.js → bundled-resources.js}

@@ -4,7 +4,7 @@ import { fileURLToPath } from "node:url";
 import { renderResourcePath } from "./adapter.js";
 import { RESOURCE_TYPES, validatePackageContract } from "./package-contract.js";
 const resourceRoot = resolve(dirname(fileURLToPath(import.meta.url)), "../resources");
-export function loadBootstrapResources(target) {
+export function loadBundledResources(target) {
     const manifestPath = join(resourceRoot, "package.yaml");
     const manifest = readFileSync(manifestPath, "utf8");
     const contract = validatePackageContract(manifest, (path) => {

package/dist/generator.js

@@ -1,8 +1,8 @@
 import { resolveGeneratedPath } from "./drift.js";
 export function generateProjectResources(profile, selected, write) {
-    const linterCommand = profile.quality.linter?.command;
-    const formatterCommand = profile.quality.formatter?.command;
-    const testCommand = profile.testing?.command;
+    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"))
         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"))
@@ -14,3 +14,13 @@ export function generateProjectResources(profile, selected, write) {
         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`);
     }
 }
+function safeInlineValue(value) {
+    return value
+        ?.split("")
+        .map((character) => character.charCodeAt(0) < 32 || character.charCodeAt(0) === 127 || character === "`"
+        ? " "
+        : character)
+        .join("")
+        .replace(/\s+/g, " ")
+        .slice(0, 180);
+}

package/dist/recommendations.d.ts

@@ -1,4 +1,9 @@
 import type { ProjectProfile } from "./profile.js";
+import type { ResourceType } from "./package-contract.js";
+export type RecommendedResource = {
+    type: ResourceType;
+    id: string;
+};
 export type CapabilityRecommendation = {
     id: string;
     provider: string;
@@ -7,6 +12,8 @@ export type CapabilityRecommendation = {
     evidence: string[];
     permissions: string[];
     conflicts: string[];
+    resources: RecommendedResource[];
 };
 export declare function recommendCapabilities(profile: ProjectProfile): CapabilityRecommendation[];
+export declare function resourcesForCapabilities(ids: string[]): RecommendedResource[];
 export declare function serializeRecommendations(items: CapabilityRecommendation[], selected?: string[]): string;

package/dist/recommendations.js

@@ -1,8 +1,73 @@
+const local = (resources) => resources;
 const CATALOG = [
+    {
+        id: "brainstorming",
+        provider: "multileaf",
+        rationale: "A project-specific brainstorming flow helps clarify goals and constraints before implementation.",
+        permissions: [],
+        resources: local([
+            { type: "skills", id: "brainstorming" },
+            { type: "rules", id: "language-policy" },
+            { type: "templates", id: "brainstorm" },
+        ]),
+        matches: (profile) => hasProjectSignals(profile)
+            ? { evidence: projectEvidence(profile), confidence: 0.92 }
+            : undefined,
+    },
+    {
+        id: "requirements-specification",
+        provider: "multileaf",
+        rationale: "The project can use explicit requirements and acceptance criteria before changes are planned.",
+        permissions: [],
+        resources: local([
+            { type: "skills", id: "requirements-specification" },
+            { type: "agents", id: "requirements-analyst" },
+            { type: "templates", id: "specification" },
+        ]),
+        matches: (profile) => hasProjectSignals(profile)
+            ? { evidence: projectEvidence(profile), confidence: 0.9 }
+            : undefined,
+    },
+    {
+        id: "implementation-planning",
+        provider: "multileaf",
+        rationale: "A traceable implementation plan can connect project requirements, tests, risks, and validation.",
+        permissions: [],
+        resources: local([
+            { type: "skills", id: "implementation-planning" },
+            { type: "agents", id: "technical-architect" },
+            { type: "templates", id: "implementation-plan" },
+        ]),
+        matches: (profile) => hasProjectSignals(profile)
+            ? { evidence: projectEvidence(profile), confidence: 0.88 }
+            : undefined,
+    },
+    {
+        id: "code-review",
+        provider: "multileaf",
+        rationale: "A consistent review checklist helps validate changes against this repository's conventions.",
+        permissions: [],
+        resources: local([
+            { type: "skills", id: "code-review" },
+            { type: "agents", id: "quality-reviewer" },
+        ]),
+        matches: (profile) => profile.runtime.languages.length
+            ? { evidence: projectEvidence(profile), confidence: 0.86 }
+            : undefined,
+    },
     {
         id: "tdd-development",
         provider: "multileaf",
-        rationale: "The project uses automated tests and should preserve test-first development.",
+        rationale: "The project uses automated tests and can apply test-first development with its existing runner.",
+        permissions: [],
+        resources: local([
+            { type: "skills", id: "tdd-development" },
+            { type: "rules", id: "tdd-policy" },
+            { type: "agents", id: "test-engineer" },
+            { type: "hooks", id: "pre-implementation" },
+            { type: "hooks", id: "post-implementation" },
+            { type: "templates", id: "test-plan" },
+        ]),
         matches: (profile) => profile.testing
             ? { evidence: [`testing:${profile.testing.name}`], confidence: 1 }
             : undefined,
@@ -10,7 +75,12 @@ const CATALOG = [
     {
         id: "typescript-quality",
         provider: "multileaf",
-        rationale: "TypeScript is present and benefits from strict, maintainable code-quality rules.",
+        rationale: "TypeScript is detected; add its specialist and tailor quality guidance to the repository's tools.",
+        permissions: [],
+        resources: local([
+            { type: "agents", id: "typescript-engineer" },
+            { type: "rules", id: "quality-gates" },
+        ]),
         matches: (profile) => profile.runtime.languages.includes("typescript")
             ? { evidence: ["language:typescript"], confidence: 1 }
             : undefined,
@@ -18,7 +88,14 @@ const CATALOG = [
     {
         id: "vitest-testing",
         provider: "multileaf",
-        rationale: "Vitest is configured and can be integrated into the verification workflow.",
+        rationale: "Vitest is configured and can be used by the verification skill and test specialist.",
+        permissions: [],
+        resources: local([
+            { type: "skills", id: "verification" },
+            { type: "agents", id: "test-engineer" },
+            { type: "templates", id: "test-plan" },
+            { type: "templates", id: "verification-report" },
+        ]),
         matches: (profile) => profile.testing?.name === "vitest"
             ? { evidence: ["testing:vitest"], confidence: 1 }
             : undefined,
@@ -26,7 +103,14 @@ const CATALOG = [
     {
         id: "react-best-practices",
         provider: "vercel-skills",
-        rationale: "React is detected; framework-specific guidance can improve component design and performance.",
+        rationale: "React is detected; framework guidance can improve component design and performance.",
+        permissions: ["network:external"],
+        resources: local([
+            { type: "skills", id: "technical-design" },
+            { type: "agents", id: "technical-architect" },
+            { type: "rules", id: "architecture-policy" },
+            { type: "templates", id: "technical-design" },
+        ]),
         matches: (profile) => profile.frameworks.includes("react")
             ? { evidence: ["framework:react"], confidence: 1 }
             : undefined,
@@ -34,11 +118,34 @@ const CATALOG = [
     {
         id: "nextjs-development",
         provider: "multileaf",
-        rationale: "Next.js is detected; project-specific conventions can guide routing and rendering decisions.",
+        rationale: "Next.js is detected; architecture guidance can follow the project's framework conventions.",
+        permissions: [],
+        resources: local([
+            { type: "skills", id: "technical-design" },
+            { type: "agents", id: "technical-architect" },
+            { type: "rules", id: "architecture-policy" },
+            { type: "templates", id: "technical-design" },
+        ]),
         matches: (profile) => profile.frameworks.includes("nextjs")
             ? { evidence: ["framework:nextjs"], confidence: 1 }
             : undefined,
     },
+    {
+        id: "security-review",
+        provider: "multileaf",
+        rationale: "The detected stack and package tooling benefit from project-aware security and dependency review.",
+        permissions: [],
+        resources: local([
+            { type: "skills", id: "security-review" },
+            { type: "rules", id: "security-policy" },
+            { type: "rules", id: "dependency-policy" },
+            { type: "agents", id: "security-reviewer" },
+            { type: "templates", id: "security-review" },
+        ]),
+        matches: (profile) => hasProjectSignals(profile)
+            ? { evidence: projectEvidence(profile), confidence: 0.83 }
+            : undefined,
+    },
 ];
 export function recommendCapabilities(profile) {
     return CATALOG.flatMap((capability) => {
@@ -46,18 +153,42 @@ export function recommendCapabilities(profile) {
         return match
             ? [
                 {
-                    id: capability.id,
-                    provider: capability.provider,
+                    ...capability,
                     confidence: match.confidence,
-                    rationale: capability.rationale,
                     evidence: match.evidence,
-                    permissions: capability.permissions ?? [],
                     conflicts: [],
                 },
             ]
             : [];
     });
 }
+export function resourcesForCapabilities(ids) {
+    const selected = new Set(ids);
+    const resources = CATALOG.filter(({ id }) => selected.has(id)).flatMap(({ resources }) => resources);
+    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    evidence: [${item.evidence.map((evidence) => `"${evidence}"`).join(", ")}]\n    rationale: ${item.rationale}`).join("\n")}\n`;
+    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}`)
+        .join("\n")}\n`;
+}
+function hasProjectSignals(profile) {
+    return Boolean(profile.runtime.languages.length ||
+        profile.frameworks.length ||
+        profile.packageManager !== "unknown" ||
+        profile.testing ||
+        profile.quality.linter ||
+        profile.ci.length);
+}
+function projectEvidence(profile) {
+    return [
+        ...profile.runtime.languages.map((language) => `language:${language}`),
+        ...profile.frameworks.map((framework) => `framework:${framework}`),
+        ...(profile.packageManager === "unknown" ? [] : [`package-manager:${profile.packageManager}`]),
+        ...(profile.testing ? [`testing:${profile.testing.name}`] : []),
+        ...(profile.quality.linter ? [`linter:${profile.quality.linter.name}`] : []),
+        ...(profile.ci.length ? profile.ci.map((system) => `ci:${system}`) : []),
+    ];
 }

package/dist/workflow.js

@@ -1,14 +1,14 @@
 import { basename, dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
 import { BASE_DIRECTORIES, WORKFLOW_DIRECTORY } from "./constants.js";
 import { detectTarget, isTarget, renderAiInit, renderAiInitPath, renderResourcePath, } from "./adapter.js";
-import { loadBootstrapResources } from "./bootstrap-resources.js";
+import { loadBundledResources } from "./bundled-resources.js";
 import { assertSafeProjectPath, withSafeProjectWrites, writeProjectFilesAtomically, } from "./files.js";
 import { parseProjectProfile, profileProject } from "./profile.js";
 import { serializeOverrides } from "./confirmation.js";
 import { applyOverrides, parseOverrides } from "./confirmation.js";
 import { mergeFacts } from "./intelligence.js";
 import { createInterpretationRequest } from "./interpreter.js";
-import { recommendCapabilities, serializeRecommendations } from "./recommendations.js";
+import { recommendCapabilities, resourcesForCapabilities, serializeRecommendations, } from "./recommendations.js";
 import { selectRecommendations } from "./selection.js";
 import { createInterface } from "node:readline/promises";
 import { stdin, stdout } from "node:process";
@@ -124,28 +124,26 @@ export async function runCommand(args, root, fs, services = {}) {
                     output: `AI Workflow is already installed for target: ${active}. Existing state preserved.`,
                 };
             }
-            const bootstrapResources = loadBootstrapResources(target);
-            const desiredResources = new Map();
+            const aiInitPath = join(root, renderAiInitPath(target));
+            const neutralAiInitPath = join(aiw, "resources/skills/ai-init.md");
+            const aiInitContent = renderAiInit(target);
+            const desiredResources = new Map([[aiInitPath, aiInitContent]]);
             const ownershipMetadata = new Map();
-            bootstrapResources.forEach(({ type, id, path, content }) => {
-                const targetPath = join(root, path);
-                const neutralPath = join(root, renderResourcePath("universal", type, id));
-                desiredResources.set(targetPath, content);
-                desiredResources.set(neutralPath, content);
-                ownershipMetadata.set(neutralPath, {
+            ownershipMetadata.set(aiInitPath, {
+                kind: "ai-init",
+                target,
+                resourceType: "skills",
+                resourceId: "ai-init",
+            });
+            if (neutralAiInitPath !== aiInitPath) {
+                desiredResources.set(neutralAiInitPath, aiInitContent);
+                ownershipMetadata.set(neutralAiInitPath, {
                     kind: "neutral-resource",
                     target: "universal",
-                    resourceType: type,
-                    resourceId: id,
+                    resourceType: "skills",
+                    resourceId: "ai-init",
                 });
-                if (targetPath !== neutralPath)
-                    ownershipMetadata.set(targetPath, {
-                        kind: "target-resource",
-                        target,
-                        resourceType: type,
-                        resourceId: id,
-                    });
-            });
+            }
             const conflicts = [];
             const pendingWrites = new Map();
             const inspectDesiredFile = (path, content, allowExisting = false) => {
@@ -161,19 +159,6 @@ export async function runCommand(args, root, fs, services = {}) {
             };
             for (const [path, content] of desiredResources)
                 inspectDesiredFile(path, content);
-            if (conflicts.length)
-                return {
-                    exitCode: 1,
-                    error: `Installation found existing target resources: ${conflicts.join(", ")}. Review and move them before retrying.`,
-                };
-            const aiInitPath = join(root, renderAiInitPath(target));
-            ownershipMetadata.set(aiInitPath, {
-                kind: "ai-init",
-                target,
-                resourceType: "skills",
-                resourceId: "ai-init",
-            });
-            inspectDesiredFile(aiInitPath, renderAiInit(target));
             if (conflicts.length)
                 return {
                     exitCode: 1,
@@ -195,7 +180,7 @@ export async function runCommand(args, root, fs, services = {}) {
                     exitCode: 1,
                     error: `Installation found conflicting project state: ${conflicts.join(", ")}. Review and move it before retrying.`,
                 };
-            const ownedPaths = new Set([...desiredResources.keys(), aiInitPath]);
+            const ownedPaths = new Set(desiredResources.keys());
             if (pendingWrites.has(adrIndex))
                 ownedPaths.add(adrIndex);
             const ownedFiles = [...ownedPaths]
@@ -207,7 +192,7 @@ export async function runCommand(args, root, fs, services = {}) {
             writeProjectFilesAtomically(fs, root, [...pendingWrites].map(([path, content]) => ({ path, content })), [...BASE_DIRECTORIES.map((directory) => join(aiw, directory)), join(root, ".context/adrs")]);
             return {
                 exitCode: 0,
-                output: `AI Workflow installed for target: ${target}; activated ${bootstrapResources.length} bundled workflow resources. Run the ai-init skill to scan the project, review recommendations, and begin the SDD gates.`,
+                output: `AI Workflow initialized for target: ${target} with only the ai-init skill. Run /ai-init to scan the project and choose which resources to install.`,
             };
         }
         if (command === "telemetry") {
@@ -409,7 +394,10 @@ export async function runCommand(args, root, fs, services = {}) {
                 diagnostics.push({ path: ".aiw/resources/skills/ai-init.md", reason: aiInitDiagnostic });
             const targetAiPath = targetPath;
             resourceDestinations.add(targetAiPath);
-            inspectMigrationDestination(targetAiPath, aiInitBytes);
+            if (targetAiPath === neutralAiInit)
+                fileChanges.set(targetAiPath, aiInitBytes);
+            else
+                inspectMigrationDestination(targetAiPath, aiInitBytes);
             const previousTargetEntries = previousTarget === "universal"
                 ? []
                 : inventory.filter((entry) => (entry.kind === "target-resource" || entry.kind === "ai-init") &&
@@ -667,18 +655,25 @@ export async function runCommand(args, root, fs, services = {}) {
                 return { exitCode: 1, error: "Run `aiw install` first." };
             const profile = await (services.profiler?.profile(root) ?? profileProject(root));
             const recommendations = services.recommender?.recommend(profile) ?? recommendCapabilities(profile);
-            const selectedArg = args.find((arg) => arg.startsWith("--select="))?.split("=", 2)[1];
-            if (!selectedArg && !stdin.isTTY) {
-                return {
-                    exitCode: 1,
-                    error: "Interactive selection requires a TTY. Use --select=id,id in non-interactive environments.",
-                };
+            const selectedOption = args.find((arg) => arg.startsWith("--select="));
+            const selectedArg = selectedOption?.slice("--select=".length) ?? "";
+            let selection;
+            if (selectedOption !== undefined)
+                selection = await selectRecommendations(recommendations, async () => "n", selectedArg ? selectedArg.split(",") : []);
+            else if (!stdin.isTTY)
+                selection = [];
+            else {
+                const terminal = createInterface({ input: stdin, output: stdout });
+                selection = await selectRecommendations(recommendations, (question) => terminal.question(question));
+                terminal.close();
             }
-            const terminal = createInterface({ input: stdin, output: stdout });
-            const selection = await selectRecommendations(recommendations, (question) => terminal.question(question), selectedArg?.split(","));
-            terminal.close();
             fs.write(join(aiw, "recommendations.yml"), serializeRecommendations(recommendations, selection));
-            return { exitCode: 0, output: `${recommendations.length} recommendations generated.` };
+            return {
+                exitCode: 0,
+                output: selectedOption === undefined && !stdin.isTTY
+                    ? `${recommendations.length} recommendations generated without selection; review .aiw/recommendations.yml, then record user choices with --select=id,id.`
+                    : `${recommendations.length} recommendations generated.`,
+            };
         }
         if (command === "skills") {
             if (!fs.exists(join(aiw, "manifest.yml")))
@@ -770,6 +765,12 @@ 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);
@@ -1532,6 +1533,135 @@ function containsCredential(value, credential, visited = new Set()) {
     visited.add(value);
     return Object.values(value).some((entry) => containsCredential(entry, credential, visited));
 }
+function syncSelectedResources(fs, root, aiw, profile, selected) {
+    const target = parseManifest(fs.read(join(aiw, "manifest.yml"))).target.active;
+    const resourceSelections = resourcesForCapabilities(selected);
+    const bundled = loadBundledResources(target);
+    const bundleByKey = new Map(bundled.map((resource) => [`${resource.type}/${resource.id}`, resource]));
+    const desired = new Map();
+    const generatedFiles = new Map();
+    const addOwned = (path, content, metadata) => {
+        const previous = desired.get(path);
+        if (previous && previous.content !== content)
+            throw new Error(`Selected resources render conflicting content at ${path}`);
+        desired.set(path, { content, metadata });
+    };
+    const addResource = (type, id, content) => {
+        const neutralPath = join(root, renderResourcePath("universal", type, id));
+        const targetPath = join(root, renderResourcePath(target, type, id));
+        addOwned(neutralPath, content, {
+            kind: "neutral-resource",
+            target: "universal",
+            resourceType: type,
+            resourceId: id,
+        });
+        if (targetPath !== neutralPath)
+            addOwned(targetPath, content, {
+                kind: "target-resource",
+                target,
+                resourceType: type,
+                resourceId: id,
+            });
+    };
+    for (const reference of resourceSelections) {
+        const key = `${reference.type}/${reference.id}`;
+        const resource = bundleByKey.get(key);
+        if (!resource)
+            return { error: `Bundled resource is unavailable: ${key}` };
+        addResource(reference.type, reference.id, personalizeBundledResource(reference.type, reference.id, resource.content, profile));
+    }
+    generateProjectResources(profile, selected, (path, content) => {
+        generatedFiles.set(join(aiw, path), content);
+        const rule = path.match(/^generated\/rules\/(project-quality|tdd-project-policy)\.md$/);
+        if (rule)
+            addResource("rules", rule[1], content);
+    });
+    const ownershipPath = join(aiw, "ownership.yml");
+    if (fs.pathType?.(ownershipPath) !== "file")
+        return {
+            error: "AI Workflow ownership inventory is missing or unsafe; reinstall before syncing.",
+        };
+    const inventory = parseOwnership(fs.read(ownershipPath));
+    const nextInventory = new Map(inventory.map((entry) => [entry.path, entry]));
+    const changes = [];
+    const conflicts = [];
+    for (const [path, { content, metadata }] of desired) {
+        assertSafeProjectPath(fs, root, path);
+        const relativePath = relative(root, path).split(sep).join("/");
+        const type = fs.pathType?.(path);
+        const owned = nextInventory.get(relativePath);
+        if (type === "missing") {
+            changes.push({ path, content: Buffer.from(content, "utf8") });
+            nextInventory.set(relativePath, createOwnedFile(relativePath, content, metadata));
+            continue;
+        }
+        if (type !== "file" || !owned) {
+            conflicts.push(relativePath);
+            continue;
+        }
+        const actual = fs.read(path);
+        if (createOwnedFile(relativePath, actual).checksum !== owned.checksum) {
+            conflicts.push(relativePath);
+            continue;
+        }
+        if (actual !== content)
+            changes.push({ path, content: Buffer.from(content, "utf8") });
+        nextInventory.set(relativePath, createOwnedFile(relativePath, content, metadata));
+    }
+    for (const [path, content] of generatedFiles) {
+        assertSafeProjectPath(fs, root, path);
+        const type = fs.pathType?.(path);
+        if (type === "missing")
+            changes.push({ path, content: Buffer.from(content, "utf8") });
+        else if (type !== "file" || fs.read(path) !== content)
+            conflicts.push(relative(root, path).split(sep).join("/"));
+    }
+    if (conflicts.length)
+        return {
+            error: `Sync preserved existing or modified project resources: ${[...new Set(conflicts)].sort().join(", ")}`,
+        };
+    const nextOwnership = serializeOwnership([...nextInventory.values()]);
+    if (fs.read(ownershipPath) !== nextOwnership)
+        changes.push({ path: ownershipPath, content: Buffer.from(nextOwnership, "utf8") });
+    if (changes.length)
+        applyProjectFileChanges(fs, root, changes);
+    return {
+        output: `Synchronized ${resourceSelections.length} selected bundled resources for ${target} and generated ${generatedFiles.size} project-specific files.`,
+    };
+}
+function personalizeBundledResource(type, id, content, profile) {
+    if (type !== "rules" || !["quality-gates", "tdd-policy", "dependency-policy"].includes(id))
+        return content;
+    const signals = [
+        profile.runtime.languages.length ? `- Languages: ${profile.runtime.languages.join(", ")}` : "",
+        profile.frameworks.length ? `- Frameworks: ${profile.frameworks.join(", ")}` : "",
+        profile.testing ? `- Test runner: ${profile.testing.name}` : "",
+        profile.testing?.command
+            ? `- Test command: \`${safeProjectSignal(profile.testing.command)}\``
+            : "",
+        profile.quality.linter ? `- Linter: ${profile.quality.linter.name}` : "",
+        profile.quality.linter?.command
+            ? `- Lint command: \`${safeProjectSignal(profile.quality.linter.command)}\``
+            : "",
+        profile.quality.formatter ? `- Formatter: ${profile.quality.formatter.name}` : "",
+        profile.quality.formatter?.command
+            ? `- Format command: \`${safeProjectSignal(profile.quality.formatter.command)}\``
+            : "",
+    ].filter(Boolean);
+    return signals.length
+        ? `${content.trimEnd()}\n\n## Detected project context\n\n${signals.join("\n")}\n`
+        : content;
+}
+function safeProjectSignal(value) {
+    return value
+        .split("")
+        .map((character) => character.charCodeAt(0) < 32 || character.charCodeAt(0) === 127 || character === "`"
+        ? " "
+        : character)
+        .join("")
+        .replace(/\s+/g, " ")
+        .slice(0, 180);
+}
 function readSelectedRecommendations(fs, aiw) {
     if (!fs.exists(join(aiw, "recommendations.yml")))
         return [];

package/docs/package-model.md

@@ -26,6 +26,8 @@ package/
 
 Packages may come from local paths, Git repositories, npm-compatible providers, Vercel Skills, or a future Multileaf registry.
 
+The package distributed by AI Workflow is a catalog, not an automatic project install. `aiw install` writes only the target-specific `ai-init` bootstrap and neutral state. `/ai-init` runs CLI commands through `npx --yes --package=@multileaf/ai-workflow -- aiw <command>` because installation does not add a global `aiw` binary or a dependency to the consuming project. It scans the project, recommends matching capabilities, asks which to activate, and syncs only the selected resources. Supported rules and project-quality guidance are personalized from detected project tools; existing or user-edited files are preserved and reported as conflicts.
+
 Local directories and Git repositories are resolved with `aiw resolve --source=<source>`. A local source may be a package directory or its `package.yaml`; relative paths are resolved from the project. Git sources support `git+https`, HTTPS, SSH, and `file://` URLs. Git packages are cloned into an isolated temporary checkout, validated before the lockfile is changed, and removed after resolution. The lockfile records the selected provider and normalized source rather than trusting those fields from the fetched manifest. The legacy `--package=<path>` form remains available for direct manifest resolution.
 
 Vercel Skills is exposed through `aiw skills search`, `inspect`, `install`, `check`, and `update`. AIW delegates to the official `npx skills` CLI with argument arrays, requires explicit `network:external` permission for network-mutating/check operations, and records installed skills and upstream integrity in `.aiw/lock.yml`. Update output is inspected for upstream failure text because some CLI releases may report failures with a successful process exit code.

package/docs/product-requirements.md

@@ -5,6 +5,7 @@
 ### Installation
 
 - The CLI must install with `npx @multileaf/ai-workflow install`.
+- Initial installation must add only the target-specific `ai-init` bootstrap and neutral state; optional skills, rules, agents, hooks, and templates must not be activated before project analysis and user selection.
 - Installation must support Codex, Claude Code, Cursor, Gemini CLI, GitHub Copilot, and a universal target over time.
 - Installation must be idempotent and preserve user overrides.
 - Installation must create a neutral `.aiw/` source of truth.
@@ -21,6 +22,8 @@
 - Recommendations must explain their evidence, capabilities, permissions, and conflicts.
 - The user must select which capabilities to install.
 - 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.
 
 ### Development workflow
 

package/package.json

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