Plan & Act

Plan and Act are two agent modes in Kodik, described on the Modes page. They structure work: first understand and plan, then implement.

Plan Mode

In Plan mode Kodik’s built-in workspace tools are read-only. They will not edit files, run mutating commands, or create files — even if you ask. The built-in catalog contains read and analysis tools such as read_file, glob, rg, codebase_search, read_lints, and web_fetch, plus ask_questions.

Enabled MCP tools are also available in Plan. They are user-installed external capabilities and may have side effects defined by their server, so use Settings → Harness or MCP Settings to disable any tool you do not want offered in this mode.

The output of Plan mode is a structured plan artifact created via the generate_plan tool. If a Mermaid architecture diagram would materially help, the agent includes it.

Workflow inside Plan mode

1. Kodik reads and analyzes the relevant code.
2. If the request is materially ambiguous, it calls ask_questions exactly once.
3. It breaks the work into small actionable steps ordered by implementation sequence.
4. It calls out risks, assumptions, and open questions.
5. It calls generate_plan exactly once to save the final plan artifact.

Plan mode does not allow ordinary chat text: questions only via ask_questions, the final plan only via generate_plan. No intermediate status messages.

Plan panel

After generate_plan is called, Kodik automatically opens a dedicated plan-review tab. Chat keeps a short confirmation while the tab renders the Markdown, task list, and (if present) Mermaid diagram; it is not an unsaved .md file in the editor.

Planning in Orchestrator

When a route needs planning, Orchestrator delegates it to the built-in Planner profile. Planner inspects the available evidence and publishes one structured draft to the session’s Team Workspace with its sub-agent-only create_plan capability. The Orchestrator reviews that draft as a recommendation instead of authoring or rewriting it.

The Orchestrator accepts a sound routine plan internally and continues delegation without interrupting you. It opens the plan review only when your authority is needed: the route has unresolved user decisions, expands scope, requires destructive or externally visible action, carries material cost, security, or compatibility risk, or you explicitly asked to review it. Approval resumes delegation in Orchestrator mode; requesting changes rejects that draft and sends the feedback to Planner, whose new draft supersedes the earlier plan while retaining it for audit and recovery.

Act Mode (Code / Act)

Once the plan is ready, switch to Act mode. All agent tools are available — file editing, terminal commands, file creation. Context from the planning session is preserved.

Typical workflow

1. Start the task in Plan mode.
2. Describe the goal; Kodik explores the codebase.
3. Answer any clarifying questions if prompted.
4. Review the generated plan in the plan panel.
5. Switch to Act mode — Kodik executes the plan.
6. If unexpected complexity arises, switch back to Plan to refine the strategy.

Best Practices

Planning phase

• Provide context up front: requirements, constraints, key files.
• Use @Mentions to point Kodik at important files explicitly.
• Let Kodik finish reading code before it forms the plan.

Implementation phase

• Follow the plan; switch back to Plan mode if the approach needs adjustment.
• Use Checkpoints to snapshot state before large changes.
• Track progress via the Task list.

When to use each mode

Plan mode works best when:

• the approach to a task is not obvious
• you need to understand a complex bug before fixing it
• you are making architectural decisions that affect multiple parts of the codebase

Act mode is ideal when:

• a plan is already in place
• you are making routine changes with a clear approach
• you are running tests or minor adjustments