@soleri/cli 1.6.0 → 1.8.0

package/dist/prompts/playbook.js

@@ -0,0 +1,154 @@
+/**
+ * Playbook data for the guided wizard.
+ * Provides curated options with self-explanatory hints,
+ * organized by category. Each list also supports a "custom" escape hatch
+ * with examples and anti-examples so the user is never staring at a blank cursor.
+ */
+export const DOMAIN_OPTIONS = [
+    { value: 'security', label: 'security', hint: 'Vulnerability scanning, threat modeling, secrets detection' },
+    { value: 'code-review', label: 'code-review', hint: 'Pattern enforcement, anti-pattern detection, PR review' },
+    { value: 'testing', label: 'testing', hint: 'Test generation, coverage analysis, mutation testing' },
+    { value: 'api-design', label: 'api-design', hint: 'REST/GraphQL contracts, versioning, error handling' },
+    { value: 'performance', label: 'performance', hint: 'Budgets, profiling, bundle size, query optimization' },
+    { value: 'accessibility', label: 'accessibility', hint: 'WCAG compliance, screen readers, keyboard navigation' },
+    { value: 'architecture', label: 'architecture', hint: 'System design, boundaries, dependency management' },
+    { value: 'database', label: 'database', hint: 'Schema design, migrations, indexing, query tuning' },
+    { value: 'documentation', label: 'documentation', hint: 'API docs, READMEs, changelogs, code comments' },
+    { value: 'devops', label: 'devops', hint: 'CI/CD pipelines, infrastructure as code, deployment' },
+];
+export const CUSTOM_DOMAIN_GUIDANCE = {
+    instruction: 'Define a custom domain (kebab-case)',
+    examples: [
+        'graphql-federation — Schema stitching, subgraph validation, entity resolution',
+        'data-pipeline — ETL jobs, stream processing, data quality checks',
+        'mobile-ux — Touch targets, gesture handling, responsive layouts',
+    ],
+    antiExamples: [
+        'stuff — too vague, what kind of stuff?',
+        'MyDomain — must be kebab-case, not camelCase',
+    ],
+};
+export const PRINCIPLE_CATEGORIES = [
+    {
+        label: 'Quality',
+        options: [
+            { value: 'Simplicity over cleverness', label: 'Simplicity over cleverness' },
+            { value: 'Convention over configuration', label: 'Convention over configuration' },
+            { value: 'Test everything that can break', label: 'Test everything that can break' },
+            { value: 'Respect existing patterns', label: 'Respect existing patterns' },
+        ],
+    },
+    {
+        label: 'Safety',
+        options: [
+            { value: 'Security first', label: 'Security first' },
+            { value: 'Fail closed, not open', label: 'Fail closed, not open' },
+            { value: 'Zero trust by default', label: 'Zero trust by default' },
+            { value: 'Least privilege always', label: 'Least privilege always' },
+        ],
+    },
+    {
+        label: 'Developer Experience',
+        options: [
+            { value: 'Actionable feedback only', label: 'Actionable feedback only' },
+            { value: 'Explain the why, not just the what', label: 'Explain the why, not just the what' },
+            { value: 'Every comment includes a fix suggestion', label: 'Every comment includes a fix suggestion' },
+            { value: 'Design for the consumer, not the implementer', label: 'Design for the consumer, not the implementer' },
+        ],
+    },
+    {
+        label: 'Reliability',
+        options: [
+            { value: 'Graceful degradation over hard failures', label: 'Graceful degradation over hard failures' },
+            { value: 'Automate everything repeatable', label: 'Automate everything repeatable' },
+            { value: 'Observability built in from day one', label: 'Observability built in from day one' },
+            { value: 'Every migration must be reversible', label: 'Every migration must be reversible' },
+        ],
+    },
+];
+export const CUSTOM_PRINCIPLE_GUIDANCE = {
+    instruction: 'Write a custom principle',
+    examples: [
+        'Never suggest any in production without a feature flag',
+        'Prefer composition over inheritance',
+        'Every public API must have a deprecation path before removal',
+    ],
+    antiExamples: [
+        'Write good code — too vague, what does "good" mean?',
+        'Follow best practices — which ones? Be specific.',
+    ],
+};
+// ─── Skills ─────────────────────────────────────────────────
+/** Core skills — always included, never shown in picker. */
+export const CORE_SKILLS = [
+    'brainstorming',
+    'systematic-debugging',
+    'verification-before-completion',
+    'health-check',
+    'context-resume',
+];
+export const SKILL_CATEGORIES = [
+    {
+        label: 'Planning & Execution',
+        options: [
+            { value: 'writing-plans', label: 'writing-plans', hint: 'Structured multi-step planning before code changes' },
+            { value: 'executing-plans', label: 'executing-plans', hint: 'Execute approved plans with review checkpoints' },
+        ],
+    },
+    {
+        label: 'Knowledge & Learning',
+        options: [
+            { value: 'vault-navigator', label: 'vault-navigator', hint: 'Deep-dive vault search and exploration' },
+            { value: 'vault-capture', label: 'vault-capture', hint: 'Persist lessons learned to the knowledge vault' },
+            { value: 'knowledge-harvest', label: 'knowledge-harvest', hint: 'Extract patterns from completed work' },
+            { value: 'brain-debrief', label: 'brain-debrief', hint: 'Post-task intelligence summary and debriefing' },
+        ],
+    },
+    {
+        label: 'Code Quality',
+        options: [
+            { value: 'code-patrol', label: 'code-patrol', hint: 'Scan for anti-patterns and code violations' },
+            { value: 'test-driven-development', label: 'test-driven-development', hint: 'TDD workflow: red, green, refactor' },
+            { value: 'fix-and-learn', label: 'fix-and-learn', hint: 'Fix bugs and capture the lesson for next time' },
+        ],
+    },
+    {
+        label: 'Team & Process',
+        options: [
+            { value: 'retrospective', label: 'retrospective', hint: 'End-of-session retrospective and reflection' },
+            { value: 'second-opinion', label: 'second-opinion', hint: 'Get a fresh perspective on tough decisions' },
+            { value: 'onboard-me', label: 'onboard-me', hint: 'Guided codebase onboarding for new team members' },
+        ],
+    },
+];
+/** Flat list of all optional skill values. */
+export const ALL_OPTIONAL_SKILLS = SKILL_CATEGORIES.flatMap((c) => c.options.map((o) => o.value));
+export const TONE_OPTIONS = [
+    { value: 'precise', label: 'Precise', hint: 'Direct, factual, minimal commentary' },
+    { value: 'mentor', label: 'Mentor', hint: 'Educational, explains the "why" behind suggestions' },
+    { value: 'pragmatic', label: 'Pragmatic', hint: 'Balanced, focuses on actionable outcomes' },
+];
+// ─── Custom field guidance (role, description, greeting) ────
+export const CUSTOM_ROLE_GUIDANCE = {
+    instruction: 'Describe what your agent does (one sentence)',
+    examples: [
+        'Enforces accessibility standards across React components',
+        'Generates and maintains API documentation from code',
+        'Monitors performance budgets and flags regressions',
+    ],
+};
+export const CUSTOM_DESCRIPTION_GUIDANCE = {
+    instruction: 'Describe your agent in detail (10-500 characters)',
+    examples: [
+        'This agent validates GraphQL schemas against federation rules, checks for breaking changes, and ensures consistent naming conventions across subgraphs.',
+    ],
+};
+export const CUSTOM_GREETING_GUIDANCE = {
+    instruction: 'Write a custom greeting (first thing users see)',
+    examples: [
+        "Hola! I'm Salvador — your design system guardian.",
+        'Ready to review. Drop a PR link or describe the issue.',
+        "Hey! Let's make sure your APIs are rock solid.",
+    ],
+};
+//# sourceMappingURL=playbook.js.map

