feat: simplify agent creation wizard

Author: im10furry

apps/cli/src/commands/agent/agents/ui/AgentsListView.tsx

@@ -199,16 +199,15 @@ export function AgentsListView(props: {
             <Box marginY={1}>{renderCreateNew()}</Box>
           ) : null}
           <Text dimColor>
-            No agents found. Create specialized subagents that the CLI can
-            delegate to.
+            No agents found. Press Enter on Create new agent to start.
           </Text>
           <Text dimColor>
-            Each subagent has its own context window, custom system prompt, and
-            specific tools.
+            Choose Quick draft for the shortest path, or Customize draft when
+            you need tools, model, or color control.
           </Text>
           <Text dimColor>
-            Try creating: Code Reviewer, Code Simplifier, Security Reviewer,
-            Tech Lead, or UX Reviewer.
+            Useful starters: code-reviewer, test-writer, security-reviewer,
+            tech-lead, ux-reviewer.
           </Text>
           {props.source !== 'built-in' &&
           props.agents.some(a => a.source === 'built-in') ? (

apps/cli/src/commands/agent/agents/ui/wizard/Wizard.test.ts

@@ -0,0 +1,52 @@
+import { describe, expect, test } from 'bun:test'
+import { getWizardStepSubtitle } from './Wizard'
+
+describe('getWizardStepSubtitle', () => {
+  test('uses an open-ended label before the setup path is selected', () => {
+    expect(
+      getWizardStepSubtitle(
+        { stepIndex: 0, totalSteps: 10, wizardData: {} },
+        'Choose location',
+      ),
+    ).toBe('Step 1 - Choose location')
+  })
+
+  test('shows the short quick path after generation', () => {
+    expect(
+      getWizardStepSubtitle(
+        {
+          stepIndex: 9,
+          totalSteps: 10,
+          wizardData: { method: 'quickGenerate' },
+        },
+        'Review and save',
+      ),
+    ).toBe('Step 4/4 - Review and save')
+  })
+
+  test('shows the customization path when settings are exposed', () => {
+    expect(
+      getWizardStepSubtitle(
+        {
+          stepIndex: 6,
+          totalSteps: 10,
+          wizardData: { method: 'customGenerate' },
+        },
+        'Select tools',
+      ),
+    ).toBe('Step 4/7 - Select tools')
+  })
+
+  test('shows the full manual path for manual setup', () => {
+    expect(
+      getWizardStepSubtitle(
+        {
+          stepIndex: 3,
+          totalSteps: 10,
+          wizardData: { method: 'manual' },
+        },
+        'Name the agent',
+      ),
+    ).toBe('Step 3/9 - Name the agent')
+  })
+})

apps/cli/src/commands/agent/agents/ui/wizard/Wizard.tsx

@@ -1,6 +1,6 @@
 import React, { useCallback, useMemo, useState } from 'react'
 import { Instructions, Panel } from '../components'
-import type { WizardData } from './types'
+import type { WizardData, WizardMethod } from './types'
 
 export type WizardContextValue = {
   stepIndex: number
@@ -14,6 +14,28 @@ export type WizardContextValue = {
   done: () => void
 }
 
+const WIZARD_PATHS: Record<WizardMethod, number[]> = {
+  quickGenerate: [0, 1, 2, 9],
+  customGenerate: [0, 1, 2, 6, 7, 8, 9],
+  manual: [0, 1, 3, 4, 5, 6, 7, 8, 9],
+}
+
+export function getWizardStepSubtitle(
+  ctx: Pick<WizardContextValue, 'stepIndex' | 'totalSteps' | 'wizardData'>,
+  subtitle: string,
+): string {
+  const method = ctx.wizardData.method
+  if (!method) return `Step ${ctx.stepIndex + 1} - ${subtitle}`
+
+  const path = WIZARD_PATHS[method]
+  const pathIndex = path.indexOf(ctx.stepIndex)
+  if (pathIndex === -1) {
+    return `Step ${ctx.stepIndex + 1}/${ctx.totalSteps} - ${subtitle}`
+  }
+
+  return `Step ${pathIndex + 1}/${path.length} - ${subtitle}`
+}
+
 export function Wizard(props: {
   steps: Array<(ctx: WizardContextValue) => React.ReactNode>
   initialData?: WizardData

apps/cli/src/commands/agent/agents/ui/wizard/steps/StepAgentType.tsx

@@ -4,7 +4,11 @@ import TextInput from '#ui-ink/components/TextInput'
 import { useKeypress } from '#ui-ink/hooks/useKeypress'
 import { validateAgentType } from '../../../generation'
 import { themeColor } from '../../colors'
-import { WizardPanel, type WizardContextValue } from '../Wizard'
+import {
+  getWizardStepSubtitle,
+  WizardPanel,
+  type WizardContextValue,
+} from '../Wizard'
 
 export function StepAgentType({ ctx }: { ctx: WizardContextValue }) {
   const [value, setValue] = useState(ctx.wizardData.agentType ?? '')
@@ -33,7 +37,7 @@ export function StepAgentType({ ctx }: { ctx: WizardContextValue }) {
 
   return (
     <WizardPanel
-      subtitle="Agent type (identifier)"
+      subtitle={getWizardStepSubtitle(ctx, 'Name the agent')}
       footerText="Press Enter to continue - Esc to go back"
     >
       <Box flexDirection="column" marginTop={1} gap={1}>
@@ -46,7 +50,10 @@ export function StepAgentType({ ctx }: { ctx: WizardContextValue }) {
           cursorOffset={cursorOffset}
           onChangeCursorOffset={setCursorOffset}
         />
-        <Text dimColor>e.g., code-reviewer, tech-lead, etc</Text>
+        <Text dimColor>
+          Use a short lowercase name, usually 2-4 words: code-reviewer,
+          test-writer, tech-lead.
+        </Text>
         {error ? <Text color={themeColor('error')}>{error}</Text> : null}
       </Box>
     </WizardPanel>

apps/cli/src/commands/agent/agents/ui/wizard/steps/StepChooseColor.tsx

@@ -1,11 +1,18 @@
 import React from 'react'
-import { Box } from 'ink'
+import { Box, Text } from 'ink'
 import { ColorPicker } from '../../ColorPicker'
-import type { AgentColor } from '../../types'
-import { DEFAULT_AGENT_MODEL } from '../../types'
+import {
+  COLOR_OPTIONS,
+  DEFAULT_AGENT_MODEL,
+  type AgentColor,
+} from '../../types'
 import type { WizardFinalAgent } from '../types'
 import { useKeypress } from '#ui-ink/hooks/useKeypress'
-import { WizardPanel, type WizardContextValue } from '../Wizard'
+import {
+  getWizardStepSubtitle,
+  WizardPanel,
+  type WizardContextValue,
+} from '../Wizard'
 
 export function StepChooseColor({ ctx }: { ctx: WizardContextValue }) {
   useKeypress((_input, key) => {
@@ -16,6 +23,12 @@ export function StepChooseColor({ ctx }: { ctx: WizardContextValue }) {
   })
 
   const agentType = ctx.wizardData.agentType ?? 'agent'
+  const currentColor = COLOR_OPTIONS.includes(
+    ctx.wizardData.selectedColor as AgentColor,
+  )
+    ? (ctx.wizardData.selectedColor as AgentColor)
+    : 'automatic'
+
   const onConfirm = (color: AgentColor) => {
     const selectedColor = color === 'automatic' ? undefined : color
     const finalAgent: WizardFinalAgent = {
@@ -37,13 +50,17 @@ export function StepChooseColor({ ctx }: { ctx: WizardContextValue }) {
 
   return (
     <WizardPanel
-      subtitle="Choose background color"
+      subtitle={getWizardStepSubtitle(ctx, 'Choose color')}
       footerText="Press Up/Down to navigate - Enter to select - Esc to go back"
     >
-      <Box marginTop={1}>
+      <Box flexDirection="column" marginTop={1} gap={1}>
+        <Text dimColor>
+          Automatic is fine. Pick a color only to make busy agent lists easier
+          to scan.
+        </Text>
         <ColorPicker
           agentName={agentType}
-          currentColor="automatic"
+          currentColor={currentColor}
           onConfirm={onConfirm}
         />
       </Box>

apps/cli/src/commands/agent/agents/ui/wizard/steps/StepChooseLocation.tsx

@@ -1,8 +1,12 @@
 import React from 'react'
-import { Box } from 'ink'
+import { Box, Text } from 'ink'
 import { Select } from '#ui-ink/components/CustomSelect/select'
 import { useKeypress } from '#ui-ink/hooks/useKeypress'
-import { WizardPanel, type WizardContextValue } from '../Wizard'
+import {
+  getWizardStepSubtitle,
+  WizardPanel,
+  type WizardContextValue,
+} from '../Wizard'
 
 export function StepChooseLocation({ ctx }: { ctx: WizardContextValue }) {
   useKeypress((_input, key) => {
@@ -14,15 +18,24 @@ export function StepChooseLocation({ ctx }: { ctx: WizardContextValue }) {
 
   return (
     <WizardPanel
-      subtitle="Choose location"
+      subtitle={getWizardStepSubtitle(ctx, 'Choose location')}
       footerText="Press Up/Down to navigate - Enter to select - Esc to cancel"
     >
-      <Box marginTop={1}>
+      <Box flexDirection="column" marginTop={1} gap={1}>
+        <Text dimColor>
+          Project is best for this repo. Personal is best for reusable agents.
+        </Text>
         <Select
           key="location-select"
           options={[
-            { label: 'Project (.kode/agents/)', value: 'projectSettings' },
-            { label: 'Personal (~/.kode/agents/)', value: 'userSettings' },
+            {
+              label: 'Project (recommended) - saved in .kode/agents/',
+              value: 'projectSettings',
+            },
+            {
+              label: 'Personal - saved in ~/.kode/agents/',
+              value: 'userSettings',
+            },
           ]}
           onChange={value => {
             const location =

apps/cli/src/commands/agent/agents/ui/wizard/steps/StepChooseMethod.tsx

@@ -1,8 +1,12 @@
 import React from 'react'
-import { Box } from 'ink'
+import { Box, Text } from 'ink'
 import { Select } from '#ui-ink/components/CustomSelect/select'
 import { useKeypress } from '#ui-ink/hooks/useKeypress'
-import { WizardPanel, type WizardContextValue } from '../Wizard'
+import {
+  getWizardStepSubtitle,
+  WizardPanel,
+  type WizardContextValue,
+} from '../Wizard'
 import type { WizardMethod } from '../types'
 
 export function StepChooseMethod({ ctx }: { ctx: WizardContextValue }) {
@@ -15,27 +19,42 @@ export function StepChooseMethod({ ctx }: { ctx: WizardContextValue }) {
 
   return (
     <WizardPanel
-      subtitle="Creation method"
+      subtitle={getWizardStepSubtitle(ctx, 'Choose setup path')}
       footerText="Press Up/Down to navigate - Enter to select - Esc to go back"
     >
-      <Box marginTop={1}>
+      <Box flexDirection="column" marginTop={1} gap={1}>
+        <Text dimColor>
+          Quick draft asks one question and uses recommended defaults. Advanced
+          paths keep every control available.
+        </Text>
         <Select
           key="method-select"
           options={[
             {
-              label: 'Generate with the current model (recommended)',
-              value: 'generate',
+              label: 'Quick draft (recommended) - describe, review, save',
+              value: 'quickGenerate',
+            },
+            {
+              label: 'Customize draft - AI writes it, you tune settings',
+              value: 'customGenerate',
+            },
+            {
+              label: 'Manual setup - write every field yourself',
+              value: 'manual',
             },
-            { label: 'Manual configuration', value: 'manual' },
           ]}
           onChange={value => {
-            const method: WizardMethod =
-              value === 'manual' ? 'manual' : 'generate'
+            const method: WizardMethod = (() => {
+              if (value === 'manual') return 'manual'
+              if (value === 'customGenerate') return 'customGenerate'
+              return 'quickGenerate'
+            })()
             ctx.updateWizardData({
               method,
-              wasGenerated: method === 'generate',
+              wasGenerated: false,
+              finalAgent: undefined,
             })
-            if (method === 'generate') ctx.goNext()
+            if (method !== 'manual') ctx.goNext()
             else ctx.goToStep(3)
           }}
         />

apps/cli/src/commands/agent/agents/ui/wizard/steps/StepConfirm.test.ts

@@ -1,14 +1,52 @@
 import { describe, expect, test } from 'bun:test'
-import { __getConfirmFooterTextForTests } from './StepConfirm'
+import {
+  __getConfirmFooterTextForTests,
+  __getToolSummaryForTests,
+  __splitValidationWarningsForTests,
+} from './StepConfirm'
 
 describe('StepConfirm footer text', () => {
   test('shows save actions while idle', () => {
     expect(__getConfirmFooterTextForTests(false)).toBe(
-      'Press s/Enter to save - e to edit in your editor - Esc to cancel',
+      'Enter/s to save - e to save and edit - Esc to go back',
     )
   })
 
   test('shows saving state while save is in progress', () => {
     expect(__getConfirmFooterTextForTests(true)).toBe('Saving agent...')
   })
 })
+
+describe('StepConfirm tool summary', () => {
+  test('describes the recommended all-tools default', () => {
+    expect(__getToolSummaryForTests(undefined)).toBe(
+      'All tools (recommended default)',
+    )
+  })
+
+  test('describes a no-tools specialist', () => {
+    expect(__getToolSummaryForTests([])).toBe('No tools (strict and limited)')
+  })
+
+  test('formats multiple selected tools', () => {
+    expect(__getToolSummaryForTests(['Read', 'Bash', 'Edit'])).toBe(
+      'Read, Bash, and Edit',
+    )
+  })
+})
+
+describe('StepConfirm validation message grouping', () => {
+  test('shows tool access advisories as notes', () => {
+    expect(
+      __splitValidationWarningsForTests([
+        'Agent has access to all tools',
+        'Unrecognized tools: UnknownTool',
+      ]),
+    ).toEqual({
+      notes: [
+        'All tools are enabled. Limit tools only for stricter specialists.',
+      ],
+      warnings: ['Unrecognized tools: UnknownTool'],
+    })
+  })
+})