@soleri/cli 1.6.0 → 1.8.0

package/src/prompts/archetypes.ts

@@ -0,0 +1,212 @@
+/**
+ * Pre-built agent archetypes that pre-fill the wizard.
+ * Each archetype provides sensible defaults for role, description,
+ * domains, principles, skills, and greeting — so the user can
+ * scaffold a full agent with minimal typing.
+ */
+
+export interface Archetype {
+  value: string;
+  label: string;
+  hint: string;
+  defaults: {
+    role: string;
+    description: string;
+    domains: string[];
+    principles: string[];
+    skills: string[];
+    tone: 'precise' | 'mentor' | 'pragmatic';
+    greetingTemplate: (name: string) => string;
+  };
+}
+
+export const ARCHETYPES: Archetype[] = [
+  {
+    value: 'code-reviewer',
+    label: 'Code Reviewer',
+    hint: 'Catches bugs, enforces patterns, reviews PRs before merge',
+    defaults: {
+      role: 'Catches bugs, enforces code patterns, and reviews pull requests before merge',
+      description:
+        'This agent reviews code for quality issues, anti-patterns, naming conventions, test coverage gaps, and architectural violations. It provides actionable feedback with concrete fix suggestions.',
+      domains: ['code-review', 'architecture'],
+      principles: [
+        'Actionable feedback only',
+        'Respect existing patterns',
+        'Simplicity over cleverness',
+      ],
+      skills: [
+        'writing-plans',
+        'executing-plans',
+        'code-patrol',
+        'fix-and-learn',
+        'second-opinion',
+      ],
+      tone: 'pragmatic',
+      greetingTemplate: (name) =>
+        `Hello! I'm ${name}. Drop a PR link or paste code — I'll review it for bugs, patterns, and quality.`,
+    },
+  },
+  {
+    value: 'security-auditor',
+    label: 'Security Auditor',
+    hint: 'OWASP Top 10, dependency scanning, secrets detection',
+    defaults: {
+      role: 'Identifies vulnerabilities and enforces secure coding practices',
+      description:
+        'This agent scans code for security issues including OWASP Top 10, dependency vulnerabilities, secrets exposure, injection risks, and insecure configurations. It provides remediation guidance with severity ratings.',
+      domains: ['security', 'code-review'],
+      principles: [
+        'Security first',
+        'Fail closed, not open',
+        'Zero trust by default',
+        'Least privilege always',
+      ],
+      skills: [
+        'writing-plans',
+        'executing-plans',
+        'code-patrol',
+        'fix-and-learn',
+        'vault-navigator',
+      ],
+      tone: 'precise',
+      greetingTemplate: (name) =>
+        `Hello! I'm ${name}. I help identify vulnerabilities and enforce secure coding practices across your codebase.`,
+    },
+  },
+  {
+    value: 'api-architect',
+    label: 'API Architect',
+    hint: 'REST/GraphQL design, contract validation, versioning',
+    defaults: {
+      role: 'Designs and validates APIs for consistency, usability, and correctness',
+      description:
+        'This agent reviews API designs for RESTful conventions, GraphQL best practices, versioning strategy, error handling, pagination patterns, and contract consistency. It catches breaking changes before they ship.',
+      domains: ['api-design', 'architecture'],
+      principles: [
+        'Convention over configuration',
+        'Design for the consumer, not the implementer',
+        'Respect existing patterns',
+        'Every migration must be reversible',
+      ],
+      skills: [
+        'writing-plans',
+        'executing-plans',
+        'vault-navigator',
+        'vault-capture',
+        'second-opinion',
+      ],
+      tone: 'mentor',
+      greetingTemplate: (name) =>
+        `Hello! I'm ${name}. Share your API design or schema — I'll review it for consistency, usability, and best practices.`,
+    },
+  },
+  {
+    value: 'test-engineer',
+    label: 'Test Engineer',
+    hint: 'Test generation, coverage analysis, TDD workflow',
+    defaults: {
+      role: 'Generates tests, analyzes coverage, and enforces test-driven development',
+      description:
+        'This agent helps write comprehensive test suites, identifies coverage gaps, suggests edge cases, and guides TDD workflows. It supports unit, integration, and end-to-end testing strategies.',
+      domains: ['testing', 'code-review'],
+      principles: [
+        'Test everything that can break',
+        'Simplicity over cleverness',
+        'Actionable feedback only',
+        'Respect existing patterns',
+      ],
+      skills: [
+        'writing-plans',
+        'executing-plans',
+        'test-driven-development',
+        'fix-and-learn',
+        'code-patrol',
+      ],
+      tone: 'pragmatic',
+      greetingTemplate: (name) =>
+        `Hello! I'm ${name}. Point me at code that needs tests — I'll generate comprehensive suites and identify coverage gaps.`,
+    },
+  },
+  {
+    value: 'devops-pilot',
+    label: 'DevOps Pilot',
+    hint: 'CI/CD pipelines, infrastructure, deployment automation',
+    defaults: {
+      role: 'Manages CI/CD pipelines, infrastructure, and deployment automation',
+      description:
+        'This agent helps design and maintain CI/CD pipelines, Docker configurations, infrastructure as code, monitoring setup, and deployment strategies. It follows reliability engineering best practices.',
+      domains: ['devops', 'architecture'],
+      principles: [
+        'Automate everything repeatable',
+        'Graceful degradation over hard failures',
+        'Observability built in from day one',
+        'Convention over configuration',
+      ],
+      skills: [
+        'writing-plans',
+        'executing-plans',
+        'vault-navigator',
+        'fix-and-learn',
+        'knowledge-harvest',
+      ],
+      tone: 'pragmatic',
+      greetingTemplate: (name) =>
+        `Hello! I'm ${name}. I help with CI/CD, infrastructure, and deployment — describe your setup or issue.`,
+    },
+  },
+  {
+    value: 'database-architect',
+    label: 'Database Architect',
+    hint: 'Schema design, migrations, query optimization',
+    defaults: {
+      role: 'Designs database schemas, manages migrations, and optimizes queries',
+      description:
+        'This agent reviews database designs for normalization, indexing strategy, migration safety, query performance, and data integrity. It supports SQL and NoSQL patterns.',
+      domains: ['database', 'performance'],
+      principles: [
+        'Every migration must be reversible',
+        'Convention over configuration',
+        'Test everything that can break',
+        'Simplicity over cleverness',
+      ],
+      skills: [
+        'writing-plans',
+        'executing-plans',
+        'vault-navigator',
+        'vault-capture',
+        'knowledge-harvest',
+      ],
+      tone: 'precise',
+      greetingTemplate: (name) =>
+        `Hello! I'm ${name}. Share your schema, migration, or query — I'll review it for correctness and performance.`,
+    },
+  },
+  {
+    value: 'full-stack',
+    label: 'Full-Stack Assistant',
+    hint: 'General-purpose dev helper across the entire stack',
+    defaults: {
+      role: 'A general-purpose development assistant across the full stack',
+      description:
+        'This agent helps with frontend, backend, database, testing, and deployment tasks. It provides balanced guidance across the entire stack without deep specialization in any single area.',
+      domains: ['code-review', 'testing', 'architecture'],
+      principles: [
+        'Simplicity over cleverness',
+        'Test everything that can break',
+        'Respect existing patterns',
+      ],
+      skills: [
+        'writing-plans',
+        'executing-plans',
+        'test-driven-development',
+        'code-patrol',
+        'fix-and-learn',
+        'vault-navigator',
+      ],
+      tone: 'mentor',
+      greetingTemplate: (name) =>
+        `Hello! I'm ${name}. I help across the full stack — frontend, backend, testing, deployment. What are you working on?`,
+    },
+  },
+];

