@aiwg/cli 2026.7.19 → 2026.7.21

package/dist/src/skills/registry.js

@@ -6,6 +6,7 @@
  *
  * @implements #539
  */
+import { AgentSkillsAdapter } from './adapters/agent-skills.js';
 import { LocalAdapter } from './adapters/local.js';
 import { ClawHubAdapter } from './adapters/clawhub.js';
 import { OpenClawAdapter } from './adapters/openclaw.js';
@@ -14,9 +15,27 @@ import { OpenClawAdapter } from './adapters/openclaw.js';
  */
 const ALL_ADAPTERS = [
     new LocalAdapter(),
+    new AgentSkillsAdapter(),
     new ClawHubAdapter(),
     new OpenClawAdapter(),
 ];
+/**
+ * Import a standard Agent Skills directory or pinned Git source.
+ */
+export async function importSkillSource(source, options, providerId = 'agentskills') {
+    const adapter = getAdapter(providerId);
+    if (!adapter) {
+        throw new Error(`Unknown registry: ${providerId}`);
+    }
+    if (!adapter.importSource) {
+        throw new Error(`Registry '${providerId}' does not support source import`);
+    }
+    const available = await adapter.isAvailable();
+    if (!available) {
+        throw new Error(`Registry '${providerId}' is not available`);
+    }
+    return adapter.importSource(source, options);
+}
 /**
  * Get adapter by ID
  */

package/dist/src/skills/validator.js

