feat(cli): plan-or-implement choice in stash init

Adds a step before the handoff target picker that asks the user whether
the agent should produce a reviewable plan first or go straight to
implementation. Plan-first is the default — for migrate-existing-column
work the wrong order of operations is hard to recover from, so a plan
checkpoint is the safer default.

Plan mode currently routes only to Claude Code or Codex (AGENTS.md and
the CipherStash Agent / wizard don't yet have planning prompt
templates). The implementation prompt now reads `.cipherstash/plan.md`
as the source of truth for routing if it exists, rather than re-asking
which path applies.

Closes #408

Author: coderdan

.changeset/init-plan-or-implement.md

@@ -0,0 +1,5 @@
+---
+"stash": minor
+---
+
+Add a plan-or-implement choice to `stash init`. After the install/detection steps, the user picks whether the agent handoff should produce a reviewable plan at `.cipherstash/plan.md` first (the recommended default) or go straight to implementation. Plan mode currently routes only to Claude Code or Codex; implement mode preserves the existing four-target picker. The implementation prompt now reads an existing plan as the source of truth for routing rather than re-asking which path applies.

packages/cli/src/commands/init/__tests__/how-to-proceed.test.ts

@@ -0,0 +1,69 @@
+import { describe, expect, it } from 'vitest'
+import type { AgentEnvironment } from '../detect-agents.js'
+import { buildOptions, defaultChoice } from '../steps/how-to-proceed.js'
+import type { InitState } from '../types.js'
+
+function makeAgents(claudeCode: boolean, codex: boolean): AgentEnvironment {
+  return {
+    cli: { claudeCode, codex },
+    project: {
+      claudeDir: false,
+      claudeMd: false,
+      claudeSkillsDir: false,
+      agentsMd: false,
+    },
+    editor: 'unknown',
+  }
+}
+
+const noAgents: InitState = { agents: makeAgents(false, false) }
+const claudeOnly: InitState = { agents: makeAgents(true, false) }
+const codexOnly: InitState = { agents: makeAgents(false, true) }
+
+describe('howToProceed — buildOptions', () => {
+  it('offers all four targets in implement mode', () => {
+    const opts = buildOptions(noAgents, 'implement')
+    const values = opts.map((o) => o.value)
+    expect(values).toEqual(['claude-code', 'codex', 'wizard', 'agents-md'])
+  })
+
+  it('offers only claude-code and codex in plan mode', () => {
+    const opts = buildOptions(noAgents, 'plan')
+    const values = opts.map((o) => o.value)
+    expect(values).toEqual(['claude-code', 'codex'])
+  })
+
+  it('reflects detection state in hints regardless of mode', () => {
+    const implement = buildOptions(claudeOnly, 'implement')
+    const plan = buildOptions(claudeOnly, 'plan')
+
+    const implementClaude = implement.find((o) => o.value === 'claude-code')
+    const planClaude = plan.find((o) => o.value === 'claude-code')
+
+    expect(implementClaude?.hint).toMatch(/detected/)
+    expect(planClaude?.hint).toMatch(/detected/)
+  })
+})
+
+describe('howToProceed — defaultChoice', () => {
+  it('prefers claude-code when detected', () => {
+    expect(defaultChoice(claudeOnly, 'implement')).toBe('claude-code')
+    expect(defaultChoice(claudeOnly, 'plan')).toBe('claude-code')
+  })
+
+  it('prefers codex when claude is absent and codex is detected', () => {
+    expect(defaultChoice(codexOnly, 'implement')).toBe('codex')
+    expect(defaultChoice(codexOnly, 'plan')).toBe('codex')
+  })
+
+  it('falls back to agents-md in implement mode when no CLI is detected', () => {
+    expect(defaultChoice(noAgents, 'implement')).toBe('agents-md')
+  })
+
+  it('falls back to claude-code in plan mode when no CLI is detected', () => {
+    // Plan mode never offers agents-md; claude-code is the listed default
+    // so the picker has a valid initialValue rather than falling through
+    // to a hidden option.
+    expect(defaultChoice(noAgents, 'plan')).toBe('claude-code')
+  })
+})

packages/cli/src/commands/init/index.ts

@@ -4,6 +4,7 @@ import { createDrizzleProvider } from './providers/drizzle.js'
 import { createSupabaseProvider } from './providers/supabase.js'
 import { authenticateStep } from './steps/authenticate.js'
 import { buildSchemaStep } from './steps/build-schema.js'
+import { chooseModeStep } from './steps/choose-mode.js'
 import { gatherContextStep } from './steps/gather-context.js'
 import { howToProceedStep } from './steps/how-to-proceed.js'
 import { installDepsStep } from './steps/install-deps.js'