package/dist/prompts/playbook.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"playbook.js","sourceRoot":"","sources":["../../src/prompts/playbook.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@soleri/cli",
-  "version": "1.6.0",
+  "version": "1.8.0",
   "description": "Developer CLI for creating and managing Soleri AI agents.",
   "keywords": [
     "agent",

package/src/commands/create.ts

@@ -12,8 +12,9 @@ export function registerCreate(program: Command): void {
     .command('create')
     .argument('[name]', 'Agent ID (kebab-case)')
     .option('-c, --config <path>', 'Path to JSON config file (skip interactive prompts)')
+    .option('-y, --yes', 'Skip confirmation prompts (use with --config for fully non-interactive)')
     .description('Create a new Soleri agent')
-    .action(async (name?: string, opts?: { config?: string }) => {
+    .action(async (name?: string, opts?: { config?: string; yes?: boolean }) => {
       try {
         let config;
 
@@ -40,6 +41,8 @@ export function registerCreate(program: Command): void {
           }
         }
 
+        const nonInteractive = !!(opts?.yes || opts?.config);
+
         // Hook packs — from config file or interactive prompt
         let selectedPacks: string[] = [];
         if (config.hookPacks && config.hookPacks.length > 0) {
@@ -56,7 +59,7 @@ export function registerCreate(program: Command): void {
             }
             selectedPacks = selectedPacks.filter((pk) => available.includes(pk));
           }
-        } else if (!opts?.config) {
+        } else if (!nonInteractive) {
           const packs = listPacks();
           const packChoices = packs.map((pk) => ({
             value: pk.name,
@@ -81,14 +84,22 @@ export function registerCreate(program: Command): void {
         p.log.info(`Will create ${preview.files.length} files in ${preview.agentDir}`);
         p.log.info(`Facades: ${preview.facades.map((f) => f.name).join(', ')}`);
         p.log.info(`Domains: ${preview.domains.join(', ')}`);
+        if (config.tone) {
+          p.log.info(`Tone: ${config.tone}`);
+        }
+        if (config.skills?.length) {
+          p.log.info(`Skills: ${config.skills.length} selected`);
+        }
         if (selectedPacks.length > 0) {
           p.log.info(`Hook packs: ${selectedPacks.join(', ')}`);
         }
 
-        const confirmed = await p.confirm({ message: 'Create agent?' });
-        if (p.isCancel(confirmed) || !confirmed) {
-          p.outro('Cancelled.');
-          return;
+        if (!nonInteractive) {
+          const confirmed = await p.confirm({ message: 'Create agent?' });
+          if (p.isCancel(confirmed) || !confirmed) {
+            p.outro('Cancelled.');
+            return;
+          }
         }
 
         // Scaffold + auto-build

package/src/commands/doctor.ts

@@ -11,11 +11,14 @@ export function registerDoctor(program: Command): void {
 
       const results = runAllChecks();
       let hasFailures = false;
+      let hasWarnings = false;
 
       for (const r of results) {
         if (r.status === 'pass') log.pass(r.label, r.detail);
-        else if (r.status === 'warn') log.warn(r.label, r.detail);
-        else {
+        else if (r.status === 'warn') {
+          log.warn(r.label, r.detail);
+          hasWarnings = true;
+        } else {
           log.fail(r.label, r.detail);
           hasFailures = true;
         }
@@ -26,6 +29,10 @@ export function registerDoctor(program: Command): void {
       if (hasFailures) {
         log.info('Some checks failed. Fix the issues above and run soleri doctor again.');
         process.exit(1);
+      } else if (hasWarnings) {
+        log.info(
+          'All checks passed with warnings. Run from an agent directory to check agent-specific health.',
+        );
       } else {
         log.info('All checks passed!');
       }

package/src/commands/extend.ts

@@ -0,0 +1,197 @@
+import type { Command } from 'commander';
+import * as p from '@clack/prompts';
+import { existsSync, mkdirSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { detectAgent } from '../utils/agent-context.js';
+
+export function registerExtend(program: Command): void {
+  const extend = program
+    .command('extend')
+    .description('Manage agent extensions — custom ops, facades, middleware');
+
+  extend
+    .command('init')
+    .description('Initialize the extensions directory (if not already present)')
+    .action(async () => {
+      const ctx = detectAgent();
+      if (!ctx) {
+        p.log.error('No agent project detected. Run this from an agent root.');
+        process.exit(1);
+      }
+
+      const extDir = join(ctx.agentPath, 'src', 'extensions');
+      if (existsSync(join(extDir, 'index.ts'))) {
+        p.log.info('Extensions directory already exists.');
+        return;
+      }
+
+      const dirs = ['', 'ops', 'facades', 'middleware'];
+      for (const d of dirs) {
+        mkdirSync(join(extDir, d), { recursive: true });
+      }
+
+      const { generateExtensionsIndex, generateExampleOp } = await import('@soleri/forge/lib');
+      const config = { id: ctx.agentId, name: ctx.agentId } as Parameters<
+        typeof generateExtensionsIndex
+      >[0];
+      writeFileSync(join(extDir, 'index.ts'), generateExtensionsIndex(config), 'utf-8');
+      writeFileSync(join(extDir, 'ops', 'example.ts'), generateExampleOp(config), 'utf-8');
+
+      p.log.success('Extensions directory created at src/extensions/');
+      p.log.info(
+        'Edit src/extensions/index.ts to register your custom ops, facades, and middleware.',
+      );
+    });
+
+  extend
+    .command('add-op')
+    .argument('<name>', 'Operation name in snake_case (e.g., "summarize_pr")')
+    .description('Scaffold a new custom op')
+    .action(async (name: string) => {
+      const ctx = detectAgent();
+      if (!ctx) {
+        p.log.error('No agent project detected. Run this from an agent root.');
+        process.exit(1);
+      }
+
+      const opsDir = join(ctx.agentPath, 'src', 'extensions', 'ops');
+      mkdirSync(opsDir, { recursive: true });
+
+      const fileName = name.replace(/_/g, '-');
+      const filePath = join(opsDir, `${fileName}.ts`);
+
+      if (existsSync(filePath)) {
+        p.log.error(`File already exists: src/extensions/ops/${fileName}.ts`);
+        process.exit(1);
+      }
+
+      const fnName =
+        'create' +
+        name
+          .split('_')
+          .map((w) => w.charAt(0).toUpperCase() + w.slice(1))
+          .join('') +
+        'Op';
+
+      const content = `import { z } from 'zod';
+import type { OpDefinition, AgentRuntime } from '@soleri/core';
+
+export function ${fnName}(runtime: AgentRuntime): OpDefinition {
+  return {
+    name: '${name}',
+    description: 'TODO: describe what this op does',
+    auth: 'read',
+    schema: z.object({
+      // TODO: define your parameters
+    }),
+    handler: async (params) => {
+      // TODO: implement your logic
+      // You have access to runtime.vault, runtime.brain, runtime.planner, etc.
+      return { status: 'ok' };
+    },
+  };
+}
+`;
+
+      writeFileSync(filePath, content, 'utf-8');
+      p.log.success(`Created src/extensions/ops/${fileName}.ts`);
+      p.log.info(`Import ${fnName} in src/extensions/index.ts and add it to the ops array.`);
+    });
+
+  extend
+    .command('add-facade')
+    .argument('<name>', 'Facade name in kebab-case (e.g., "github")')
+    .description('Scaffold a new custom facade')
+    .action(async (name: string) => {
+      const ctx = detectAgent();
+      if (!ctx) {
+        p.log.error('No agent project detected. Run this from an agent root.');
+        process.exit(1);
+      }
+
+      const facadesDir = join(ctx.agentPath, 'src', 'extensions', 'facades');
+      mkdirSync(facadesDir, { recursive: true });
+
+      const filePath = join(facadesDir, `${name}.ts`);
+      if (existsSync(filePath)) {
+        p.log.error(`File already exists: src/extensions/facades/${name}.ts`);
+        process.exit(1);
+      }
+
+      const facadeName = `${ctx.agentId}_${name.replace(/-/g, '_')}`;
+      const className = name
+        .split('-')
+        .map((w) => w.charAt(0).toUpperCase() + w.slice(1))
+        .join('');
+
+      const content = `import { z } from 'zod';
+import type { FacadeConfig, AgentRuntime } from '@soleri/core';
+
+export function create${className}Facade(runtime: AgentRuntime): FacadeConfig {
+  return {
+    name: '${facadeName}',
+    description: 'TODO: describe this facade',
+    ops: [
+      {
+        name: 'status',
+        description: 'TODO: describe this op',
+        auth: 'read',
+        schema: z.object({}),
+        handler: async () => {
+          return { status: 'ok' };
+        },
+      },
+    ],
+  };
+}
+`;
+
+      writeFileSync(filePath, content, 'utf-8');
+      p.log.success(`Created src/extensions/facades/${name}.ts`);
+      p.log.info(`Import and add the facade to src/extensions/index.ts facades array.`);
+      p.log.info(`This will register as MCP tool: ${facadeName}`);
+    });
+
+  extend
+    .command('add-middleware')
+    .argument('<name>', 'Middleware name in kebab-case (e.g., "audit-logger")')
+    .description('Scaffold a new middleware')
+    .action(async (name: string) => {
+      const ctx = detectAgent();
+      if (!ctx) {
+        p.log.error('No agent project detected. Run this from an agent root.');
+        process.exit(1);
+      }
+
+      const mwDir = join(ctx.agentPath, 'src', 'extensions', 'middleware');
+      mkdirSync(mwDir, { recursive: true });
+
+      const filePath = join(mwDir, `${name}.ts`);
+      if (existsSync(filePath)) {
+        p.log.error(`File already exists: src/extensions/middleware/${name}.ts`);
+        process.exit(1);
+      }
+
+      const varName = name.replace(/-([a-z])/g, (_, c) => c.toUpperCase());
+
+      const content = `import type { OpMiddleware } from '@soleri/core';
+
+export const ${varName}: OpMiddleware = {
+  name: '${name}',
+  before: async (ctx) => {
+    // Runs before every op. Return modified params or throw to reject.
+    // console.error(\`[\${ctx.facade}.\${ctx.op}] called\`);
+    return ctx.params;
+  },
+  after: async (ctx) => {
+    // Runs after every op. Return modified result or throw.
+    return ctx.result;
+  },
+};
+`;
+
+      writeFileSync(filePath, content, 'utf-8');
+      p.log.success(`Created src/extensions/middleware/${name}.ts`);
+      p.log.info('Import and add to src/extensions/index.ts middleware array.');
+    });
+}

package/src/commands/list.ts

@@ -1,42 +1,81 @@
 import { resolve } from 'node:path';
+import { homedir } from 'node:os';
+import { existsSync } from 'node:fs';
 import type { Command } from 'commander';
 import { listAgents } from '@soleri/forge/lib';
+import type { AgentInfo } from '@soleri/forge/lib';
 import * as log from '../utils/logger.js';
 
 function pad(s: string, len: number): string {
   return s.length >= len ? s.slice(0, len) : s + ' '.repeat(len - s.length);
 }
 
+function printAgentTable(agents: AgentInfo[]): void {
+  console.log(`  ${pad('ID', 16)}${pad('Domains', 26)}${pad('Built', 8)}${pad('Deps', 8)}Path`);
+  console.log('  ' + '-'.repeat(80));
+
+  for (const agent of agents) {
+    const built = agent.hasDistDir ? '✓' : '✗';
+    const deps = agent.hasNodeModules ? '✓' : '✗';
+    const domains = agent.domains.join(', ') || '(none)';
+    const truncDomains = domains.length > 25 ? domains.slice(0, 22) + '...' : domains;
+    console.log(
+      `  ${pad(agent.id, 16)}${pad(truncDomains, 26)}${pad(built, 8)}${pad(deps, 8)}${agent.path}`,
+    );
+  }
+}
+
 export function registerList(program: Command): void {
   program
     .command('list')
-    .argument('[dir]', 'Directory to scan for agents', process.cwd())
-    .description('List all Soleri agents in a directory')
-    .action((dir: string) => {
-      const targetDir = resolve(dir);
-      const agents = listAgents(targetDir);
-
-      if (agents.length === 0) {
-        log.info(`No agents found in ${targetDir}`);
+    .argument('[dir]', 'Directory to scan for agents')
+    .description('List all Soleri agents in a directory (scans common locations if none given)')
+    .action((dir?: string) => {
+      if (dir) {
+        // Explicit directory — scan only that
+        const targetDir = resolve(dir);
+        const agents = listAgents(targetDir);
+
+        if (agents.length === 0) {
+          log.info(`No agents found in ${targetDir}`);
+          return;
+        }
+
+        log.heading(`Agents in ${targetDir}`);
+        printAgentTable(agents);
+        console.log(`\n  ${agents.length} agent(s) found`);
         return;
       }
 
-      log.heading(`Agents in ${targetDir}`);
+      // No directory given — scan common locations
+      const home = homedir();
+      const scanDirs = [
+        process.cwd(),
+        home,
+        resolve(home, 'agents'),
+        resolve(home, 'projects'),
+      ].filter((d, i, arr) => existsSync(d) && arr.indexOf(d) === i);
+
+      const allAgents: AgentInfo[] = [];
+      for (const d of scanDirs) {
+        allAgents.push(...listAgents(d));
+      }
 
-      // Table header
-      console.log(`  ${pad('ID', 16)}${pad('Domains', 26)}${pad('Built', 8)}${pad('Deps', 8)}Path`);
-      console.log('  ' + '-'.repeat(80));
+      // Deduplicate by path
+      const seen = new Set<string>();
+      const unique = allAgents.filter((a) => {
+        if (seen.has(a.path)) return false;
+        seen.add(a.path);
+        return true;
+      });
 
-      for (const agent of agents) {
-        const built = agent.hasDistDir ? '✓' : '✗';
-        const deps = agent.hasNodeModules ? '✓' : '✗';
-        const domains = agent.domains.join(', ') || '(none)';
-        const truncDomains = domains.length > 25 ? domains.slice(0, 22) + '...' : domains;
-        console.log(
-          `  ${pad(agent.id, 16)}${pad(truncDomains, 26)}${pad(built, 8)}${pad(deps, 8)}${agent.path}`,
-        );
+      if (unique.length === 0) {
+        log.info('No agents found. Create one with: soleri create');
+        return;
       }
 
-      console.log(`\n  ${agents.length} agent(s) found`);
+      log.heading('Soleri Agents');
+      printAgentTable(unique);
+      console.log(`\n  ${unique.length} agent(s) found`);
     });
 }

package/src/main.ts

@@ -1,5 +1,6 @@
 #!/usr/bin/env node
 
+import { createRequire } from 'node:module';
 import { Command } from 'commander';
 import { registerCreate } from './commands/create.js';
 import { registerList } from './commands/list.js';
@@ -11,13 +12,17 @@ import { registerHooks } from './commands/hooks.js';
 import { registerGovernance } from './commands/governance.js';
 import { registerTest } from './commands/test.js';
 import { registerUpgrade } from './commands/upgrade.js';
+import { registerExtend } from './commands/extend.js';
+
+const require = createRequire(import.meta.url);
+const { version } = require('../package.json');
 
 const program = new Command();
 
 program
   .name('soleri')
   .description('Developer CLI for creating and managing Soleri AI agents')
-  .version('1.5.0');
+  .version(version);
 
 registerCreate(program);
 registerList(program);
@@ -29,5 +34,6 @@ registerHooks(program);
 registerGovernance(program);
 registerTest(program);
 registerUpgrade(program);
+registerExtend(program);
 
 program.parse();