@@ -0,0 +1,323 @@
+/**
+ * Shared Agent Skills parser and conformance validator.
+ *
+ * This module is the only place that parses SKILL.md for Agent Skills
+ * conformance. Consumers may add their own quality or deployment policy, but
+ * must retain these diagnostics unchanged.
+ *
+ * @implements #1878
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { parseDocument } from 'yaml';
+import { AGENT_SKILLS_BASELINE, AGENT_SKILL_VALIDATION_PROFILES, AIWG_SKILL_CONTROL_FIELDS, STANDARD_SKILL_FIELDS, validateCompatibleAgentSkillMetadata, } from './agent-skills.js';
+const FRONTMATTER = /^---\r?\n([\s\S]*?)\r?\n---(?:\r?\n|$)/;
+const MARKDOWN_LINK = /!?\[[^\]]*]\(\s*(?:<([^>]+)>|([^\s)]+))(?:\s+["'][^)]*["'])?\s*\)/g;
+const STANDARD_FIELDS = new Set(STANDARD_SKILL_FIELDS);
+const AIWG_FIELDS = new Set(AIWG_SKILL_CONTROL_FIELDS);
+function diagnostic(code, severity, file, yamlPath, message, remediation) {
+    return {
+        code,
+        severity,
+        file,
+        yamlPath,
+        message,
+        upstreamBaseline: AGENT_SKILLS_BASELINE.revision,
+        remediation,
+    };
+}
+function sortDiagnostics(diagnostics) {
+    return diagnostics.sort((left, right) => (left.file.localeCompare(right.file)
+        || left.code.localeCompare(right.code)
+        || left.yamlPath.localeCompare(right.yamlPath)
+        || left.message.localeCompare(right.message)));
+}
+function normalizeMetadataDiagnostics(diagnostics, frontmatter, profile, file) {
+    const policy = AGENT_SKILL_VALIDATION_PROFILES[profile];
+    const normalized = diagnostics.flatMap((item) => {
+        if (item.code === 'AS_FIELD_UNKNOWN') {
+            return [{
+                    ...item,
+                    severity: policy.unknownField,
+                }];
+        }
+        if (profile === 'discovery'
+            && (item.code === 'AS_NAME_FORMAT' || item.code === 'AS_NAME_DIRECTORY')) {
+            return [{ ...item, severity: policy.cosmeticNameDefect }];
+        }
+        return [item];
+    });
+    if (!policy.recognizedAiwgFields) {
+        for (const key of Object.keys(frontmatter).sort()) {
+            if (!AIWG_FIELDS.has(key))
+                continue;
+            normalized.push(diagnostic('AS_FIELD_EXTENSION', 'error', file, `$.${key}`, `AIWG extension field "${key}" is not allowed by the strict profile`, 'Remove the extension field or validate with the compatible profile.'));
+        }
+    }
+    return normalized;
+}
+function resourceDiagnostics(content, file, skillRoot, checkResources) {
+    const diagnostics = [];
+    const references = new Set();
+    for (const match of content.matchAll(MARKDOWN_LINK)) {
+        const raw = (match[1] ?? match[2] ?? '').trim();
+        if (raw.length === 0
+            || raw.startsWith('#')
+            || /^(?:https?|mailto|data):/i.test(raw)) {
+            continue;
+        }
+        const withoutFragment = raw.split('#', 1)[0] ?? '';
+        const decoded = (() => {
+            try {
+                return decodeURIComponent(withoutFragment);
+            }
+            catch {
+                return withoutFragment;
+            }
+        })();
+        references.add(decoded);
+    }
+    for (const reference of [...references].sort()) {
+        const normalized = reference.replaceAll('\\', '/');
+        if (path.isAbsolute(reference)
+            || normalized === '..'
+            || normalized.startsWith('../')
+            || normalized.includes('/../')) {
+            diagnostics.push(diagnostic('AS_RESOURCE_PATH', 'warning', file, '$.body', `resource reference "${reference}" is not an in-skill relative path`, 'Reference a file relative to SKILL.md without parent traversal.'));
+            continue;
+        }
+        const segments = normalized.split('/').filter(Boolean);
+        if (segments.length > 2) {
+            diagnostics.push(diagnostic('AS_ADVISORY_RESOURCE_DEPTH', 'warning', file, '$.body', `resource reference "${reference}" is deeper than one resource-directory level`, 'Prefer resources such as references/topic.md, scripts/run.sh, or assets/example.json.'));
+        }
+        if (!checkResources || !skillRoot)
+            continue;
+        const resolved = path.resolve(skillRoot, reference);
+        const relative = path.relative(skillRoot, resolved);
+        if (relative.startsWith('..')
+            || path.isAbsolute(relative)
+            || !fs.existsSync(resolved)) {
+            diagnostics.push(diagnostic('AS_RESOURCE_MISSING', 'warning', file, '$.body', `referenced resource "${reference}" does not exist`, 'Add the referenced file or correct the relative resource path.'));
+            continue;
+        }
+        const stat = fs.lstatSync(resolved);
+        if (stat.isSymbolicLink() || !stat.isFile()) {
+            diagnostics.push(diagnostic('AS_RESOURCE_TYPE', 'warning', file, '$.body', `referenced resource "${reference}" is not a regular file`, 'Replace the reference target with an in-tree regular file.'));
+        }
+    }
+    return diagnostics;
+}
+function resultState(diagnostics, profile) {
+    const errors = diagnostics.filter((item) => item.severity === 'error');
+    if (errors.length > 0) {
+        if (profile === 'discovery'
+            && errors.some((item) => (item.code === 'AS_DESCRIPTION_REQUIRED'
+                || item.code === 'AS_FRONTMATTER_REQUIRED'
+                || item.code === 'AS_YAML_PARSE'
+                || item.code === 'AS_YAML_TYPE'))) {
+            return 'skipped';
+        }
+        return 'invalid';
+    }
+    return diagnostics.some((item) => item.severity === 'warning')
+        ? 'warning'
+        : 'valid';
+}
+export function validateAgentSkillContent(content, options = {}) {
+    const profile = options.profile ?? 'compatible';
+    const file = options.file ?? 'SKILL.md';
+    const directoryName = options.directoryName
+        ?? (options.skillRoot ? path.basename(options.skillRoot) : undefined)
+        ?? (path.dirname(file) !== '.' ? path.basename(path.dirname(file)) : undefined);
+    const lines = content.split(/\r?\n/).length;
+    const metrics = {
+        lines,
+        // The upstream guidance is advisory. A deterministic UTF-16/4 estimate
+        // avoids a runtime tokenizer dependency while keeping CI snapshots stable.
+        estimatedTokens: Math.ceil(content.length / 4),
+    };
+    const diagnostics = [];
+    const match = FRONTMATTER.exec(content);
+    if (!match) {
+        diagnostics.push(diagnostic('AS_FRONTMATTER_REQUIRED', 'error', file, '$', 'SKILL.md must begin with YAML frontmatter', 'Add a leading YAML mapping delimited by `---` lines.'));
+        const state = resultState(diagnostics, profile);
+        return {
+            schemaVersion: 1,
+            profile,
+            file,
+            state,
+            valid: false,
+            discoverable: false,
+            body: content,
+            diagnostics,
+            metrics,
+        };
+    }
+    const document = parseDocument(match[1] ?? '', {
+        prettyErrors: false,
+        strict: true,
+        uniqueKeys: true,
+    });
+    if (document.errors.length > 0) {
+        for (const error of document.errors) {
+            diagnostics.push(diagnostic('AS_YAML_PARSE', 'error', file, '$', `SKILL.md frontmatter is invalid YAML: ${error.message}`, 'Correct the YAML syntax before validation or discovery.'));
+        }
+        const state = resultState(diagnostics, profile);
+        return {
+            schemaVersion: 1,
+            profile,
+            file,
+            state,
+            valid: false,
+            discoverable: false,
+            body: content.slice(match[0].length),
+            diagnostics: sortDiagnostics(diagnostics),
+            metrics,
+        };
+    }
+    const parsed = document.toJS({ maxAliasCount: 100 });
+    if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed)) {
+        diagnostics.push(diagnostic('AS_YAML_TYPE', 'error', file, '$', 'SKILL.md frontmatter must be a YAML mapping', 'Use top-level key/value fields.'));
+        const state = resultState(diagnostics, profile);
+        return {
+            schemaVersion: 1,
+            profile,
+            file,
+            state,
+            valid: false,
+            discoverable: false,
+            body: content.slice(match[0].length),
+            diagnostics,
+            metrics,
+        };
+    }
+    const frontmatter = parsed;
+    diagnostics.push(...normalizeMetadataDiagnostics(validateCompatibleAgentSkillMetadata(frontmatter, directoryName
+        ?? (typeof frontmatter['name'] === 'string' ? frontmatter['name'] : ''), file, lines), frontmatter, profile, file));
+    if (Object.prototype.hasOwnProperty.call(frontmatter, 'allowed-tools')) {
+        const value = frontmatter['allowed-tools'];
+        if (typeof value === 'string'
+            && (value.trim() !== value || value.length === 0 || /\s{2,}|\t|\r|\n/.test(value))) {
+            diagnostics.push(diagnostic('AS_ALLOWED_TOOLS_FORMAT', 'error', file, '$.allowed-tools', 'allowed-tools must contain non-empty tool identifiers separated by single spaces', 'Normalize allowed-tools to a single space-delimited string.'));
+        }
+        diagnostics.push(diagnostic('AS_ALLOWED_TOOLS_EXPERIMENTAL', 'warning', file, '$.allowed-tools', 'allowed-tools is experimental in the pinned Agent Skills baseline', 'Treat allowed-tools as advisory unless the target provider documents enforcement.'));
+    }
+    const body = content.slice(match[0].length);
+    if (body.trim().length === 0) {
+        diagnostics.push(diagnostic('AS_BODY_REQUIRED', 'error', file, '$.body', 'SKILL.md must contain Markdown instructions after frontmatter', 'Add the skill instructions below the closing frontmatter delimiter.'));
+    }
+    if (metrics.estimatedTokens > 5_000) {
+        diagnostics.push(diagnostic('AS_ADVISORY_TOKENS', 'warning', file, '$', `SKILL.md is approximately ${metrics.estimatedTokens} tokens; the recommendation is at most 5,000`, 'Move detailed material to referenced resources.'));
+    }
+    diagnostics.push(...resourceDiagnostics(body, file, options.skillRoot, options.checkResources ?? Boolean(options.skillRoot)));
+    // Defensive policy check: a future field added to one allow-list must not
+    // silently escape classification in this parser.
+    for (const key of Object.keys(frontmatter).sort()) {
+        if (STANDARD_FIELDS.has(key) || AIWG_FIELDS.has(key))
+            continue;
+        if (!diagnostics.some((item) => item.yamlPath === `$.${key}`)) {
+            diagnostics.push(diagnostic('AS_FIELD_UNKNOWN', AGENT_SKILL_VALIDATION_PROFILES[profile].unknownField, file, `$.${key}`, `unrecognized top-level field "${key}"`, 'Remove the field or map it explicitly before granting it policy meaning.'));
+        }
+    }
+    sortDiagnostics(diagnostics);
+    const state = resultState(diagnostics, profile);
+    return {
+        schemaVersion: 1,
+        profile,
+        file,
+        state,
+        valid: state === 'valid' || state === 'warning',
+        discoverable: state !== 'skipped',
+        frontmatter,
+        body,
+        diagnostics,
+        metrics,
+    };
+}
+export function validateAgentSkillFile(filePath, options = {}) {
+    const resolved = path.resolve(filePath);
+    const stat = fs.lstatSync(resolved);
+    if (stat.isSymbolicLink() || !stat.isFile()) {
+        const content = '';
+        const result = validateAgentSkillContent(content, {
+            ...options,
+            file: resolved,
+            skillRoot: path.dirname(resolved),
+        });
+        result.diagnostics = [diagnostic('AS_SKILL_FILE_TYPE', 'error', resolved, '$', 'SKILL.md must be a regular file, not a symbolic link or special file', 'Replace SKILL.md with an in-tree regular file.')];
+        result.state = options.profile === 'discovery' ? 'skipped' : 'invalid';
+        result.valid = false;
+        result.discoverable = false;
+        return result;
+    }
+    const result = validateAgentSkillContent(fs.readFileSync(resolved, 'utf8'), {
+        ...options,
+        file: resolved,
+        directoryName: options.directoryName ?? path.basename(path.dirname(resolved)),
+        skillRoot: path.dirname(resolved),
+        checkResources: true,
+    });
+    if (path.basename(resolved) !== 'SKILL.md') {
+        result.diagnostics.push(diagnostic('AS_SKILL_FILENAME', 'error', resolved, '$', 'the skill entrypoint must be named SKILL.md', 'Rename the entrypoint to SKILL.md.'));
+        sortDiagnostics(result.diagnostics);
+        result.state = resultState(result.diagnostics, result.profile);
+        result.valid = false;
+    }
+    return result;
+}
+function collectSkillFiles(targetPath, recursive, files) {
+    const resolved = path.resolve(targetPath);
+    if (!fs.existsSync(resolved))
+        return;
+    const stat = fs.lstatSync(resolved);
+    if (stat.isSymbolicLink())
+        return;
+    if (stat.isFile()) {
+        if (path.basename(resolved) === 'SKILL.md')
+            files.add(resolved);
+        return;
+    }
+    if (!stat.isDirectory())
+        return;
+    const direct = path.join(resolved, 'SKILL.md');
+    if (fs.existsSync(direct) && !fs.lstatSync(direct).isSymbolicLink()) {
+        files.add(direct);
+    }
+    if (!recursive)
+        return;
+    for (const entry of fs.readdirSync(resolved, { withFileTypes: true })
+        .sort((left, right) => left.name.localeCompare(right.name))) {
+        if (!entry.isDirectory()
+            || entry.isSymbolicLink()
+            || entry.name.startsWith('.')
+            || entry.name === 'node_modules') {
+            continue;
+        }
+        collectSkillFiles(path.join(resolved, entry.name), true, files);
+    }
+}
+export function scanAgentSkillPaths(targetPaths, options = {}) {
+    const profile = options.profile ?? 'compatible';
+    const files = new Set();
+    for (const target of typeof targetPaths === 'string' ? [targetPaths] : targetPaths) {
+        collectSkillFiles(target, options.recursive ?? true, files);
+    }
+    const results = [...files]
+        .sort((left, right) => left.localeCompare(right))
+        .map((file) => validateAgentSkillFile(file, { profile }));
+    return {
+        schemaVersion: 1,
+        profile,
+        files: results,
+        summary: {
+            scanned: results.length,
+            valid: results.filter((result) => result.state === 'valid').length,
+            warnings: results.filter((result) => result.state === 'warning').length,
+            invalid: results.filter((result) => result.state === 'invalid').length,
+            skipped: results.filter((result) => result.state === 'skipped').length,
+            errors: results.reduce((count, result) => count
+                + result.diagnostics.filter((item) => item.severity === 'error').length, 0),
+        },
+    };
+}
+//# sourceMappingURL=validator.js.map

package/dist/src/smiths/context-pipeline/aiwg-md.js

@@ -16,6 +16,7 @@
  */
 import { promises as fs } from 'node:fs';
 import * as path from 'node:path';
