@soleri/cli 1.7.0 → 1.8.0

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,
   };
 }