@open-agent-toolkit/cli 0.3.8 → 0.3.9

package/dist/commands/config/index.js

@@ -12,7 +12,7 @@ import { normalizeDispatchMatrix, validateDispatchRouteTarget, walkDispatchMatri
 import { formatDispatchNotices, terminalReviewerNoticesForMatrix, } from '../../config/dispatch-notices.js';
 import { dispatchPolicyModeDescription, dispatchPolicyPolicyDescription, managedDispatchPolicyValueList, } from '../../config/dispatch-policy-options.js';
 import { parseJsonConfig } from '../../config/json.js';
-import { VALID_DISPATCH_POLICY_MODES, VALID_MANAGED_DISPATCH_POLICIES, MAX_GATE_TIMEOUT_MS, MIN_GATE_TIMEOUT_MS, isValidGateTimeoutMs, normalizeWorkflowPostImplementSequence, readOatConfig, readOatConfigForDefaultScopeRepair, readOatConfigForDocumentationExcludesRepair, readOatConfigForInstructionPointerExcludesRepair, readOatConfigWithWarnings, readOatLocalConfig, readUserConfig, writeOatConfig, writeOatLocalConfig, writeUserConfig, VALID_POST_IMPLEMENT_LEGACY_SEQUENCES, } from '../../config/oat-config.js';
+import { DEFAULT_INSTRUCTION_SYNC_STRATEGY, INSTRUCTION_SYNC_STRATEGIES, VALID_DISPATCH_POLICY_MODES, VALID_MANAGED_DISPATCH_POLICIES, MAX_GATE_TIMEOUT_MS, MIN_GATE_TIMEOUT_MS, isValidGateTimeoutMs, normalizeWorkflowPostImplementSequence, readOatConfig, readOatConfigForDefaultScopeRepair, readOatConfigForDocumentationExcludesRepair, readOatConfigForInstructionPointerExcludesRepair, readOatConfigForInstructionSyncStrategyRepair, readOatConfigWithWarnings, readOatLocalConfig, readUserConfig, writeOatConfig, writeOatLocalConfig, writeUserConfig, VALID_POST_IMPLEMENT_LEGACY_SEQUENCES, } from '../../config/oat-config.js';
 import { getOwnKey, setOwnKey } from '../../config/own-keys.js';
 import { resolveEffectiveConfig, resolveEnvOverride, } from '../../config/resolve.js';
 import { resolveAssetsRoot } from '../../fs/assets.js';
@@ -71,13 +71,14 @@ const KEY_ORDER = [
     'documentation.tooling',
     'documentation.config',
     'documentation.excludes',
-    'documentation.instructionPointerExcludes',
     'documentation.requireForProjectCompletion',
     'explainers.defaults.style',
     'explainers.defaults.palette',
     'explainers.defaults.visualProfile',
     'explainers.defaults.themeBundlePath',
     'git.defaultBranch',
+    'instructions.claude.shims',
+    'instructions.claude.excludes',
     'projects.root',
     'projects.defaultScope',
     ...PJM_REMOTE_CONFIG_KEYS,
@@ -200,6 +201,28 @@ const CONFIG_CATALOG = [
         owningCommand: 'oat config set git.defaultBranch <value>',
         description: 'Default branch used by lifecycle PR flows when base branch auto-detection is unavailable.',
     },
+    {
+        key: 'instructions.claude.shims',
+        group: 'Shared Repo (.oat/config.json)',
+        file: '.oat/config.json',
+        scope: 'shared repo',
+        type: 'enum',
+        defaultValue: DEFAULT_INSTRUCTION_SYNC_STRATEGY,
+        mutability: 'read/write',
+        owningCommand: `oat config set instructions.claude.shims <${INSTRUCTION_SYNC_STRATEGIES.join('|')}>`,
+        description: 'How `oat instructions sync` keeps a CLAUDE.md beside each AGENTS.md, and what `oat instructions validate` checks. The `--strategy` flag overrides it for one run.',
+    },
+    {
+        key: 'instructions.claude.excludes',
+        group: 'Shared Repo (.oat/config.json)',
+        file: '.oat/config.json',
+        scope: 'shared repo',
+        type: 'string[]',
+        defaultValue: 'unset',
+        mutability: 'read/write',
+        owningCommand: 'oat config set instructions.claude.excludes <path[,path...]>',
+        description: 'Comma-separated repository-relative directories that `oat instructions sync` and `oat instructions validate` must not treat as pointer sites, additive to the documentation content root they already skip. Absolute paths and paths escaping the repository are rejected; an empty value clears the key.',
+    },
     {
         key: 'autoReviewAtCheckpoints',
         group: 'Shared Repo (.oat/config.json)',
@@ -256,17 +279,6 @@ const CONFIG_CATALOG = [
         owningCommand: 'oat config set documentation.excludes <glob[,glob...]>',
         description: 'Comma-separated globs, relative to the docs directory, excluded from `oat docs generate-index`. Repeated `--exclude` flags extend this list; an empty value clears the key.',
     },
-    {
-        key: 'documentation.instructionPointerExcludes',
-        group: 'Shared Repo (.oat/config.json)',
-        file: '.oat/config.json',
-        scope: 'shared repo',
-        type: 'string[]',
-        defaultValue: 'unset',
-        mutability: 'read/write',
-        owningCommand: 'oat config set documentation.instructionPointerExcludes <path[,path...]>',
-        description: 'Comma-separated repository-relative directories that `oat instructions sync` and `oat instructions validate` must not treat as pointer sites, additive to the documentation content root they already skip. Absolute paths and paths escaping the repository are rejected; an empty value clears the key.',
-    },
     {
         key: 'documentation.requireForProjectCompletion',
         group: 'Shared Repo (.oat/config.json)',
@@ -891,6 +903,7 @@ const DEFAULT_DEPENDENCIES = {
     readOatConfigForDefaultScopeRepair,
     readOatConfigForDocumentationExcludesRepair,
     readOatConfigForInstructionPointerExcludesRepair,
+    readOatConfigForInstructionSyncStrategyRepair,
     readOatConfigWithWarnings,
     writeOatConfig,
     readOatLocalConfig,
@@ -966,7 +979,7 @@ function normalizeSharedRoot(value) {
  * as "clear the key" rather than as an error.
  */
 /**
- * Parse `documentation.instructionPointerExcludes` from one comma-separated
+ * Parse `instructions.claude.excludes` from one comma-separated
  * value into the shape the loader and the consumer already agree on.
  *
  * Every entry goes through `normalizeExcludedPaths`, the same function
@@ -994,7 +1007,7 @@ function parseInstructionPointerExcludes(rawValue) {
         .filter((value) => value.length > 0)) {
         const [normalizedEntry] = normalizeExcludedPaths([entry]);
         if (normalizedEntry === undefined || WINDOWS_DRIVE_PATH_RE.test(entry)) {
-            throw new Error(`Invalid documentation.instructionPointerExcludes entry ${JSON.stringify(entry)}: entries must be repository-relative paths inside the repository. Absolute paths and paths escaping the repository cannot exclude anything.`);
+            throw new Error(`Invalid instructions.claude.excludes entry ${JSON.stringify(entry)}: entries must be repository-relative paths inside the repository. Absolute paths and paths escaping the repository cannot exclude anything.`);
         }
         if (!normalized.includes(normalizedEntry)) {
             normalized.push(normalizedEntry);
@@ -1037,6 +1050,7 @@ function parseExplainerValue(key, rawValue, surface) {
 }
 const WORKFLOW_ENUM_VALUES = {
     'projects.defaultScope': PROJECT_SCOPES,
+    'instructions.claude.shims': INSTRUCTION_SYNC_STRATEGIES,
     'workflow.hillCheckpointDefault': ['every', 'final'],
     'workflow.postImplementSequence': ['wait', 'summary', 'pr', 'docs-pr'],
     'workflow.reviewExecutionModel': ['subagent', 'inline', 'fresh-session'],
@@ -1094,6 +1108,7 @@ function isStructuralKey(key) {
         key === 'worktrees.root' ||
         key === 'git.defaultBranch' ||
         key.startsWith('documentation.') ||
+        key.startsWith('instructions.') ||
         key.startsWith('archive.') ||
         key.startsWith('tools.'));
 }
@@ -1126,7 +1141,7 @@ function validateSurfaceForKey(key, surface) {
     }
     if (isStructuralKey(key)) {
         if (surface !== 'shared') {
-            throw new Error(`Cannot set structural key '${key}' at '${surface}' scope. Structural keys (projects.root, worktrees.root, git.*, documentation.*, archive.*, tools.*) can only be set at shared scope (.oat/config.json).`);
+            throw new Error(`Cannot set structural key '${key}' at '${surface}' scope. Structural keys (projects.root, worktrees.root, git.*, documentation.*, instructions.*, archive.*, tools.*) can only be set at shared scope (.oat/config.json).`);
         }
         return;
     }
@@ -1844,9 +1859,37 @@ async function setConfigValue(repoRoot, userConfigDir, key, rawValue, surface, d
     // would reject the very value the operator is trying to replace.
     const config = key === 'documentation.excludes'
         ? await dependencies.readOatConfigForDocumentationExcludesRepair(repoRoot)
-        : key === 'documentation.instructionPointerExcludes'
+        : key === 'instructions.claude.excludes'
             ? await dependencies.readOatConfigForInstructionPointerExcludesRepair(repoRoot)
-            : await dependencies.readOatConfig(repoRoot);
+            : key === 'instructions.claude.shims'
+                ? await dependencies.readOatConfigForInstructionSyncStrategyRepair(repoRoot)
+                : await dependencies.readOatConfig(repoRoot);
+    if (key.startsWith('instructions.claude.')) {
+        const claude = { ...config.instructions?.claude };
+        if (key === 'instructions.claude.excludes') {
+            const excludes = parseInstructionPointerExcludes(rawValue);
+            if (excludes.length === 0) {
+                delete claude.excludes;
+            }
+            else {
+                claude.excludes = excludes;
+            }
+        }
+        else {
+            claude.shims = parseWorkflowValue(key, rawValue);
+        }
+        await dependencies.writeOatConfig(repoRoot, {
+            ...config,
+            instructions: { ...config.instructions, claude },
+        });
+        return {
+            key,
+            value: key === 'instructions.claude.excludes'
+                ? (claude.excludes ?? null)
+                : (claude.shims ?? null),
+            source: 'shared',
+        };
+    }
     if (key.startsWith('documentation.')) {
         const doc = { ...config.documentation };
         if (key === 'documentation.root') {
@@ -1869,15 +1912,6 @@ async function setConfigValue(repoRoot, userConfigDir, key, rawValue, surface, d
                 doc.excludes = excludes;
             }
         }
-        else if (key === 'documentation.instructionPointerExcludes') {
-            const excludes = parseInstructionPointerExcludes(rawValue);
-            if (excludes.length === 0) {
-                delete doc.instructionPointerExcludes;
-            }
-            else {
-                doc.instructionPointerExcludes = excludes;
-            }
-        }
         else if (key === 'documentation.requireForProjectCompletion') {
             doc.requireForProjectCompletion =
                 rawValue.trim().toLowerCase() === 'true';
@@ -1890,9 +1924,7 @@ async function setConfigValue(repoRoot, userConfigDir, key, rawValue, surface, d
             ? String(doc.requireForProjectCompletion ?? false)
             : key === 'documentation.excludes'
                 ? (doc.excludes ?? null)
-                : key === 'documentation.instructionPointerExcludes'
-                    ? (doc.instructionPointerExcludes ?? null)
-                    : (doc[key.replace('documentation.', '')] ?? null);
+                : (doc[key.replace('documentation.', '')] ?? null);
         return {
             key,
             value: resultValue,
@@ -2095,6 +2127,7 @@ function configPathForKey(key) {
     }
     if (key.startsWith('explainers.') ||
         key.startsWith('documentation.') ||
+        key.startsWith('instructions.') ||
         key.startsWith('archive.') ||
         isPjmRemoteConfigKey(key)) {
         return key.split('.');
@@ -2289,11 +2322,13 @@ async function removeFromSurface(repoRoot, userConfigDir, key, effectiveSurface,
     }
     const sharedConfig = key === 'documentation.excludes'
         ? await dependencies.readOatConfigForDocumentationExcludesRepair(repoRoot)
-        : key === 'documentation.instructionPointerExcludes'
+        : key === 'instructions.claude.excludes'
             ? await dependencies.readOatConfigForInstructionPointerExcludesRepair(repoRoot)
-            : key === 'projects.defaultScope'
-                ? await dependencies.readOatConfigForDefaultScopeRepair(repoRoot)
-                : await dependencies.readOatConfig(repoRoot);
+            : key === 'instructions.claude.shims'
+                ? await dependencies.readOatConfigForInstructionSyncStrategyRepair(repoRoot)
+                : key === 'projects.defaultScope'
+                    ? await dependencies.readOatConfigForDefaultScopeRepair(repoRoot)
+                    : await dependencies.readOatConfig(repoRoot);
     const { next, removed } = removeConfigPath(sharedConfig, path);
     if (removed) {
         await dependencies.writeOatConfig(repoRoot, next);

package/dist/commands/init/index.d.ts

@@ -13,6 +13,7 @@ import type { ConcreteScope } from '../../shared/types.js';
 import { Command } from 'commander';
 import { type DetectedDocs, type DetectDocsDependencies } from './detect-docs.js';
 import { type ToolPack } from './tools/index.js';
+import { type AgentsGuidancePlan } from './tools/project-guidance.js';
 export interface InitStrayCandidate {
     provider: string;
     report: DriftReport;
@@ -76,6 +77,11 @@ interface InitDependencies {
     runGuidedSetup: (context: CommandContext, dependencies: InitDependencies, explicitProjectGuidance?: boolean) => Promise<void>;
     runToolPacks: (context: CommandContext, explicitProjectGuidance?: boolean) => Promise<ToolPack[]>;
     runProviderSync: (projectRoot: string) => Promise<void>;
+    /**
+     * Applies accepted OAT tools guidance for the already-installed packs when
+     * `--project-guidance` is given and guided setup does not run.
+     */
+    applyProjectGuidance: (context: CommandContext, projectRoot: string | null) => Promise<AgentsGuidancePlan>;
 }
 export declare function createInitCommand(overrides?: Partial<InitDependencies>): Command;
 export {};

package/dist/commands/init/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/commands/init/index.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/commands/init/index.ts"],"names":[],"mappings":"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"}

package/dist/commands/init/index.js

@@ -28,8 +28,8 @@ import { getActiveAdapters, getConfigAwareAdapters, getProviderRegistrations, re
 import { getAdoptionSources } from '../../providers/shared/adapter.utils.js';
 import { Command } from 'commander';
 import { detectExistingDocs, } from './detect-docs.js';
-import { createInitToolsCommand, runInitToolsWithDefaults, } from './tools/index.js';
-import { commandProjectGuidanceChoice, withProjectGuidanceOptions, } from './tools/project-guidance.js';
+import { applyProjectGuidanceForInstalledPacks, createInitToolsCommand, runInitToolsWithDefaults, } from './tools/index.js';
+import { commandProjectGuidanceChoice, isProjectGuidanceIncomplete, reportableProjectGuidance, reportProjectGuidancePlan, withProjectGuidanceOptions, } from './tools/project-guidance.js';
 const ADOPT_REMEDIATION = 'Run "oat init" interactively to adopt stray entries.';
 const HOOK_PROMPT = 'Install optional pre-commit hook for drift warnings?';
 const HOOK_CONFIGURE_PROMPT = (hooksPath) => `Configure Git hooks to use ${hooksPath} before installing the OAT hook?`;
@@ -171,6 +171,7 @@ function createDependencies() {
         applyNativeSkillDisposition,
         runGuidedSetup: runGuidedSetupImpl,
         runToolPacks: runInitToolsWithDefaults,
+        applyProjectGuidance: (context, projectRoot) => applyProjectGuidanceForInstalledPacks(context, projectRoot, true),
         async runProviderSync(projectRoot) {
             execSync('oat sync --scope project', {
                 cwd: projectRoot,
@@ -695,6 +696,15 @@ async function runInitCommand(context, dependencies, hookFlag, setupFlag, explic
         });
     }
     const hookInstalled = await maybeHandleHook(context, dependencies, projectRoot, hookFlag);
+    const freshInit = projectRoot !== null && !oatDirExistedBefore;
+    const setupMayRun = !!setupFlag || (context.interactive && freshInit);
+    // Guided setup owns guidance when it runs. Otherwise an explicit
+    // --project-guidance is applied directly for the installed packs, so the
+    // flag is never silently dropped (--no-project-guidance needs no write).
+    let directGuidance = null;
+    if (explicitProjectGuidance === true && !setupMayRun) {
+        directGuidance = await dependencies.applyProjectGuidance(context, projectRoot);
+    }
     if (context.json) {
         const payload = {
             scope: context.scope,
@@ -704,12 +714,14 @@ async function runInitCommand(context, dependencies, hookFlag, setupFlag, explic
             hookInstalled,
             scopes: scopeSummaries,
             manifestVersionRestamps,
+            ...(directGuidance
+                ? { projectGuidance: reportableProjectGuidance(directGuidance) }
+                : {}),
         };
         context.logger.json(payload);
     }
     process.exitCode = 0;
-    const freshInit = projectRoot !== null && !oatDirExistedBefore;
-    if (setupFlag || (context.interactive && freshInit)) {
+    if (setupMayRun) {
         let shouldRunSetup = !!setupFlag;
         if (!shouldRunSetup && freshInit) {
             shouldRunSetup = await dependencies.confirmAction('Would you like to run guided setup?', { interactive: context.interactive });
@@ -722,6 +734,17 @@ async function runInitCommand(context, dependencies, hookFlag, setupFlag, explic
                 await dependencies.runGuidedSetup(context, dependencies, explicitProjectGuidance);
             }
         }
+        else if (explicitProjectGuidance === true) {
+            directGuidance = await dependencies.applyProjectGuidance(context, projectRoot);
+        }
+    }
+    if (directGuidance) {
+        if (!context.json) {
+            reportProjectGuidancePlan(context.logger, directGuidance);
+        }
+        if (isProjectGuidanceIncomplete(directGuidance)) {
+            process.exitCode = 1;
+        }
     }
 }
 export function createInitCommand(overrides = {}) {

package/dist/commands/init/tools/index.d.ts

@@ -13,7 +13,7 @@ import { type InstallBrainstormOptions, type InstallBrainstormResult } from './b
 import { type InstallCoreOptions, type InstallCoreResult } from './core/install-core.js';
 import { type InstallDocsOptions, type InstallDocsResult } from './docs/install-docs.js';
 import { type InstallIdeasOptions, type InstallIdeasResult } from './ideas/install-ideas.js';
-import { type PlanProjectGuidanceInput, planProjectGuidance } from './project-guidance.js';
+import { type AgentsGuidancePlan, type PlanProjectGuidanceInput, planProjectGuidance, type ProjectGuidancePack } from './project-guidance.js';
 import { type InstallProjectManagementOptions, type InstallProjectManagementResult } from './project-management/install-project-management.js';
 import { type InstallResearchOptions, type InstallResearchResult } from './research/install-research.js';
 import { type InstallUtilityOptions, type InstallUtilityResult } from './utility/install-utility.js';
@@ -78,6 +78,23 @@ interface PackScopeChange {
 export declare function formatReconcileSummary(adds: PackScopeChange[], removes: PackScopeChange[]): string;
 export declare function consumeInitToolsRunMetadata(): InitToolsRunMetadata | null;
 export declare function wasInstallSyncHandled(command: Command): boolean;
+export interface RealizedGuidanceState {
+    packs: ProjectGuidancePack[];
+    /** Project skills that belong to no OAT pack, by name. */
+    otherProjectSkills: string[];
+}
+/**
+ * Reads the realized pack placement (and unrelated project skills) the OAT
+ * tools block describes. Read-only: it inventories and scans installed state
+ * and never installs, upgrades, or writes.
+ */
+export declare function loadRealizedGuidanceState(context: CommandContext, projectRoot: string | null, overrides?: Partial<InitToolsDependencies>): Promise<RealizedGuidanceState>;
+/**
+ * Plans and applies the OAT tools guidance block for the packs already
+ * installed, without installing or upgrading anything. `oat init` uses it to
+ * honor `--project-guidance` when guided setup does not run.
+ */
+export declare function applyProjectGuidanceForInstalledPacks(context: CommandContext, projectRoot: string | null, explicitChoice: boolean, overrides?: Partial<InitToolsDependencies>): Promise<AgentsGuidancePlan>;
 export { buildToolPacksSectionBody } from './project-guidance.js';
 export declare function runInitTools(context: CommandContext, dependencies: InitToolsDependencies, explicitProjectGuidance?: boolean): Promise<ToolPack[]>;
 export declare function runInitToolsWithDefaults(context: CommandContext, explicitProjectGuidance?: boolean): Promise<ToolPack[]>;

package/dist/commands/init/tools/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/commands/init/tools/index.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/commands/init/tools/index.ts"],"names":[],"mappings":"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"}

package/dist/commands/init/tools/index.js

@@ -532,7 +532,11 @@ async function applyProjectGuidance(plan, dependencies) {
         }
         return {
             ...plan,
-            action: sectionResult.action === 'created' ? 'create' : 'no-change',
+            action: sectionResult.action === 'created'
+                ? 'create'
+                : sectionResult.action === 'appended'
+                    ? 'appended'
+                    : 'no-change',
             reason: `Accepted project guidance ${sectionResult.action}. Capability placement and PJM adoption were unchanged.`,
         };
     }
@@ -544,6 +548,50 @@ async function applyProjectGuidance(plan, dependencies) {
         };
     }
 }
+async function realizedGuidanceState(context, repoRoot, assetsRoot, dependencies) {
+    const userRoot = dependencies.resolveScopeRoot('user', context.cwd, context.home);
+    const finalPackStates = await loadInstalledPackStates(repoRoot, userRoot, assetsRoot, dependencies);
+    const packs = ALL_TOOL_PACKS.flatMap((pack) => {
+        const scope = finalPackStates[pack].location;
+        return scope === 'not-installed'
+            ? []
+            : [{ pack, scope }];
+    });
+    return {
+        packs,
+        otherProjectSkills: await otherProjectSkillNames(repoRoot, assetsRoot, dependencies),
+    };
+}
+/**
+ * Project skills whose names belong to no bundled pack. Pack membership, not
+ * directory existence, decides what is "other".
+ */
+async function otherProjectSkillNames(repoRoot, assetsRoot, dependencies) {
+    if (!repoRoot)
+        return [];
+    const projectTools = await dependencies.scanTools({
+        scope: 'project',
+        scopeRoot: repoRoot,
+        assetsRoot,
+    });
+    return projectTools
+        .filter(({ type, pack }) => type === 'skill' && pack === 'custom')
+        .map(({ name }) => name)
+        .sort();
+}
+/**
+ * Reads the realized pack placement (and unrelated project skills) the OAT
+ * tools block describes. Read-only: it inventories and scans installed state
+ * and never installs, upgrades, or writes.
+ */
+export async function loadRealizedGuidanceState(context, projectRoot, overrides = {}) {
+    const dependencies = {
+        ...DEFAULT_DEPENDENCIES,
+        ...overrides,
+    };
+    const assetsRoot = await dependencies.resolveAssetsRoot();
+    return realizedGuidanceState(context, projectRoot, assetsRoot, dependencies);
+}
 async function planAndApplyProjectGuidanceAfterInstall(context, assetsRoot, installedProjectRoot, explicitChoice, dependencies) {
     const initialPlan = await dependencies.planProjectGuidance({
         repoRoot: installedProjectRoot,
@@ -557,17 +605,22 @@ async function planAndApplyProjectGuidanceAfterInstall(context, assetsRoot, inst
     try {
         const repoRoot = installedProjectRoot ??
             (await dependencies.resolveProjectRoot(context.cwd));
-        const userRoot = dependencies.resolveScopeRoot('user', context.cwd, context.home);
-        const finalPackStates = await loadInstalledPackStates(repoRoot, userRoot, assetsRoot, dependencies);
-        const realizedPacks = ALL_TOOL_PACKS.flatMap((pack) => {
-            const scope = finalPackStates[pack].location;
-            return scope === 'not-installed'
-                ? []
-                : [{ pack, scope }];
-        });
+        const realized = await realizedGuidanceState(context, repoRoot, assetsRoot, dependencies);
+        if (realized.packs.length === 0) {
+            // An empty block would be a stale placeholder that turns the first real
+            // pack install into a manual patch, so write nothing.
+            return {
+                ...initialPlan,
+                repoRoot,
+                target: join(repoRoot, 'AGENTS.md'),
+                action: 'skipped',
+                reason: 'No OAT tool pack is installed, so there is no OAT tools guidance to write; AGENTS.md was left unchanged. Run `oat tools install <pack> --project-guidance` or `oat init --setup --project-guidance` to install packs with guidance.',
+            };
+        }
         const completePlan = await dependencies.planProjectGuidance({
             repoRoot,
-            packs: realizedPacks,
+            packs: realized.packs,
+            otherProjectSkills: realized.otherProjectSkills,
             explicitChoice: true,
             interactive: false,
             confirmAction: dependencies.confirmAction,
@@ -582,6 +635,19 @@ async function planAndApplyProjectGuidanceAfterInstall(context, assetsRoot, inst
         };
     }
 }
+/**
+ * Plans and applies the OAT tools guidance block for the packs already
+ * installed, without installing or upgrading anything. `oat init` uses it to
+ * honor `--project-guidance` when guided setup does not run.
+ */
+export async function applyProjectGuidanceForInstalledPacks(context, projectRoot, explicitChoice, overrides = {}) {
+    const dependencies = {
+        ...DEFAULT_DEPENDENCIES,
+        ...overrides,
+    };
+    const assetsRoot = await dependencies.resolveAssetsRoot();
+    return planAndApplyProjectGuidanceAfterInstall(context, assetsRoot, projectRoot, explicitChoice, dependencies);
+}
 function initProviderVisibility(syncScopes) {
     if (syncScopes.length === 0)
         return null;
@@ -1022,6 +1088,7 @@ export async function runInitTools(context, dependencies, explicitProjectGuidanc
         const plannedGuidance = await dependencies.planProjectGuidance({
             repoRoot: projectRoot,
             packs: realizedPacks,
+            otherProjectSkills: await otherProjectSkillNames(projectRoot, assetsRoot, dependencies),
             explicitChoice: explicitProjectGuidance,
             interactive: context.interactive,
             confirmAction: dependencies.confirmAction,
@@ -1171,9 +1238,9 @@ function createReconciledPackCommand(pack, dependencies) {
     };
     const base = new Command(pack).description(descriptions[pack]);
     const scopedCommand = pack === 'core' ? base : withScopeOption(base);
-    const packCommand = pack === 'workflows'
-        ? withProjectGuidanceOptions(scopedCommand)
-        : scopedCommand;
+    // Every pack command acts on --project-guidance: the OAT tools block
+    // describes every installed pack, so any pack install can plan it.
+    const packCommand = withProjectGuidanceOptions(scopedCommand);
     return packCommand
         .allowUnknownOption(false)
         .action(async (_options, command) => {
@@ -1182,9 +1249,7 @@ function createReconciledPackCommand(pack, dependencies) {
         let selection = null;
         let providerContexts = [];
         try {
-            const explicitProjectGuidance = pack === 'workflows'
-                ? commandProjectGuidanceChoice(command)
-                : undefined;
+            const explicitProjectGuidance = commandProjectGuidanceChoice(command);
             const assetsRoot = await dependencies.resolveAssetsRoot();
             const explicitScope = command.getOptionValueSourceWithGlobals('scope') === 'cli';
             const requestedScope = context.scope === 'project' || context.scope === 'user'
@@ -1270,7 +1335,9 @@ function createReconciledPackCommand(pack, dependencies) {
             const providerVisibility = initProviderVisibility(results
                 .filter(({ plan }) => plan.operations.length > 0)
                 .map(({ request }) => request.scope));
-            const projectGuidance = pack === 'workflows'
+            // `workflows` offers guidance on every run (prompting when
+            // interactive); other packs plan it only when the flag is given.
+            const projectGuidance = pack === 'workflows' || explicitProjectGuidance !== undefined
                 ? await planAndApplyProjectGuidanceAfterInstall(context, assetsRoot, requests.find(({ scope }) => scope === 'project')?.scopeRoot ??
                     null, explicitProjectGuidance, dependencies)
                 : null;

package/dist/commands/init/tools/project-guidance.d.ts

@@ -1,4 +1,4 @@
-import type { AgentsMdManualPatch } from '../../shared/agents-md.js';
+import { type AgentsMdManualPatch } from '../../shared/agents-md.js';
 import type { PromptContext } from '../../shared/shared.prompts.js';
 import type { PackName } from '../../tools/shared/types.js';
 import type { Command } from 'commander';
@@ -12,7 +12,7 @@ export type ProjectGuidanceChoice = {
     choice: 'not-requested';
     source: 'non-interactive-default';
 };
-export type AgentsGuidanceAction = 'declined' | 'not-requested' | 'create' | 'no-change' | 'manual-required' | 'blocked';
+export type AgentsGuidanceAction = 'declined' | 'not-requested' | 'create' | 'appended' | 'skipped' | 'no-change' | 'manual-required' | 'blocked';
 export interface ProjectGuidancePack {
     pack: PackName;
     scope: 'project' | 'user' | 'both';
@@ -28,7 +28,14 @@ export interface AgentsGuidancePlan {
     choice: ProjectGuidanceChoice;
     manualPatch?: AgentsMdManualPatch;
 }
-export interface PlanProjectGuidanceInput {
+export interface ToolPacksSectionOptions {
+    /**
+     * Project skills that belong to no OAT pack. They are described separately
+     * and never named as pack skills.
+     */
+    otherProjectSkills?: readonly string[];
+}
+export interface PlanProjectGuidanceInput extends ToolPacksSectionOptions {
     repoRoot: string | null;
     packs: readonly ProjectGuidancePack[];
     explicitChoice?: boolean;
@@ -41,7 +48,15 @@ export declare function reportableProjectGuidance(plan: AgentsGuidancePlan): {
     reason: string;
     manualPatch?: AgentsMdManualPatch | undefined;
 };
-export declare function buildToolPacksSectionBody(packs: readonly ProjectGuidancePack[]): string;
+export declare function isProjectGuidanceIncomplete(plan: AgentsGuidancePlan): boolean;
+/** Prints one guidance plan in the human form every guidance surface uses. */
+export declare function reportProjectGuidancePlan(logger: {
+    info: (message: string) => void;
+    warn: (message: string) => void;
+}, plan: AgentsGuidancePlan): void;
+export declare function buildToolPacksSectionBody(packs: readonly ProjectGuidancePack[], options?: ToolPacksSectionOptions): string;
+/** The complete managed `OAT tools` block, markers included. */
+export declare function renderToolPacksManagedBlock(packs: readonly ProjectGuidancePack[], options?: ToolPacksSectionOptions): string;
 export declare function parseProjectGuidanceFlags(args: readonly string[]): boolean | undefined;
 export declare function commandProjectGuidanceChoice(command: Command): boolean | undefined;
 export declare function withProjectGuidanceOptions<TCommand extends Command>(command: TCommand): TCommand;

package/dist/commands/init/tools/project-guidance.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"project-guidance.d.ts","sourceRoot":"","sources":["../../../../src/commands/init/tools/project-guidance.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,4BAA4B,CAAC;AACtE,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,iCAAiC,CAAC;AACrE,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,8BAA8B,CAAC;AAE7D,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAEzC,MAAM,MAAM,qBAAqB,GAC7B;IAAE,MAAM,EAAE,UAAU,CAAC;IAAC,MAAM,EAAE,QAAQ,GAAG,MAAM,CAAA;CAAE,GACjD;IAAE,MAAM,EAAE,UAAU,CAAC;IAAC,MAAM,EAAE,QAAQ,GAAG,MAAM,CAAA;CAAE,GACjD;IAAE,MAAM,EAAE,eAAe,CAAC;IAAC,MAAM,EAAE,yBAAyB,CAAA;CAAE,CAAC;AAEnE,MAAM,MAAM,oBAAoB,GAC5B,UAAU,GACV,eAAe,GACf,QAAQ,GACR,WAAW,GACX,iBAAiB,GACjB,SAAS,CAAC;AAEd,MAAM,WAAW,mBAAmB;IAClC,IAAI,EAAE,QAAQ,CAAC;IACf,KAAK,EAAE,SAAS,GAAG,MAAM,GAAG,MAAM,CAAC;CACpC;AAED,MAAM,WAAW,kBAAkB;IACjC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,MAAM,EAAE,oBAAoB,CAAC;IAC7B,UAAU,EAAE,OAAO,CAAC;IACpB,IAAI,EAAE,MAAM,CAAC;IACb,mBAAmB,EAAE,UAAU,GAAG,QAAQ,CAAC;IAC3C,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,qBAAqB,CAAC;IAC9B,WAAW,CAAC,EAAE,mBAAmB,CAAC;CACnC;AAED,MAAM,WAAW,wBAAwB;IACvC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,KAAK,EAAE,SAAS,mBAAmB,EAAE,CAAC;IACtC,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB,WAAW,EAAE,OAAO,CAAC;IACrB,aAAa,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,aAAa,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;CAC9E;AAED,wBAAgB,yBAAyB,CAAC,IAAI,EAAE,kBAAkB;;;;;EAOjE;AAgBD,wBAAgB,yBAAyB,CACvC,KAAK,EAAE,SAAS,mBAAmB,EAAE,GACpC,MAAM,CA2CR;AAED,wBAAgB,yBAAyB,CACvC,IAAI,EAAE,SAAS,MAAM,EAAE,GACtB,OAAO,GAAG,SAAS,CAYrB;AAED,wBAAgB,4BAA4B,CAC1C,OAAO,EAAE,OAAO,GACf,OAAO,GAAG,SAAS,CAKrB;AAED,wBAAgB,0BAA0B,CAAC,QAAQ,SAAS,OAAO,EACjE,OAAO,EAAE,QAAQ,GAChB,QAAQ,CAcV;AAED,wBAAsB,mBAAmB,CACvC,KAAK,EAAE,wBAAwB,GAC9B,OAAO,CAAC,kBAAkB,CAAC,CAyE7B"}
+{"version":3,"file":"project-guidance.d.ts","sourceRoot":"","sources":["../../../../src/commands/init/tools/project-guidance.ts"],"names":[],"mappings":"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"}