+import { projectAiwgPath } from '../../config/project-artifacts.js';
 import { buildParallelismSection, replaceOrAppendParallelismBlock } from './parallelism-section.js';
 import { buildContextFinalizationBlock, replaceOrAppendFinalizationBlock } from './finalization.js';
 import { buildExternalLinksSection, replaceOrAppendExternalLinksBlock, } from './external-links-section.js';
@@ -78,13 +79,16 @@ export async function buildAiwgMdContent(projectPath, stagedClaudeMdContent) {
         return replaceOrAppendExternalLinksBlock(withFinalization, externalLinksSection);
     }
     // Fallback stub.
+    const normalizedPath = projectAiwgPath(projectPath, 'AIWG.md');
+    const normalizedRelative = path.relative(projectPath, normalizedPath).replace(/\\/g, '/');
+    const normalizedLink = normalizedRelative.startsWith('.') ? normalizedRelative : `./${normalizedRelative}`;
     const stub = [
         '# AIWG.md',
         AIWG_SIGNATURE_COMMENT,
         '<!-- CLAUDE.md companion for non-Claude providers. -->',
         '',
         'CLAUDE.md was not found at project root. AIWG.md normally mirrors that content.',
-        'See [.aiwg/AIWG.md](./.aiwg/AIWG.md) for the project framework context.',
+        `See [${normalizedRelative}](${normalizedLink}) for the project framework context.`,
         '',
     ].join('\n');
     const withParallelism = replaceOrAppendParallelismBlock(stub, parallelismSection);