@@ -25,6 +26,7 @@ const STEPS = [
   installDepsStep,
   installEqlStep,
   gatherContextStep,
+  chooseModeStep,
   howToProceedStep,
   nextStepsStep,
 ]

packages/cli/src/commands/init/lib/__tests__/setup-prompt.test.ts

@@ -10,10 +10,11 @@ const baseCtx: SetupPromptContext = {
   stackInstalled: true,
   cliInstalled: true,
   handoff: 'claude-code',
+  mode: 'implement',
   installedSkills: ['stash-encryption', 'stash-drizzle', 'stash-cli'],
 }
 
-describe('renderSetupPrompt — orient + route', () => {
+describe('renderSetupPrompt — orient + route (implement mode)', () => {
   it('emits integration + package manager in the header', () => {
     const out = renderSetupPrompt(baseCtx)
     expect(out).toContain('Integration: `drizzle`')
@@ -139,4 +140,85 @@ describe('renderSetupPrompt — orient + route', () => {
     expect(out).toContain('serverExternalPackages')
     expect(out).toContain('@cipherstash/protect-ffi')
   })
+
+  it('directs the agent to read .cipherstash/plan.md first if it exists', () => {
+    // Plan mode produces .cipherstash/plan.md; if the user later runs init
+    // again in implement mode, the plan must be the source of truth — not
+    // a re-asked routing question.
+    const out = renderSetupPrompt(baseCtx)
+    expect(out).toContain('.cipherstash/plan.md')
+    expect(out).toMatch(/source of truth/i)
+  })
+})
+
+describe('renderSetupPrompt — plan mode', () => {
+  const planCtx: SetupPromptContext = { ...baseCtx, mode: 'plan' }
+
+  it('frames the deliverable as a plan file, not code changes', () => {
+    const out = renderSetupPrompt(planCtx)
+    expect(out).toContain('# CipherStash setup — write a plan')
+    expect(out).toContain('.cipherstash/plan.md')
+    expect(out).toMatch(/produce a plan file/i)
+  })
+
+  it('explicitly forbids mutating commands during planning', () => {
+    const out = renderSetupPrompt(planCtx)
+    expect(out).toContain('## What you must NOT do')
+    expect(out).toMatch(/db push/)
+    expect(out).toMatch(/encrypt backfill/)
+    expect(out).toMatch(/encrypt cutover/)
+    expect(out).toMatch(/encrypt drop/)
+  })
+
+  it('allows read-only inspection commands', () => {
+    const out = renderSetupPrompt(planCtx)
+    expect(out).toMatch(/db status/)
+    expect(out).toMatch(/Read-only/i)
+  })
+
+  it('tells the agent to offer copying the plan into docs/plans when it exists', () => {
+    const out = renderSetupPrompt(planCtx)
+    expect(out).toContain('docs/plans/')
+    expect(out).toMatch(/offer to copy/i)
+  })
+
+  it('lists project-specific risk classes the plan must cover', () => {
+    const out = renderSetupPrompt(planCtx)
+    expect(out).toMatch(/bundler exclusion/i)
+    expect(out).toMatch(/top-level-await/i)
+    expect(out).toMatch(/partial CipherStash/i)
+  })
+
+  it('requires the plan to identify which lifecycle path applies per column', () => {
+    const out = renderSetupPrompt(planCtx)
+    expect(out).toMatch(/path 1/i)
+    expect(out).toMatch(/path 3/i)
+    expect(out).toMatch(/four-deploy sequence/i)
+  })
+
+  it('still tells the agent its first response is an orientation message, not action', () => {
+    const out = renderSetupPrompt(planCtx)
+    expect(out).toContain('## Your first response')
+    expect(out).toMatch(/orientation message/i)
+  })
+
+  it('references concrete table/column names from .cipherstash/context.json', () => {
+    const out = renderSetupPrompt(planCtx)
+    expect(out).toContain('.cipherstash/context.json')
+  })
+
+  it('preserves the integration + package manager header in plan mode', () => {
+    const out = renderSetupPrompt(planCtx)
+    expect(out).toContain('Integration: `drizzle`')
+    expect(out).toContain('Package manager: `pnpm`')
+  })
+
+  it('does not emit the implement-mode flow walkthroughs verbatim', () => {
+    // Plan mode summarises the two options in one line each rather than
+    // restating the full numbered walkthroughs; the walkthroughs live in
+    // the implement prompt.
+    const out = renderSetupPrompt(planCtx)
+    expect(out).not.toContain('### Add a new encrypted column')
+    expect(out).not.toContain('### Migrate an existing column to encrypted')
+  })
 })