package/src/prompts/create-wizard.ts

@@ -1,31 +1,73 @@
 /**
  * Interactive create wizard using @clack/prompts.
+ *
+ * Guided flow with archetypes, multiselects, and playbook-assisted
+ * custom fields. Happy path: 1 typed field (name), everything else
+ * is Enter / arrow keys / space bar.
  */
 import * as p from '@clack/prompts';
 import type { AgentConfig } from '@soleri/forge/lib';
+import { ARCHETYPES, type Archetype } from './archetypes.js';
+import {
+  DOMAIN_OPTIONS,
+  CUSTOM_DOMAIN_GUIDANCE,
+  PRINCIPLE_CATEGORIES,
+  CUSTOM_PRINCIPLE_GUIDANCE,
+  SKILL_CATEGORIES,
+  CORE_SKILLS,
+  ALL_OPTIONAL_SKILLS,
+  TONE_OPTIONS,
+  CUSTOM_ROLE_GUIDANCE,
+  CUSTOM_DESCRIPTION_GUIDANCE,
+  CUSTOM_GREETING_GUIDANCE,
+} from './playbook.js';
+
+/** Slugify a display name into a kebab-case ID. */
+function slugify(name: string): string {
+  return name
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-|-$/g, '');
+}
 
 /**
  * Run the interactive create wizard and return an AgentConfig.
- * Returns null if the user cancels.
+ * Returns null if the user cancels at any point.
  */
 export async function runCreateWizard(initialName?: string): Promise<AgentConfig | null> {
   p.intro('Create a new Soleri agent');
 
-  const id =
-    initialName ??
-    ((await p.text({
-      message: 'Agent ID (kebab-case)',
-      placeholder: 'my-agent',
-      validate: (v = '') => {
-        if (!/^[a-z][a-z0-9-]*$/.test(v)) return 'Must be kebab-case (e.g., "my-agent")';
-      },
-    })) as string);
+  // ─── Step 1: Archetype ────────────────────────────────────
+  const archetypeChoices = [
+    ...ARCHETYPES.map((a) => ({
+      value: a.value,
+      label: a.label,
+      hint: a.hint,
+    })),
+    {
+      value: '_custom',
+      label: '\u2726 Create Custom',
+      hint: "I'll guide you through defining your own agent type",
+    },
+  ];
 
-  if (p.isCancel(id)) return null;
+  const archetypeValue = await p.select({
+    message: 'What kind of agent are you building?',
+    options: archetypeChoices,
+  });
+
+  if (p.isCancel(archetypeValue)) return null;
+
+  const archetype: Archetype | undefined = ARCHETYPES.find((a) => a.value === archetypeValue);
+  const isCustom = archetypeValue === '_custom';
+
+  // ─── Step 2: Display name ─────────────────────────────────
+  const nameDefault = archetype ? archetype.label : undefined;
 
   const name = (await p.text({
     message: 'Display name',
-    placeholder: 'My Agent',
+    placeholder: nameDefault ?? 'My Agent',
+    initialValue: initialName ?? nameDefault,
     validate: (v) => {
       if (!v || v.length > 50) return 'Required (max 50 chars)';
     },
@@ -33,81 +75,313 @@ export async function runCreateWizard(initialName?: string): Promise<AgentConfig
 
   if (p.isCancel(name)) return null;
 
-  const role = (await p.text({
-    message: 'Role (one line)',
-    placeholder: 'A helpful AI assistant for...',
-    validate: (v) => {
-      if (!v || v.length > 100) return 'Required (max 100 chars)';
+  // ─── Step 3: Agent ID (auto-derived, confirm or edit) ─────
+  const autoId = slugify(name);
+
+  const id = (await p.text({
+    message: 'Agent ID (auto-generated, press Enter to accept)',
+    placeholder: autoId,
+    initialValue: autoId,
+    validate: (v = '') => {
+      if (!/^[a-z][a-z0-9-]*$/.test(v)) return 'Must be kebab-case (e.g., "my-agent")';
     },
   })) as string;
 
-  if (p.isCancel(role)) return null;
+  if (p.isCancel(id)) return null;
 
-  const description = (await p.text({
-    message: 'Description',
-    placeholder: 'This agent helps developers with...',
-    validate: (v) => {
-      if (!v || v.length < 10 || v.length > 500) return 'Required (10-500 chars)';
-    },
-  })) as string;
+  // ─── Step 4: Role ─────────────────────────────────────────
+  let role: string;
 
-  if (p.isCancel(description)) return null;
+  if (isCustom) {
+    p.note(
+      [
+        CUSTOM_ROLE_GUIDANCE.instruction,
+        '',
+        'Examples:',
+        ...CUSTOM_ROLE_GUIDANCE.examples.map((e) => `  "${e}"`),
+      ].join('\n'),
+      '\u2726 Custom Agent Playbook',
+    );
 
-  const domainsRaw = (await p.text({
-    message: 'Domains (comma-separated, kebab-case)',
-    placeholder: 'api-design, security, testing',
-    validate: (v = '') => {
-      const parts = v
-        .split(',')
-        .map((s) => s.trim())
-        .filter(Boolean);
-      if (parts.length === 0) return 'At least one domain required';
-      for (const d of parts) {
-        if (!/^[a-z][a-z0-9-]*$/.test(d)) return `Invalid domain "${d}" — must be kebab-case`;
-      }
-    },
-  })) as string;
+    const customRole = (await p.text({
+      message: 'What does your agent do? (one sentence)',
+      placeholder: 'Validates GraphQL schemas against federation rules',
+      validate: (v) => {
+        if (!v || v.length > 100) return 'Required (max 100 chars)';
+      },
+    })) as string;
 
-  if (p.isCancel(domainsRaw)) return null;
+    if (p.isCancel(customRole)) return null;
+    role = customRole;
+  } else {
+    const prefilledRole = archetype!.defaults.role;
+    const editedRole = (await p.text({
+      message: 'Role (pre-filled, press Enter to accept)',
+      initialValue: prefilledRole,
+      validate: (v) => {
+        if (!v || v.length > 100) return 'Required (max 100 chars)';
+      },
+    })) as string;
 
-  const domains = domainsRaw
-    .split(',')
-    .map((s) => s.trim())
-    .filter(Boolean);
+    if (p.isCancel(editedRole)) return null;
+    role = editedRole;
+  }
 
-  const principlesRaw = (await p.text({
-    message: 'Principles (one per line)',
-    placeholder: 'Security first\nSimplicity over cleverness\nTest everything',
-    validate: (v = '') => {
-      const lines = v
-        .split('\n')
-        .map((s) => s.trim())
-        .filter(Boolean);
-      if (lines.length === 0) return 'At least one principle required';
-      if (lines.length > 10) return 'Max 10 principles';
+  // ─── Step 5: Description ──────────────────────────────────
+  let description: string;
+
+  if (isCustom) {
+    p.note(
+      [
+        CUSTOM_DESCRIPTION_GUIDANCE.instruction,
+        '',
+        'Example:',
+        ...CUSTOM_DESCRIPTION_GUIDANCE.examples.map((e) => `  "${e}"`),
+      ].join('\n'),
+      '\u2726 Description',
+    );
+
+    const customDesc = (await p.text({
+      message: 'Describe your agent in detail',
+      placeholder: 'This agent helps developers with...',
+      validate: (v) => {
+        if (!v || v.length < 10 || v.length > 500) return 'Required (10-500 chars)';
+      },
+    })) as string;
+
+    if (p.isCancel(customDesc)) return null;
+    description = customDesc;
+  } else {
+    const prefilledDesc = archetype!.defaults.description;
+    const editedDesc = (await p.text({
+      message: 'Description (pre-filled, press Enter to accept)',
+      initialValue: prefilledDesc,
+      validate: (v) => {
+        if (!v || v.length < 10 || v.length > 500) return 'Required (10-500 chars)';
+      },
+    })) as string;
+
+    if (p.isCancel(editedDesc)) return null;
+    description = editedDesc;
+  }
+
+  // ─── Step 6: Domains (multiselect) ────────────────────────
+  const preselectedDomains = new Set(archetype?.defaults.domains ?? []);
+
+  const domainChoices = [
+    ...DOMAIN_OPTIONS.map((d) => ({
+      value: d.value,
+      label: d.label,
+      hint: d.hint,
+    })),
+    {
+      value: '_custom',
+      label: '\u2726 Add custom domain...',
+      hint: 'Define your own domain with playbook guidance',
     },
-  })) as string;
+  ];
 
-  if (p.isCancel(principlesRaw)) return null;
+  // Pre-select archetype domains via initialValues
+  const domainSelection = await p.multiselect({
+    message: 'Select domains (areas of expertise)',
+    options: domainChoices,
+    initialValues: [...preselectedDomains],
+    required: true,
+  });
 
-  const principles = principlesRaw
-    .split('\n')
-    .map((s) => s.trim())
-    .filter(Boolean);
+  if (p.isCancel(domainSelection)) return null;
 
-  const greeting = (await p.text({
+  const domains = (domainSelection as string[]).filter((d) => d !== '_custom');
+  const wantsCustomDomain = (domainSelection as string[]).includes('_custom');
+
+  if (wantsCustomDomain) {
+    p.note(
+      [
+        CUSTOM_DOMAIN_GUIDANCE.instruction,
+        '',
+        'Examples:',
+        ...CUSTOM_DOMAIN_GUIDANCE.examples.map((e) => `  ${e}`),
+        '',
+        'Avoid:',
+        ...CUSTOM_DOMAIN_GUIDANCE.antiExamples.map((e) => `  \u2717 ${e}`),
+      ].join('\n'),
+      '\u2726 Custom Domain',
+    );
+
+    const customDomain = (await p.text({
+      message: 'Custom domain name (kebab-case)',
+      placeholder: 'graphql-federation',
+      validate: (v = '') => {
+        if (!/^[a-z][a-z0-9-]*$/.test(v)) return 'Must be kebab-case';
+        if (domains.includes(v)) return 'Already selected';
+      },
+    })) as string;
+
+    if (!p.isCancel(customDomain)) {
+      domains.push(customDomain);
+    }
+  }
+
+  if (domains.length === 0) {
+    p.log.error('At least one domain is required');
+    return null;
+  }
+
+  // ─── Step 7: Principles (multiselect) ─────────────────────
+  const preselectedPrinciples = new Set(archetype?.defaults.principles ?? []);
+
+  // Flatten categories into a single options list with group labels
+  const principleChoices = PRINCIPLE_CATEGORIES.flatMap((cat) => cat.options.map((o) => ({
+      value: o.value,
+      label: o.label,
+      hint: cat.label,
+    })));
+
+  principleChoices.push({
+    value: '_custom',
+    label: '\u2726 Add custom principle...',
+    hint: 'Write your own guiding principle',
+  });
+
+  const principleSelection = await p.multiselect({
+    message: 'Select guiding principles',
+    options: principleChoices,
+    initialValues: [...preselectedPrinciples],
+    required: true,
+  });
+
+  if (p.isCancel(principleSelection)) return null;
+
+  const principles = (principleSelection as string[]).filter((p) => p !== '_custom');
+  const wantsCustomPrinciple = (principleSelection as string[]).includes('_custom');
+
+  if (wantsCustomPrinciple) {
+    p.note(
+      [
+        CUSTOM_PRINCIPLE_GUIDANCE.instruction,
+        '',
+        'Good principles are specific and actionable:',
+        ...CUSTOM_PRINCIPLE_GUIDANCE.examples.map((e) => `  \u2713 "${e}"`),
+        '',
+        'Avoid vague principles:',
+        ...CUSTOM_PRINCIPLE_GUIDANCE.antiExamples.map((e) => `  \u2717 ${e}`),
+      ].join('\n'),
+      '\u2726 Custom Principle',
+    );
+
+    const customPrinciple = (await p.text({
+      message: 'Your custom principle',
+      placeholder: 'Every public API must have a deprecation path',
+      validate: (v) => {
+        if (!v) return 'Required';
+        if (v.length > 100) return 'Max 100 chars';
+      },
+    })) as string;
+
+    if (!p.isCancel(customPrinciple)) {
+      principles.push(customPrinciple);
+    }
+  }
+
+  if (principles.length === 0) {
+    p.log.error('At least one principle is required');
+    return null;
+  }
+
+  // ─── Step 8: Communication tone ───────────────────────────
+  const defaultTone = archetype?.defaults.tone ?? 'pragmatic';
+
+  const tone = await p.select({
+    message: 'Communication tone',
+    options: TONE_OPTIONS.map((t) => ({
+      value: t.value,
+      label: t.label,
+      hint: t.hint,
+    })),
+    initialValue: defaultTone,
+  });
+
+  if (p.isCancel(tone)) return null;
+
+  // ─── Step 9: Skills (multiselect) ─────────────────────────
+  const preselectedSkills = new Set(archetype?.defaults.skills ?? []);
+
+  p.note(`Always included: ${CORE_SKILLS.join(', ')}`, 'Core Skills');
+
+  const skillChoices = SKILL_CATEGORIES.flatMap((cat) =>
+    cat.options.map((o) => ({
+      value: o.value,
+      label: o.label,
+      hint: `${o.hint} (${cat.label})`,
+    })),
+  );
+
+  const skillSelection = await p.multiselect({
+    message: 'Select additional skills',
+    options: skillChoices,
+    initialValues: [...preselectedSkills].filter((s) => ALL_OPTIONAL_SKILLS.includes(s)),
+    required: false,
+  });
+
+  if (p.isCancel(skillSelection)) return null;
+
+  const selectedSkills = [...CORE_SKILLS, ...(skillSelection as string[])];
+
+  // ─── Step 10: Greeting (auto or custom) ───────────────────
+  const autoGreeting = archetype
+    ? archetype.defaults.greetingTemplate(name)
+    : `Hello! I'm ${name}. I ${role[0].toLowerCase()}${role.slice(1)}.`;
+
+  const greetingChoice = await p.select({
     message: 'Greeting message',
-    placeholder: `Hello! I'm ${name}, your AI assistant for...`,
-    validate: (v) => {
-      if (!v || v.length < 10 || v.length > 300) return 'Required (10-300 chars)';
-    },
-  })) as string;
+    options: [
+      {
+        value: 'auto',
+        label: `Auto \u2014 "${autoGreeting.length > 70 ? autoGreeting.slice(0, 67) + '...' : autoGreeting}"`,
+        hint: 'Generated from name + role',
+      },
+      {
+        value: 'custom',
+        label: '\u2726 Custom \u2014 Write your own greeting',
+        hint: 'Opens playbook-guided text field',
+      },
+    ],
+    initialValue: 'auto',
+  });
+
+  if (p.isCancel(greetingChoice)) return null;
+
+  let greeting: string;
+
+  if (greetingChoice === 'custom') {
+    p.note(
+      [
+        CUSTOM_GREETING_GUIDANCE.instruction,
+        '',
+        'Examples:',
+        ...CUSTOM_GREETING_GUIDANCE.examples.map((e) => `  "${e}"`),
+      ].join('\n'),
+      '\u2726 Custom Greeting',
+    );
+
+    const customGreeting = (await p.text({
+      message: 'Your greeting',
+      placeholder: `Hello! I'm ${name}...`,
+      validate: (v) => {
+        if (!v || v.length < 10 || v.length > 300) return 'Required (10-300 chars)';
+      },
+    })) as string;
 
-  if (p.isCancel(greeting)) return null;
+    if (p.isCancel(customGreeting)) return null;
+    greeting = customGreeting;
+  } else {
+    greeting = autoGreeting;
+  }
 
+  // ─── Step 11: Output directory ────────────────────────────
   const outputDir = (await p.text({
     message: 'Output directory',
-    defaultValue: process.cwd(),
+    initialValue: process.cwd(),
     placeholder: process.cwd(),
     validate: (v) => {
       if (!v) return 'Required';
@@ -123,7 +397,9 @@ export async function runCreateWizard(initialName?: string): Promise<AgentConfig
     description,
     domains,
     principles,
+    tone: tone as 'precise' | 'mentor' | 'pragmatic',
     greeting,
     outputDir,
+    skills: selectedSkills,
   };
 }