Dan/init plan or implement 1

[calvinbrewer]

We split stash init and added stash impl to gamify the encryption setup with a save-point between scaffolding and the agent handoff, plus an opt-in prompt at end of init to chain straight into stash impl plan mode.

Summary by CodeRabbit

• New Features

  • Added stash impl command to manage planning and implementation workflows separately
  • New --yolo flag bypasses planning checkpoint confirmation
  • stash init now completes scaffolding and checkpoints to stash impl

• Workflow Improvements

  • Planning and implementation are now distinct steps
  • stash impl supports plan-first mode or direct implementation based on existing plan state

[changeset-bot]

🦋 Changeset detected

Latest commit: e16b282

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 2 packages

Name	Type
stash	Minor
@cipherstash/e2e	Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[coderabbitai]

Caution

Review failed

Failed to post review comments

📝 Walkthrough

Walkthrough

This PR introduces a new stash impl command that separates implementation handoff from initialization scaffolding. The command derives its execution mode (plan vs implement) from the presence of .cipherstash/plan.md and the --yolo flag, then dispatches to appropriate agent handoff steps. stash init is shortened to a scaffolding-only checkpoint that prompts users to continue with stash impl.

Changes

Init Scaffolding + Plan/Implement Mode Selection

Layer / File(s)	Summary
Type Definitions packages/cli/src/commands/init/types.ts	Adds InitMode union type ('plan' | 'implement') and optional mode?: InitMode field to InitState.
Core Mode Logic packages/cli/src/commands/impl/index.ts	Implements readContextFile(), deriveMode(cwd, yolo) (checks plan.md presence, handles --yolo confirmation), and implCommand() (loads context, derives mode, builds state, dispatches to howToProceedStep).
Setup Prompting packages/cli/src/commands/init/lib/setup-prompt.ts, packages/cli/src/commands/init/lib/__tests__/setup-prompt.test.ts	Adds PLAN_REL_PATH constant and renderPlanPrompt() function; renderSetupPrompt() now dispatches on ctx.mode to plan vs implement renderers. Plan mode forbids mutations, requires risk/path/sequence coverage, and writes .cipherstash/plan.md.
Context Integration packages/cli/src/commands/init/lib/write-context.ts	buildSetupPromptContext() now includes mode field from state for prompt mode selection.
Mode-Aware Handoff Selection packages/cli/src/commands/impl/steps/how-to-proceed.ts, packages/cli/src/commands/impl/__tests__/how-to-proceed.test.ts	buildOptions() and defaultChoice() now accept mode parameter; in plan mode, menu is limited to claude-code and codex (no wizard/agents-md). howToProceedStep.run() derives mode and varies prompt text accordingly.
Mode-Conditional Agent Handoffs packages/cli/src/commands/impl/steps/handoff-claude.ts, packages/cli/src/commands/impl/steps/handoff-codex.ts	Launch prompts now conditionally instruct agents to produce planning deliverables (no code edits / mutations) when mode === 'plan'; otherwise use existing setup-completion prompt.
Import Wiring packages/cli/src/commands/impl/steps/handoff-agents-md.ts, packages/cli/src/commands/impl/steps/handoff-wizard.ts	Module paths updated from ../lib/... to ../../init/lib/... to reflect new directory structure.
Init Command Restructure packages/cli/src/commands/init/index.ts	STEPS pipeline shortened (removes howToProceedStep and nextStepsStep); post-scaffolding checkpoint now prompts for immediate stash impl continuation in TTY mode, or prints package-manager-aware next-command suggestion. Safely handles missing provider factory.
Deleted Step packages/cli/src/commands/init/steps/next-steps.ts	Removed nextStepsStep entirely; its next-steps formatting logic is now folded into the init checkpoint prompt.
CLI Wiring packages/cli/src/bin/stash.ts, packages/cli/src/commands/index.ts	New impl command is registered in CLI, added to help/examples, and dispatched in main().
Tests packages/cli/src/commands/impl/__tests__/derive-mode.test.ts	Comprehensive coverage for deriveMode() mode selection logic and readContextFile() JSON parsing/error handling.

Sequence Diagram

sequenceDiagram
    actor User
    participant CLI
    participant implCommand as impl Command
    participant howToProceeded as how-to-proceed Step
    participant Agent as Agent (claude-code/codex/...)

    User->>CLI: stash impl [--yolo]
    CLI->>implCommand: implCommand(flags)
    implCommand->>implCommand: readContextFile()
    alt Context missing
        implCommand->>User: Error: run 'stash init' first
    else Context exists
        implCommand->>implCommand: deriveMode(cwd, yolo)
        alt --yolo and no plan.md
            implCommand->>User: Confirm force implement mode?
            alt User declines
                implCommand->>User: Cancelled
            else User confirms
                implCommand->>implCommand: mode = 'implement'
            end
        else plan.md exists
            implCommand->>implCommand: mode = 'implement'
        else No plan.md, no --yolo
            implCommand->>implCommand: mode = 'plan'
        end
        implCommand->>implCommand: buildStateFromContext(mode)
        implCommand->>howToProceeded: run(state, provider)
        howToProceeded->>howToProceeded: buildOptions(mode)<br/>(plan: claude-code, codex only)<br/>(implement: +wizard, agents-md)
        howToProceeded->>howToProceeded: defaultChoice(mode)
        howToProceeded->>User: Select agent or tool
        User->>howToProceeded: Choose handoff
        howToProceeded->>Agent: handoffXxxStep.run(state)<br/>(prompt varies by mode)
        Agent->>User: Interactive handoff<br/>(plan: draft .cipherstash/plan.md)<br/>(implement: execute setup steps)
        Agent->>implCommand: Complete
        implCommand->>User: Mode-specific outro<br/>(plan/implement)
    end

Loading

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

Possibly related issues

• stash init: offer plan-or-implement choice before handoff #408: Directly addresses the plan-vs-implement mode selection feature, touching the same init/how-to-proceed/setup-prompt/handoff code paths and adding InitMode/plan handling.

Possibly related PRs

• cipherstash/stack#395: Continues handoff/init refactoring—splits init vs impl, moves handoff logic into new stash impl entrypoint, updates shared init/handoff modules.
• cipherstash/stack#379: Both touch init "next steps" surface—one makes getNextSteps mode-aware while the main PR removes/rewires the next-steps step entirely.
• cipherstash/stack#349: Both modify CLI command wiring and init flow (packages/cli/src/bin/stash.ts, commands/index.ts, provider next-steps).

Suggested reviewers

• coderdan
• auxesis
• tobyhede

---

🐰 A command split is quite a sight,
Init scaffolds now, then yields its might,
Impl takes the torch with plans so bright,
Plan first or execute outright!
The checkpoint whispers: continue your flight. ✨

🚥 Pre-merge checks | ✅ 3 | ❌ 2

❌ Failed checks (1 warning, 1 inconclusive)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 47.06% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.
Title check	❓ Inconclusive	The title 'Dan/init plan or implement 1' is vague and does not clearly convey the main changes; it references a branch name and lacks specificity about what was implemented.	Use a descriptive title that summarizes the key change, such as 'Split stash init scaffolding from agent handoff with stash impl command' or 'Add stash impl command and plan-first flow for setup'.

✅ Passed checks (3 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch dan/init-plan-or-implement-1

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderdan]

I think the wording is the wrong way around. The command performs implementation but will generate a plan first if one exists?