picassodocs
docs/04-plan-mode.md

04 - Plan Mode

Read-only software architect mode. /plan maps a repository, diagnoses the request, and produces a reviewable strategy document with rationale, impact boundaries, risks, and next steps. It does not edit files, install packages, run migrations, start mutating services, change git state, or execute destructive commands. The user reviews, edits, and approves the strategy before any separate execution path can touch the workspace.

The visual treatment is locked in Scene 03 of design/Picasso TUI.html. Plan mode renders the plan document in serif italic for the title, file rows tagged with op-colored chips (edit amber, create add-green, delete del-red), risks in a separate band, and an approval bar at the bottom with kbd-pill key hints. The plan-mode badge in the status line uses --lilac.

/plan is intentionally different from /goal. Plan mode is analytical and non-destructive. Goal mode is mutation-capable only after a completion contract is approved, and then it runs the autonomous PLAN -> ACT -> OBSERVE -> ASSESS loop described in 16-goals.md.

When plan mode is active

Three triggers:

In /goal mode, plan generation runs at the top of every major iteration. See 16-goals.md.

Plan document format

Plan mode renders a structured Markdown document with required sections. The runtime validates structure before presenting it to the user. The canonical plan is stored in the session/plan store; exporting it to plan.md is an explicit user action and is not part of read-only analysis.

# Plan: <one-line summary>

## System Persona

Operating as a Read-Only Software Architect. No file writes, dependency
installs, migrations, service mutations, git mutations, or destructive commands
were performed.

## Goal

<2-4 sentences on what the user asked for and what the agent will deliver.>

## Repository Architecture

<Detected entry points, package/config files, frameworks, services, folder
structure, and module boundaries.>

## Functional Capabilities

<What the application does programmatically, grouped by business or runtime
domain.>

## Data Flow

<How data moves from UI/CLI/API boundaries through domain modules, providers,
storage, telemetry, memory, or other relevant systems.>

## Target State

<The technical architecture required to satisfy the user's request.>

## Impact Isolation

<Precise files/modules/services expected to change, plus areas intentionally
left untouched.>

## Proposed Changes

### File: path/to/file.ts

- **Operation:** edit | create | delete
- **Change:** <one-line description>
- **Rationale:** <why this change>

(repeat for each file)

## New dependencies

<List any new packages, libraries, or runtime tools. Empty section if none.>

## Risks

<3-5 bullet points on what could go wrong, including breaking changes,
performance impact, and security considerations.>

## Actionable Next Steps

<Ordered checklist for future execution. Include tests to run and properties to
verify, but do not run mutation-capable commands in plan mode.>

## Risks And Assumptions

<Clarifying questions for the user. Each question has a default the agent
will use if the user does not respond.>

## Optional Goal Handoff Contract

<A draft `/goal` completion contract if the user wants autonomous execution
after approving this plan. This is a draft only; it does not start a goal.>

Approval flow

After plan generation, the TUI presents the plan with three actions:

Approval is logged with timestamp and user identity in the session log.

Auto-accept thresholds

For repetitive or low-risk plans, the user can configure auto-accept:

# .picasso/config.yaml
plan_mode:
  auto_accept:
    after_n_safe_operations: 10 # auto-accept once 10 safe ops have passed
    safe_operation_classes:
      - read-only-tool-use
      - in-workspace-file-edit
    require_approval_for:
      - destructive-tool-use
      - dependency-add
      - schema-migration

Auto-accept is logged at the same fidelity as manual approval. The first auto-accepted plan in a session displays a one-line banner.

Plan editing protocol

When the user edits the plan, the agent treats edits as binding instructions. Specifically:

Edits are diffed against the original plan; the agent receives the diff explicitly in its next prompt.

Plan-to-goal handoff

An approved plan can be converted into a draft goal contract. The draft includes the target objective, completion criteria, budget ceilings, allowed tools, scope boundaries, and verification commands. The draft contract must still be reviewed and explicitly approved before /goal starts. Plan mode never starts the autonomous loop by itself.

An approved plan can also be used by a normal execution command. That command runs outside plan mode, with the normal permission model and destructive confirmation rules.

Multi-stage plans

For large work, the plan itself may contain stages. Each stage has its own changes and verification. The agent presents the staged plan once; on approval, it executes stages sequentially with a pause between each for the user to inspect (configurable to "run all" without inter-stage pauses).

## Stages

### Stage 1: Add database column

- File: migrations/...
- File: src/models/user.ts
- Verification: migration runs cleanly on dev DB

### Stage 2: Migrate read paths

- File: src/handlers/user.ts
- Verification: existing tests pass

Companion dashboard

Every plan generated is mirrored to the web dashboard. Users can review and edit plans in the dashboard's collaborative plan editor (markdown editor with section validation). Multiple team members can comment on a plan before approval. See 06-sessions.md for the persistence model.

Plan-mode tool restrictions

In plan mode, only read-safe tools are available to the agent: read_file, view_directory, grep, glob, find_symbol, query_memory, web_search, web_fetch, and mcp_call when the MCP server is marked read-only. Write tools fail with a structured error if invoked during plan generation. This guarantees plan generation itself does not modify state.

Plan mode may inspect configuration and source files, parse dependency manifests, build import graphs, and read existing logs. It must not run commands that write files, install dependencies, start services with side effects, run database migrations, mutate git state, invoke package-manager scripts that are not proven read-only, or execute destructive shell commands. Diagnostics that would write coverage, snapshots, caches, lockfiles, generated artifacts, databases, or logs must be proposed in the plan instead of executed.

query_memory is allowed only as a read-only retrieval tool. write_memory, memory deletion, cache mutation, sync upload, and projection generation are disabled while /plan is active.

Plan-mode subagents

Plan generation can spawn subagents (e.g., a codebase_investigator to scope the change). Those subagents inherit the read-only constraint.

Acceptance criteria

Dependencies

Open questions