Planning Workflow
Kalami includes a planning skill that enforces a plan-before-coding workflow for non-trivial changes.
When planning triggers
The plan skill activates when:
- You say "plan", "think first", "let's build", or "implement"
- A task involves 3 or more files
- You explicitly ask Claude to make a plan
The planning flow
1. Analyze scope
Claude analyzes what needs to change — which files, which modules, what the boundaries are.
2. Write the plan
A plan is saved to .kalami/plans/{date}-{topic}.md with this structure:
# Plan: Add user authentication
Created: 2026-03-19
Status: approved
## Steps
- [ ] Step 1: Create auth middleware in src/middleware/auth.ts
- [ ] Step 2: Add login endpoint in src/routes/login.ts
- [ ] Step 3: Add tests for auth middleware
- [ ] Step 4: Update route configuration
## Scope boundary
Only touches: src/middleware/, src/routes/, tests/
Does NOT touch: database schema, existing routes
## Verification
- npm test passes
- Login endpoint returns JWT
3. Get your approval
Claude presents the plan and waits. No code is written until you approve. This is the critical gate — you review the scope, the approach, and the verification method.
4. Execute step by step
After approval:
- Claude works through one step at a time
- Commits after each step
- Marks steps as complete in the plan file
- If a step fails verification, stops and reports
5. Complete
When all steps are done, the plan is marked complete.
Commands during planning
| What you say | What happens |
|---|---|
| "go" or "approved" | Start executing the plan |
| "step 2 not needed" | Skip a step |
| "do step 3 first" | Reorder execution |
| "abandon" | Cancel the plan entirely |
| "show plan" | Display current plan |
| "continue plan" | Resume an interrupted plan |
Why plan?
Without planning, Claude tends to:
- Edit too many files at once
- Miss edge cases
- Break things in one module while fixing another
- Not commit intermediary progress
The planning skill prevents all of these by forcing scope clarity before coding starts.