@aiwg/cli 2026.7.20 → 2026.7.23

package/dist/src/cli/handlers/skill-lint.js

@@ -11,8 +11,8 @@
  */
 import * as fs from 'fs/promises';
 import * as path from 'path';
-import * as yaml from 'js-yaml';
 import { validateSkillFrontmatter } from '../../extensions/validation.js';
+import { validateAgentSkillFile } from '../../skills/validator.js';
 const THRESHOLDS = {
     strict: 80,
     standard: 60,
@@ -36,7 +36,14 @@ function partialDimension(score, notes) {
  * because the cleanup work in #1015 made schema correctness a baseline
  * expectation across the corpus.
  */
-function scoreSchema(frontmatter) {
+function scoreSchema(frontmatter, diagnostics) {
+    const conformanceErrors = diagnostics.filter((item) => item.severity === 'error');
+    if (conformanceErrors.length > 0) {
+        const notes = conformanceErrors.map((item) => (item.code === 'AS_YAML_PARSE'
+            ? `YAML parse error: ${item.message}`
+            : `${item.yamlPath}: ${item.message} [${item.code}]`));
+        return scoreDimension(false, notes);
+    }
     const result = validateSkillFrontmatter(frontmatter);
     if (result.success)
         return scoreDimension(true);
@@ -190,38 +197,12 @@ function inventoryCompanionCli(filePath, body) {
  * @param filePath - Absolute or relative path to the SKILL.md
  * @param rubric - Strictness level (drives the pass threshold)
  */
-export async function lintSkillFile(filePath, rubric = 'standard') {
-    const content = await fs.readFile(filePath, 'utf-8');
-    const fmMatch = content.match(/^---\n([\s\S]*?)\n---\n?([\s\S]*)$/);
-    if (!fmMatch) {
-        return {
-            file: filePath,
-            score: 0,
-            passes: false,
-            dimensions: {
-                schema: scoreDimension(false, ['no YAML frontmatter found']),
-                description: scoreDimension(false, ['no frontmatter to derive description from']),
-                discoverability: scoreDimension(false, ['no frontmatter']),
-                body: scoreBody(content),
-            },
-        };
-    }
-    const [, fmText, body = ''] = fmMatch;
-    let frontmatter = {};
-    let yamlError = null;
-    try {
-        const parsed = yaml.load(fmText);
-        if (parsed && typeof parsed === 'object') {
-            frontmatter = parsed;
-        }
-    }
-    catch (e) {
-        yamlError = e.message.split('\n')[0];
-    }
+export async function lintSkillFile(filePath, rubric = 'standard', profile = 'compatible') {
+    const validation = validateAgentSkillFile(filePath, { profile });
+    const frontmatter = validation.frontmatter ?? {};
+    const body = validation.body;
     const dimensions = {
-        schema: yamlError
-            ? scoreDimension(false, [`YAML parse error: ${yamlError}`])
-            : scoreSchema(frontmatter),
+        schema: scoreSchema(frontmatter, validation.diagnostics),
         description: scoreDescription(frontmatter),
         discoverability: scoreDiscoverability(frontmatter),
         body: scoreBody(body),
@@ -230,7 +211,12 @@ export async function lintSkillFile(filePath, rubric = 'standard') {
     return {
         file: filePath,
         score,
-        passes: score >= THRESHOLDS[rubric],
+        conformance: {
+            profile,
+            state: validation.state,
+            diagnostics: validation.diagnostics,
+        },
+        passes: validation.valid && score >= THRESHOLDS[rubric],
         dimensions,
     };
 }
@@ -243,7 +229,8 @@ async function* walkSkillFiles(rootPath) {
     }
     if (!stat.isDirectory())
         return;
-    const entries = await fs.readdir(rootPath, { withFileTypes: true });
+    const entries = (await fs.readdir(rootPath, { withFileTypes: true }))
+        .sort((left, right) => left.name.localeCompare(right.name));
     for (const e of entries) {
         if (e.name.startsWith('.') || e.name === 'node_modules')
             continue;
@@ -265,7 +252,7 @@ async function* walkSkillFiles(rootPath) {
  * Pure function — does not print or exit. The CLI handler renders
  * output and translates the report into an exit code.
  */
-export async function lintSkills(targetPaths, rubric = 'standard') {
+export async function lintSkills(targetPaths, rubric = 'standard', profile = 'compatible') {
     const targets = Array.isArray(targetPaths) ? targetPaths : [targetPaths];
     const seen = new Set();
     const files = [];
@@ -275,7 +262,7 @@ export async function lintSkills(targetPaths, rubric = 'standard') {
             if (seen.has(resolved))
                 continue;
             seen.add(resolved);
-            files.push(await lintSkillFile(f, rubric));
+            files.push(await lintSkillFile(f, rubric, profile));
         }
     }
     const total = files.reduce((sum, f) => sum + f.score, 0);
@@ -289,6 +276,7 @@ export async function lintSkills(targetPaths, rubric = 'standard') {
     }
     return {
         rubric,
+        profile,
         threshold: THRESHOLDS[rubric],
         files,
         averageScore: files.length > 0 ? Math.round(total / files.length) : 0,
@@ -303,6 +291,7 @@ export async function lintSkills(targetPaths, rubric = 'standard') {
 function parseArgs(args) {
     const targets = [];
     let rubric = 'standard';
+    let profile = 'compatible';
     let json = false;
     for (let i = 0; i < args.length; i++) {
         const a = args[i];
@@ -315,27 +304,42 @@ function parseArgs(args) {
                 rubric = next;
             }
         }
+        else if (a === '--profile' && i + 1 < args.length) {
+            const next = args[++i];
+            if (next === 'strict' || next === 'compatible' || next === 'discovery') {
+                profile = next;
+            }
+        }
         else if (!a.startsWith('-')) {
             targets.push(a);
         }
     }
     if (targets.length === 0)
         targets.push('agentic/code');
-    return { targets, rubric, json };
+    return { targets, rubric, profile, json };
 }
 function renderTextReport(report) {
-    const { files, threshold, rubric, averageScore, failedCount } = report;
+    const { files, threshold, rubric, profile, averageScore, failedCount } = report;
     for (const f of files) {
-        if (f.passes)
+        if (f.passes && f.conformance.diagnostics.length === 0)
             continue;
-        console.log(`✗ ${f.file} (${f.score}/100)`);
+        const mark = !f.passes
+            ? '✗'
+            : f.conformance.diagnostics.some((item) => item.severity === 'warning')
+                ? '⚠'
+                : '✓';
+        console.log(`${mark} ${f.file} (${f.score}/100, conformance=${f.conformance.state})`);
+        for (const item of f.conformance.diagnostics) {
+            console.log(`    ${item.severity} ${item.code} ${item.yamlPath}: ${item.message}; `
+                + `fix: ${item.remediation}`);
+        }
         for (const [name, dim] of Object.entries(f.dimensions)) {
-            if (dim.score < 100) {
+            if (!f.passes && dim.score < 100) {
                 console.log(`    ${name} (${dim.score}): ${dim.notes.join('; ')}`);
             }
         }
     }
-    console.log(`\nskill-lint (rubric=${rubric}, threshold=${threshold}):`);
+    console.log(`\nskill-lint (rubric=${rubric}, profile=${profile}, threshold=${threshold}):`);
     console.log(`  ${files.length} file(s) scanned`);
     console.log(`  ${failedCount} below threshold`);
     console.log(`  average score: ${averageScore}/100`);
@@ -351,8 +355,8 @@ export const skillLintHandler = {
     category: 'utility',
     aliases: ['-skill-lint', '--skill-lint'],
     async execute(ctx) {
-        const { targets, rubric, json } = parseArgs(ctx.args);
-        const report = await lintSkills(targets, rubric);
+        const { targets, rubric, profile, json } = parseArgs(ctx.args);
+        const report = await lintSkills(targets, rubric, profile);
         if (json) {
             console.log(JSON.stringify(report, null, 2));
         }

package/dist/src/cli/handlers/use.js

@@ -17,7 +17,7 @@ import { createScriptRunner } from './script-runner.js';
 import { getFrameworkRoot, getVersionInfo } from '../../channel/manager.mjs';
 import { getRegistry } from '../../extensions/registry.js';
 import { registerDeployedExtensions } from '../../extensions/deployment-registration.js';
-import { registerCliCommands, registerHooks } from '../cli-extension-loader.js';
+import { loadCliCommandsContribution, registerCliCommands, registerHooks, } from '../cli-extension-loader.js';
 import { translateSkillsToCommands, providerNeedsCommands } from '../../plugin/skill-command-translator.js';
 import * as ui from '../ui.js';
 import { readAiwgConfig, writeAiwgConfig, updateInstalled, hashManifest, emptyConfig, getProjectDir } from '../../config/aiwg-config.js';
@@ -270,6 +270,25 @@ export function addonPath(frameworkRoot, name) {
     const folderName = resolveAddonFolderName(name);
     return path.join(frameworkRoot, 'agentic/code/addons', folderName);
 }
+async function registerSourceCliCommands(opts) {
+    const contribution = await loadCliCommandsContribution(opts.source);
+    if (!contribution)
+        return 0;
+    const { manifest, commandsSource } = contribution;
+    const count = Object.keys(manifest.subcommands).length;
+    if (opts.dryRun) {
+        ui.dim(`  [dry-run] Would register CLI namespace '${manifest.namespace}' (${count} subcommands)`);
+        return count;
+    }
+    await registerCliCommands(opts.target, manifest.namespace, manifest.description || opts.fallbackDescription, commandsSource, manifest.subcommands);
+    ui.success(`CLI namespace '${manifest.namespace}' registered (${count} subcommands)`);
+    if (opts.provider === 'claude') {
+        const registeredHooks = await registerHooks(opts.target, manifest.namespace, manifest.subcommands);
+        for (const hook of registeredHooks)
+            ui.success(`Hook registered: ${hook}`);
+    }
+    return count;
+}
 function getProviderPaths(provider) {
     const paths = getProviderArtifactPathStrings(provider) ?? getProviderArtifactPathStrings('claude');
     if (!paths)
@@ -777,54 +796,82 @@ async function deployOneProjectLocalBundle(opts) {
     const { bundle, ctx, frameworkRoot, provider, target, dryRun, verbose, quiet, modelArgs } = opts;
     const counts = await countBundleSourceArtifacts(bundle.artifactPath);
     const artifactTotal = counts.agents + counts.commands + counts.skills + counts.rules;
+    let cliCommandCount = 0;
+    try {
+        const contribution = await loadCliCommandsContribution(bundle.artifactPath);
+        cliCommandCount = contribution ? Object.keys(contribution.manifest.subcommands).length : 0;
+    }
+    catch (error) {
+        ui.warn(`Invalid CLI contribution for project-local '${bundle.id}': ${error.message}`);
+        return { exitCode: 1, counts };
+    }
     if (verbose || dryRun) {
-        ui.dim(`  Artifacts: agents=${counts.agents} commands=${counts.commands} skills=${counts.skills} rules=${counts.rules}`);
+        ui.dim(`  Artifacts: agents=${counts.agents} commands=${counts.commands} skills=${counts.skills} rules=${counts.rules} cli=${cliCommandCount}`);
     }
-    if (artifactTotal === 0) {
-        ui.warn(`Project-local ${bundle.type} '${bundle.id}' has no deployable agents, commands, skills, or rules at ${bundle.artifactPath}`);
+    if (artifactTotal === 0 && cliCommandCount === 0) {
+        ui.warn(`Project-local ${bundle.type} '${bundle.id}' has no deployable agents, commands, skills, rules, or CLI commands at ${bundle.artifactPath}`);
         return { exitCode: 1, counts };
     }
-    const runner = createScriptRunner(frameworkRoot);
-    const args = [
-        '--source', bundle.artifactPath,
-        '--deploy-commands', '--deploy-skills', '--deploy-rules',
-        '--provider', provider,
-        '--target', target,
-        // Project-local skills MUST land in the per-project skills tier
-        // (#1228 follow-up). Default deploy mode after #1217 is no-copy +
-        // index-driven discovery, but that model assumes upstream skills at
-        // $AIWG_ROOT — project-local bundles live under the project's .aiwg/
-        // tree and aren't reachable via `aiwg discover` of the framework
-        // graph. Without --copy-all, the bundle's rules deploy but its skills
-        // never reach <provider>/.aiwg/skills/, leaving them invisible to
-        // both the platform and the index.
-        '--copy-all',
-        ...modelArgs,
-    ];
-    if (dryRun)
-        args.push('--dry-run');
-    if (verbose)
-        args.push('--verbose');
-    if (quiet && !verbose)
-        args.push('--quiet');
-    // Project-local bundles are addon-shaped — never trigger the legacy commands
-    // migration prompt (which is only relevant for full-framework deploys).
-    args.push('--skip-commands-migration');
-    const captureOpts = quiet && !verbose ? { capture: true } : {};
-    // Inject AIWG_ROOT so the deploy subprocess can resolve the upstream AIWG
-    // install root. The bundle's `--source` is its project-local path, so
-    // `computeAllKernelNames`/`computeAllArtifactBasenames` (which walk up from
-    // srcRoot looking for agentic/code/{frameworks,addons}) would otherwise fail
-    // and prune the provider's kernel skill directory with an empty desired set
-    // (#123). `frameworkRoot` is the AIWG install root that owns these trees.
-    const result = await runner.run('tools/agents/deploy-agents.mjs', args, {
-        ...captureOpts,
-        env: { AIWG_ROOT: frameworkRoot },
-    });
+    let exitCode = 0;
+    if (artifactTotal > 0) {
+        const runner = createScriptRunner(frameworkRoot);
+        const args = [
+            '--source', bundle.artifactPath,
+            '--deploy-commands', '--deploy-skills', '--deploy-rules',
+            '--provider', provider,
+            '--target', target,
+            // Project-local skills MUST land in the per-project skills tier
+            // (#1228 follow-up). Default deploy mode after #1217 is no-copy +
+            // index-driven discovery, but that model assumes upstream skills at
+            // $AIWG_ROOT — project-local bundles live under the project's .aiwg/
+            // tree and aren't reachable via `aiwg discover` of the framework
+            // graph. Without --copy-all, the bundle's rules deploy but its skills
+            // never reach <provider>/.aiwg/skills/, leaving them invisible to
+            // both the platform and the index.
+            '--copy-all',
+            ...modelArgs,
+        ];
+        if (dryRun)
+            args.push('--dry-run');
+        if (verbose)
+            args.push('--verbose');
+        if (quiet && !verbose)
+            args.push('--quiet');
+        // Project-local bundles are addon-shaped — never trigger the legacy commands
+        // migration prompt (which is only relevant for full-framework deploys).
+        args.push('--skip-commands-migration');
+        const captureOpts = quiet && !verbose ? { capture: true } : {};
+        // Inject AIWG_ROOT so the deploy subprocess can resolve the upstream AIWG
+        // install root. The bundle's `--source` is its project-local path, so
+        // `computeAllKernelNames`/`computeAllArtifactBasenames` (which walk up from
+        // srcRoot looking for agentic/code/{frameworks,addons}) would otherwise fail
+        // and prune the provider's kernel skill directory with an empty desired set
+        // (#123). `frameworkRoot` is the AIWG install root that owns these trees.
+        const result = await runner.run('tools/agents/deploy-agents.mjs', args, {
+            ...captureOpts,
+            env: { AIWG_ROOT: frameworkRoot },
+        });
+        exitCode = result.exitCode;
+    }
+    if (exitCode === 0 && cliCommandCount > 0) {
+        try {
+            await registerSourceCliCommands({
+                source: bundle.artifactPath,
+                target,
+                provider,
+                dryRun,
+                fallbackDescription: `${bundle.id} project-local commands`,
+            });
+        }
+        catch (error) {
+            ui.warn(`Failed to register CLI commands for project-local '${bundle.id}': ${error.message}`);
+            exitCode = 1;
+        }
+    }
     // Approximate counts from the bundle's source dirs (deploy-agents.mjs is
     // idempotent and copies file-for-file from these dirs)
     void ctx;
-    return { exitCode: result.exitCode, counts };
+    return { exitCode, counts };
 }
 /**
  * Discover and deploy artifact-bearing project-local bundles from
@@ -1461,7 +1508,25 @@ async function deploySourceDirectory(opts) {
     if (opts.quiet)
         args.unshift('--quiet');
     const runner = createScriptRunner(opts.frameworkRoot);
-    return runner.run('tools/agents/deploy-agents.mjs', args, opts.quiet ? { capture: true } : {});
+    const result = await runner.run('tools/agents/deploy-agents.mjs', args, opts.quiet ? { capture: true } : {});
+    if (result.exitCode === 0) {
+        try {
+            await registerSourceCliCommands({
+                source: opts.source,
+                target: opts.target,
+                provider: opts.provider,
+                dryRun: opts.dryRun,
+                fallbackDescription: `${path.basename(opts.source)} addon commands`,
+            });
+        }
+        catch (error) {
+            return {
+                exitCode: 1,
+                message: `Failed to register addon CLI commands: ${error.message}`,
+            };
+        }
+    }
+    return result;
 }
 /**
  * Use command handler
@@ -1940,25 +2005,19 @@ export class UseHandler {
             }
             // Register CLI commands if addon declares them
             try {
-                const manifestPath = path.join(addonSource, 'manifest.json');
-                const manifestContent = await fs.readFile(manifestPath, 'utf-8');
-                const manifest = JSON.parse(manifestContent);
-                if (manifest.cli_commands?.namespace && manifest.cli_commands?.subcommands) {
-                    const cmds = manifest.cli_commands;
-                    const commandsSource = path.join(addonSource, cmds.entry || 'commands/');
-                    await registerCliCommands(target, cmds.namespace, cmds.description || `${framework} addon commands`, commandsSource, cmds.subcommands);
-                    ui.success(`CLI namespace '${cmds.namespace}' registered (${Object.keys(cmds.subcommands).length} subcommands)`);
-                    // Register Claude Code hooks for subcommands with hook_event
-                    if (provider === 'claude') {
-                        const registeredHooks = await registerHooks(target, cmds.namespace, cmds.subcommands);
-                        for (const hook of registeredHooks) {
-                            ui.success(`Hook registered: ${hook}`);
-                        }
-                    }
-                }
+                await registerSourceCliCommands({
+                    source: addonSource,
+                    target,
+                    provider,
+                    dryRun: false,
+                    fallbackDescription: `${framework} addon commands`,
+                });
             }
             catch (error) {
-                ui.warn(`Failed to register CLI commands: ${error instanceof Error ? error.message : String(error)}`);
+                return {
+                    exitCode: 1,
+                    message: `Failed to register CLI commands: ${error instanceof Error ? error.message : String(error)}`,
+                };
             }
             // Profile picker for addons with memory topology and multiple templates
             try {
@@ -2247,6 +2306,18 @@ export class UseHandler {
                 if (result.exitCode !== 0) {
                     return result;
                 }
+                try {
+                    await registerSourceCliCommands({
+                        source,
+                        target,
+                        provider,
+                        dryRun,
+                        fallbackDescription: `${addon} addon commands`,
+                    });
+                }
+                catch (error) {
+                    ui.warn(`Failed to register CLI commands for '${addon}': ${error.message}`);
+                }
             }
             // Deploy all extensions from agentic/code/extensions/* (#1222).
             // Extensions are addon-shaped bundles (manifest type: "addon") that live
@@ -2267,6 +2338,18 @@ export class UseHandler {
                 if (result.exitCode !== 0) {
                     return result;
                 }
+                try {
+                    await registerSourceCliCommands({
+                        source,
+                        target,
+                        provider,
+                        dryRun,
+                        fallbackDescription: `${ext} extension commands`,
+                    });
+                }
+                catch (error) {
+                    ui.warn(`Failed to register CLI commands for '${ext}': ${error.message}`);
+                }
             }
         }
         // Deploy project-local bundles (#1035). Auto-runs after upstream addons unless

package/dist/src/cli/handlers/utilities.js

@@ -130,8 +130,8 @@ function countSentences(s) {
     return matches.length + (endsWithTerminator ? 0 : 1);
 }
 /**
- * Scan source SKILL.md files in `agentic/code/` for namespace issues:
- * - Missing `namespace: aiwg`
+ * Scan canonical AIWG source SKILL.md files in `agentic/code/` for policy issues:
+ * - Missing the AIWG-only `namespace: aiwg` source convention
  * - Slug (`aiwg-{name}`) that would shadow an AIWG CLI command
  *
  * Returns lines suitable for console output, or empty array if clean.
@@ -263,12 +263,14 @@ export const validateMetadataHandler = {
         const result = await runner.run('tools/cli/validate-metadata.mjs', scriptArgs, {
             cwd: ctx.cwd,
         });
-        // Append namespace validation: scan source SKILL.md files
+        // Append canonical AIWG source policy. `namespace` is an AIWG extension,
+        // not an Agent Skills standard requirement; shared conformance is emitted
+        // by validate-metadata.mjs before this source-only convention.
         try {
             const issues = await scanSourceNamespaceIssues(frameworkRoot);
             if (issues.length > 0) {
-                console.log('\n── Namespace validation ──');
-                console.log(`  ${issues.length} skill(s) missing namespace field:`);
+                console.log('\n── AIWG source conventions ──');
+                console.log(`  ${issues.length} canonical source convention issue(s):`);
                 // Show first 20 to avoid flooding output
                 issues.slice(0, 20).forEach(l => console.log(l));
                 if (issues.length > 20) {
@@ -276,11 +278,11 @@ export const validateMetadataHandler = {
                 }
                 // Non-zero exit only in strict mode
                 if (ctx.args.includes('--strict') && result.exitCode === 0) {
-                    return { exitCode: 1, message: `Namespace validation failed: ${issues.length} skill(s) missing namespace field` };
+                    return { exitCode: 1, message: `AIWG source convention validation failed: ${issues.length} issue(s)` };
                 }
             }
             else {
-                console.log('\n── Namespace validation: all skills have namespace field ✓');
+                console.log('\n── AIWG source conventions: all canonical skills include the AIWG namespace extension ✓');
             }
         }
         catch {
@@ -460,6 +462,16 @@ export const doctorHandler = {
         const runner = createScriptRunner(frameworkRoot);
         // Run core doctor diagnostics
         const result = await runner.run('tools/cli/doctor.mjs', ctx.args, { cwd: ctx.cwd });
+        let agentSkillsFailure = false;
+        try {
+            const { buildAgentSkillsDoctorSection } = await import('../../skills/doctor.js');
+            const section = buildAgentSkillsDoctorSection(ctx.cwd || process.cwd());
+            console.log(section.output);
+            agentSkillsFailure = section.hasFailures;
+        }
+        catch (error) {
+            console.log(`\n── Agent Skills conformance ──\n  ⚠ unable to audit: ${error instanceof Error ? error.message : String(error)}`);
+        }
         // Surface feedback escape hatch when doctor finds issues
         if (result.exitCode !== 0) {
             console.log(`
@@ -567,7 +579,9 @@ export const doctorHandler = {
         catch (error) {
             console.log(`\n── Workspace context graph ──\n  ⚠ unable to audit: ${error instanceof Error ? error.message : String(error)}`);
         }
-        return result;
+        return agentSkillsFailure
+            ? { exitCode: 1, message: '' }
+            : result;
     },
 };
 /**