Draft an encryption plan

stash plan is the second step in the setup lifecycle. It hands off to a coding agent, which reads your project and produces a reviewable encryption plan at .cipherstash/plan.md. No code is changed. The plan is a checkpoint you review before running stash impl.

npx stash plan

Prerequisites

stash plan reads .cipherstash/context.json, which is written by stash init. If that file is missing, the command errors with a message pointing you to run stash init first.

What plan does

1. Reads .cipherstash/context.json to understand your project (integration, schemas, environment, installed agents).
2. Checks for an existing .cipherstash/plan.md. If one is found, warns you that the agent will be asked to revise it. Delete the file first to start fresh.
3. Asks which agent should write the plan. All four handoff targets are available: Claude Code, Codex, AGENTS.md (for Cursor/Windsurf/Cline), and the CipherStash Agent (@cipherstash/wizard). Each target produces a plan-mode artifact: Claude Code / Codex / AGENTS.md read the mode-aware setup-prompt.md; the wizard receives --mode plan and the gateway returns its planning prompt.
4. Hands off to the selected agent with a planning prompt. The agent reads your codebase and produces .cipherstash/plan.md.
5. After the agent finishes, asks (default-yes) whether to continue to stash impl now.

The plan.md artifact

The agent writes .cipherstash/plan.md as a human-readable Markdown file. At the top, it embeds a machine-readable summary block:

<!-- cipherstash:plan-summary
{
  "columns": [
    {"table": "users", "column": "email", "path": "new"},
    {"table": "users", "column": "phone", "path": "migrate"}
  ]
}
-->

stash impl parses this block to render a confirmation panel before launching implementation.

Column paths

Each entry in columns has a path field with one of two values:

If stash impl finds a plan without the summary block (for example, a plan written before this feature was added), it falls back to a soft prompt asking you to open the file in your editor before proceeding.

Agent options

stash plan offers all four handoff targets:

The command defaults to Claude Code if detected, then Codex, otherwise AGENTS.md. The CipherStash Agent is never selected by default. Pick it explicitly if you want the in-house wizard. Each target produces a .cipherstash/plan.md with the same machine-readable summary block at the top, so the choice of target doesn't change what stash impl parses later.

Chain prompt

After the agent completes the plan, stash plan shows:

Plan drafted at `.cipherstash/plan.md`. Continue to `stash impl` now? (Y/n)

Answering yes launches stash impl immediately. Answering no (or running non-interactively) prints the next step and exits:

Plan drafted at `.cipherstash/plan.md`. Review it, then run `stash impl` to implement.

Non-TTY environments (CI, pipes) skip the prompt and always print the hint.

Reviewing the plan

Before running stash impl, open .cipherstash/plan.md and verify:

• The tables and columns listed match your intent.
• The path values are correct. A migrate path triggers the full four-deploy lifecycle. Confirm this is what you want for any column with existing data.
• Any columns with path: migrate have a backfill strategy accounted for.

Next steps