package/dist/src/smiths/context-pipeline/claude-hook.js

@@ -21,7 +21,7 @@
  */
 import * as fs from 'fs/promises';
 import * as path from 'path';
-import { buildProviderBootstrapBlock } from './workspace-context.js';
+import { buildProviderBootstrapBlock, PROVIDER_BOOTSTRAP_START, PROVIDER_BOOTSTRAP_END, } from './workspace-context.js';
 export const CLAUDE_HOOK_START = '<!-- AIWG:claude-md-hook:start -->';
 export const CLAUDE_HOOK_END = '<!-- AIWG:claude-md-hook:end -->';
 /**
@@ -76,6 +76,26 @@ export async function ensureClaudeMdHook(projectPath, opts = {}) {
     const endIdx = existing.indexOf(CLAUDE_HOOK_END);
     // Case 2: marker block does not exist — append the block to end of file.
     if (startIdx === -1 && endIdx === -1) {
+        const bootstrapStarts = existing.split(PROVIDER_BOOTSTRAP_START).length - 1;
+        const bootstrapEnds = existing.split(PROVIDER_BOOTSTRAP_END).length - 1;
+        // Current and legacy AIWG initialization may have emitted the provider
+        // bootstrap directly. Migrate that exact managed block in place instead
+        // of appending a hook containing a second copy (#1867).
+        if (bootstrapStarts === 1 && bootstrapEnds === 1) {
+            const bootstrapStartIdx = existing.indexOf(PROVIDER_BOOTSTRAP_START);
+            const bootstrapEndIdx = existing.indexOf(PROVIDER_BOOTSTRAP_END, bootstrapStartIdx)
+                + PROVIDER_BOOTSTRAP_END.length;
+            const updated = existing.substring(0, bootstrapStartIdx)
+                + block
+                + existing.substring(bootstrapEndIdx);
+            await fs.writeFile(claudeMdPath, updated, 'utf8');
+            result.action = 'updated';
+            return result;
+        }
+        if (bootstrapStarts !== bootstrapEnds || bootstrapStarts > 1) {
+            result.warnings.push('CLAUDE.md has malformed or duplicate AIWG provider-bootstrap markers; refusing to append a second managed bootstrap.');
+            return result;
+        }
         // Ensure the file ends with a single newline before appending.
         const trimmed = existing.replace(/\n+$/, '\n');
         const updated = `${trimmed}\n${block}\n`;

package/dist/src/smiths/context-pipeline/finalization.js

@@ -62,6 +62,7 @@ export async function buildContextFinalizationBlock(projectPath) {
     const installedNames = installed.map(([name]) => name);
     const providerDeployments = new Set();
     const normalizedAiwgMdPath = displayProjectPath(projectPath, projectAiwgPath(projectPath, 'AIWG.md'));
+    const normalizedAiwgMdLabel = `\`${normalizedAiwgMdPath}\``;
     for (const [, entry] of installed) {
         for (const provider of Object.keys(entry.deployedTo ?? {})) {
             providerDeployments.add(provider);
@@ -94,9 +95,9 @@ export async function buildContextFinalizationBlock(projectPath) {
         '',
         '### Source Model',
         '',
-        '- `.aiwg/AIWG.md` is the normalized project-local context entry point.',
+        `- ${normalizedAiwgMdLabel} is the normalized project-local context entry point.`,
         '- Root `AIWG.md` is the generated cross-provider companion loaded through `AGENTS.md` and provider twins.',
-        '- `AGENTS.md`, `WARP.md`, `.hermes.md`, and `.github/copilot-instructions.md` are provider-facing bridges, not replacements for `.aiwg/AIWG.md`.',
+        `- \`AGENTS.md\`, \`WARP.md\`, \`.hermes.md\`, and \`.github/copilot-instructions.md\` are provider-facing bridges, not replacements for ${normalizedAiwgMdLabel}.`,
         FINALIZATION_END,
         '',
     ];
@@ -113,6 +114,7 @@ export function replaceOrAppendFinalizationBlock(content, block) {
 export async function buildNormalizedAiwgMd(projectPath, existing = '') {
     const block = await buildContextFinalizationBlock(projectPath);
     const externalLinksSection = await buildExternalLinksSection(projectPath);
+    const normalizedAiwgMdPath = displayProjectPath(projectPath, projectAiwgPath(projectPath, 'AIWG.md'));
     const base = existing.trim().length > 0
         ? existing
         : [
@@ -120,7 +122,7 @@ export async function buildNormalizedAiwgMd(projectPath, existing = '') {
             AIWG_SIGNATURE_COMMENT,
             '<!-- Normalized project-local AIWG context. Operator notes may live outside AIWG-managed blocks. -->',
             '',
-            'This file is the stable `.aiwg/AIWG.md` entry point for AIWG skills, rules, and generated provider context.',
+            `This file is the stable \`${normalizedAiwgMdPath}\` entry point for AIWG skills, rules, and generated provider context.`,
             '',
         ].join('\n');
     const signed = base.includes(AIWG_SIGNATURE_COMMENT)

package/dist/src/smiths/context-pipeline/generator.js

@@ -21,6 +21,7 @@ import { shouldEmitAgentsMd, shouldEmitAiwgMd, shouldEmitClaudeMdHook } from './
 import { ensureClaudeMdHook } from './claude-hook.js';
 import { ensureManagedHook } from './managed-hook.js';
 import { buildProviderBootstrapBlock, ensureWorkspaceContext, registerProviderContext, } from './workspace-context.js';
+import { projectAiwgPath } from '../../config/project-artifacts.js';
 const SECTION_TITLES = {
     agents: 'Agents',
     rules: 'Rules',
@@ -136,7 +137,9 @@ export async function buildAgentsMd(opts) {
     parts.push('');
     parts.push('See [AIWG.md](./AIWG.md) for the full AIWG framework context');
     parts.push('(active frameworks, addons, agents, behaviors, rules).');
-    parts.push('Tracker and delivery source of truth: [.aiwg/aiwg.config](./.aiwg/aiwg.config).');
+    const configRelative = path.relative(opts.projectPath, projectAiwgPath(opts.projectPath, 'aiwg.config')).replace(/\\/g, '/');
+    const configLink = configRelative.startsWith('.') ? configRelative : `./${configRelative}`;
+    parts.push(`Tracker and delivery source of truth: [${configRelative}](${configLink}).`);
     parts.push('');
     parts.push('Deployed artifacts live under your provider\'s native directory');
     parts.push('(for example `.codex/agents/`, `.warp/agents/`, `.github/agents/`).');

package/dist/src/smiths/context-pipeline/parallelism-section.js

@@ -16,6 +16,27 @@
 import { readAiwgConfig, resolveParallelism, PROVIDER_PARALLELISM_DEFAULTS } from '../../config/aiwg-config.js';
 export const PARALLELISM_BLOCK_START = '<!-- AIWG-PARALLELISM-CAP:START -->';
 export const PARALLELISM_BLOCK_END = '<!-- AIWG-PARALLELISM-CAP:END -->';
+function delegationSupport(provider) {
+    switch (provider) {
+        case 'claude':
+        case 'codex':
+        case 'copilot':
+        case 'cursor':
+        case 'factory':
+        case 'opencode':
+        case 'openclaw':
+            return `**Provider behavior (${provider})**: native custom subagents can select the deployed model-worker wrapper. Verify the resolved model when provider or account policy may substitute it.`;
+        case 'openhuman':
+            return '**Provider behavior (openhuman)**: wrapper roles compile to OpenHuman agent definitions; exact pins validate while semantic hints may be routed dynamically.';
+        case 'warp':
+        case 'hermes':
+            return `**Provider behavior (${provider})**: delegation is available, but model selection is global/run-scoped. Use the wrapper rubric for task selection while reporting that heterogeneous per-worker pinning is not enforced.`;
+        case 'windsurf':
+            return '**Provider behavior (windsurf)**: portable subagent model selection is unsupported. Apply the decomposition rubric in the primary agent and do not claim wrapper pinning or parallel delegation.';
+        default:
+            return '**Provider behavior (unknown)**: delegation and per-worker model selection are unverified. Apply the rubric only where the active provider exposes those capabilities, and state any fallback explicitly.';
+    }
+}
 /**
  * Build the parallelism-cap markdown section for injection into context files.
  * Returns `''` when injection should be skipped:
@@ -61,7 +82,19 @@ export async function buildParallelismSection(projectPath) {
         lines.push(`*Rationale*: ${resolved.rationale}`);
     }
     lines.push('');
-    lines.push('When spawning parallel subagents, take the MIN of: this cap, `AIWG_CONTEXT_WINDOW` budget, the RLM 7-agent hard cap (RLM dispatches only), and the natural task decomposition. Bump via `aiwg config set --project parallelism.max_parallel_subagents N`.');
+    lines.push('### Model-selected delegation rubric');
+    lines.push('');
+    lines.push('For each non-trivial task, assess whether it contains independent, bounded subtasks that can run concurrently. When delegation is supported, prefer the deployed model-pinned wrappers by task characteristics and consequence:');
+    lines.push('');
+    lines.push('- `aiwg-model-efficiency-worker`: discovery, inventory, focused edits, and other bounded low-cost work.');
+    lines.push('- `aiwg-model-coding-worker`: implementation, tests, debugging, and routine technical delivery.');
+    lines.push('- `aiwg-model-reasoning-worker`: architecture, synthesis, difficult analysis, and high-consequence review.');
+    lines.push('');
+    lines.push('Do not delegate trivial work, tightly coupled changes, serial dependencies, or tasks likely to collide in shared state; also keep work local when coordination costs exceed the expected benefit. Parallelize only independent work, and take the MIN of provider limits, `max_parallel_subagents`, `AIWG_CONTEXT_WINDOW` budget, framework-specific caps (including the RLM 7-agent hard cap for RLM dispatches), and natural task decomposition. Bump the project cap via `aiwg config set --project parallelism.max_parallel_subagents N`.');
+    lines.push('');
+    lines.push('The primary agent retains orchestration, final integration, conflict resolution, validation, and user-facing accountability.');
+    lines.push('');
+    lines.push(delegationSupport(primary));
     lines.push('');
     lines.push(PARALLELISM_BLOCK_END);
     lines.push('');

package/dist/src/smiths/context-pipeline/workspace-context.js

@@ -384,7 +384,15 @@ export async function ensureWorkspaceContext(projectPath, options = {}) {
     }
     const block = buildWorkspaceManagedBlock(projectPath, options.providerFiles);
     if (existing.includes(WORKSPACE_MANAGED_START) || existing.includes(WORKSPACE_MANAGED_END)) {
-        const updated = replaceBlock(existing, WORKSPACE_MANAGED_START, WORKSPACE_MANAGED_END, block);
+        let updated = replaceBlock(existing, WORKSPACE_MANAGED_START, WORKSPACE_MANAGED_END, block);
+        // A managed project-extraction block explicitly points operators back to
+        // README/package metadata as its source. Refresh that block during normal
+        // regeneration so the documented edit-source-then-regenerate contract is
+        // true (#1866). Workspaces without an extraction remain opt-in.
+        if (updated.includes(PROJECT_EXTRACTION_START) || updated.includes(PROJECT_EXTRACTION_END)) {
+            const extracted = await extractExistingProjectContext(projectPath);
+            updated = replaceBlock(updated, PROJECT_EXTRACTION_START, PROJECT_EXTRACTION_END, extracted.content);
+        }
         if (updated === existing)
             return { path: workspacePath, action: 'unchanged', warnings };
         await atomicWrite(workspacePath, updated);
@@ -512,6 +520,7 @@ function sensitiveEvidence(content) {
 async function nestedInstructionFiles(projectPath) {
     const found = [];
     const ignored = new Set(['.git', 'node_modules', 'dist', 'build', 'coverage', '.aiwg']);
+    const artifactRoot = path.resolve(resolveProjectAiwgDir(projectPath));
     async function walk(directory) {
         let entries;
         try {
@@ -522,8 +531,11 @@ async function nestedInstructionFiles(projectPath) {
         }
         for (const entry of entries) {
             if (entry.isDirectory()) {
-                if (!ignored.has(entry.name) && !entry.name.startsWith('.context-migration-'))
-                    await walk(path.join(directory, entry.name));
+                const child = path.join(directory, entry.name);
+                if (!ignored.has(entry.name)
+                    && !entry.name.startsWith('.context-migration-')
+                    && path.resolve(child) !== artifactRoot)
+                    await walk(child);
             }
             else if (['AGENTS.md', 'CLAUDE.md', 'WARP.md'].includes(entry.name)) {
                 const relative = path.relative(projectPath, path.join(directory, entry.name)).replace(/\\/g, '/');

package/dist/src/smiths/mcpsmith/example.js

@@ -12,6 +12,7 @@ import { analyzeCLI } from './analyzers/cli-analyzer.js';
 import { generateServer, updateRegistry } from './generator.js';
 import path from 'path';
 import { fileURLToPath } from 'url';
+import { projectAiwgPath } from '../../config/project-artifacts.js';
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 async function main() {
     console.log('MCPsmith Example: Generating Git MCP Server\n');
@@ -28,7 +29,8 @@ async function main() {
     console.log();
     // Step 2: Generate the MCP server
     console.log('Step 2: Generating MCP server...');
-    const outputDir = path.join(__dirname, '..', '..', '..', '.aiwg', 'smiths', 'mcpsmith', 'servers');
+    const projectRoot = path.resolve(__dirname, '..', '..', '..');
+    const outputDir = projectAiwgPath(projectRoot, 'smiths', 'mcpsmith', 'servers');
     const generatedServer = await generateServer({
         serverId: 'git',
         serverName: 'Git CLI MCP Server',

package/dist/src/smiths/mcpsmith/generator.js

@@ -10,6 +10,7 @@ import fs from 'fs/promises';
 import path from 'path';
 import { fileURLToPath } from 'url';
 import crypto from 'crypto';
+import { projectAiwgPath } from '../../config/project-artifacts.js';
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 /**
  * Generate MCP server from analyzer result
@@ -174,7 +175,8 @@ function createManifest(serverId, serverName, analyzerResult, config) {
  */
 async function generateServerCode(serverId, serverName, analyzerResult) {
     // Load template
-    const templatePath = path.join(path.dirname(__dirname), '..', '..', '.aiwg', 'smiths', 'mcpsmith', 'templates', 'server-template.mjs');
+    const projectRoot = path.resolve(path.dirname(__dirname), '..', '..');
+    const templatePath = projectAiwgPath(projectRoot, 'smiths', 'mcpsmith', 'templates', 'server-template.mjs');
     let template = await fs.readFile(templatePath, 'utf-8');
     // Replace template variables
     const now = new Date().toISOString();

package/dist/src/smiths/toolsmith/runtime-discovery.mjs

@@ -13,6 +13,7 @@ import { existsSync, constants } from 'fs';
 import { resolve, join, dirname } from 'path';
 import { platform, arch, homedir, tmpdir, cpus, totalmem, freemem } from 'os';
 import { fileURLToPath } from 'url';
+import { projectAiwgPath } from '../../config/project-artifacts-runtime.mjs';
 
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
@@ -22,7 +23,7 @@ const __dirname = dirname(__filename);
  */
 export class RuntimeDiscovery {
   constructor(basePath = null) {
-    this.basePath = basePath || resolve(process.cwd(), '.aiwg/smiths/toolsmith');
+    this.basePath = basePath || projectAiwgPath(process.cwd(), 'smiths', 'toolsmith');
     this.knownTools = this.#loadKnownTools();
   }
 

package/dist/src/storage/cli.js

@@ -18,6 +18,7 @@ import { existsSync } from 'fs';
 import { mkdir, readFile, writeFile, appendFile } from 'fs/promises';
 import { dirname, join, resolve as resolvePath } from 'path';
 import { BACKEND_TYPES, FilesystemAdapter, ObsidianAdapter, LogseqAdapter, FortemiAdapter, SUBSYSTEM_KEYS, getLoadedConfig, initStorage, resolveStorage, resolveSubsystemRoot, storageConfigPath, } from './index.js';
+import { projectAiwgPath, resolveProjectAiwgDir } from '../config/project-artifacts.js';
 export async function main(args) {
     const subcommand = args[0];
     const subArgs = args.slice(1);
@@ -47,7 +48,7 @@ async function handleShow(projectRoot) {
     const config = await getLoadedConfig(projectRoot);
     const cfgPath = storageConfigPath(projectRoot);
     if (!config) {
-        console.log(`No storage.config — every subsystem uses the default fs backend under .aiwg/.\n`);
+        console.log(`No storage.config — every subsystem uses the default fs backend under ${resolveProjectAiwgDir(projectRoot)}.\n`);
         console.log(`Expected location (when configured): ${cfgPath}\n`);
     }
     else {
@@ -178,7 +179,7 @@ async function handleMigrate(projectRoot, args) {
         return;
     }
     // Resume support: read the per-migration log; skip already-done paths
-    const migrationLogPath = resolvePath(projectRoot, '.aiwg', '.storage-cache', 'migrations', `${opts.subsystem}-${specSlug(opts.from)}-to-${specSlug(opts.to)}.jsonl`);
+    const migrationLogPath = projectAiwgPath(projectRoot, '.storage-cache', 'migrations', `${opts.subsystem}-${specSlug(opts.from)}-to-${specSlug(opts.to)}.jsonl`);
     const completed = await readCompletedSet(migrationLogPath);
     let copied = 0;
     let skipped = 0;