Planning | Gokin

Gokin includes a full-featured planning system for complex multi-step tasks with support for parallel steps, conditions, dependencies, and adaptive replanning.

Plan Lifecycle#

Draft → AwaitingApproval → Approved → Executing → Completed
                         ↘ Cancelled ↙              ↓
                                                   Failed

Executing ⟷ Paused (pause / resume)
Failed → Approved (after replan)

State	Description
Draft	Initial state, steps being designed
AwaitingApproval	Ready for user review
Approved	User accepted, execution not started
Executing	Steps are running
Paused	Temporarily stopped, can be resumed
Completed	All steps finished successfully
Failed	A step encountered a fatal error
Cancelled	User cancelled

Step Statuses#

Status	Icon	Description
Pending	○	Awaiting execution
InProgress	◐	Running
Completed	●	Finished successfully
Failed	✗	Execution error
Skipped	⊘	Condition not met or dependency failed
Paused	⏸	Temporarily stopped

Step Structure#

Step {
    ID          int           // 1-indexed
    Title       string        // What to do
    Description string        // Detailed description
    Status      Status        // Current state

    // Execution control
    Parallel    bool          // Can run in parallel
    DependsOn   []int         // Step IDs to wait for
    MaxRetries  int           // Retry attempts (0 = no retries)
    Timeout     time.Duration // Step timeout
    Condition   string        // "step_N_failed" or "step_N_succeeded"

    // Results
    Output      string
    Error       string
    TokensUsed  int
    StartTime   time.Time
    EndTime     time.Time
}

Parallel Steps#

Steps with Parallel: true run concurrently via sync.WaitGroup:

Step 1: Explore structure (Parallel)  ──┐
Step 2: Analyze imports (Parallel)    ──┤── All 3 launch simultaneously
Step 3: Find tests (Parallel)         ──┘
Step 4: Implement changes (DependsOn: [1, 2, 3])  ── Waits for all 3

NextReadySteps() determines available steps:

If the next step is NOT parallel → returns one step
If parallel → returns all consecutive Parallel steps

Conditional Steps#

Steps with Condition execute only when the condition matches:

Step 3: Run tests
Step 4: Fix tests (Condition: "step_3_failed")       ← only if tests failed
Step 5: Deploy (Condition: "step_3_succeeded")        ← only if tests passed

ShouldSkip(plan) evaluates the condition before execution.

Step Dependencies#

DependsOn specifies step IDs that must complete before starting:

steps:
  - id: 1
    title: "Explore structure"
  - id: 2
    title: "Write tests"
    depends_on: [1]
  - id: 3
    title: "Implement feature"
    depends_on: [1]
  - id: 4
    title: "Run tests"
    depends_on: [2, 3]

Timeouts#

Step timeout priority:

Step.Timeout — individual step timeout
PlanConfig.DefaultStepTimeout — global timeout from configuration
5 minutes — default value

Error Classification#

Category	Description	Action
Transient	Timeout, network, rate limit	Retry
Logic	Invalid arguments, validation	Retry with changes
Fatal	Permission denied, not found	Skip or replan
Unknown	Unrecognized error	Default handling

Classification Patterns#

Transient: context.DeadlineExceeded, “rate limit”, “timeout”, “connection refused”, “503”, “502”, “429”

Fatal: “permission denied”, “not found”, “no such file”, “access denied”, “forbidden”

Logic: “validation error”, “invalid argument”, “syntax error”, “parse error”

Adaptive Replanning#

On a fatal step error, replanning is triggered automatically:

LLM generates replacement steps
All completed/failed/skipped steps are preserved
Pending steps are replaced with new ones
New IDs are assigned sequentially
DependsOn references are validated
Plan.Version is incremented
Plan status returns to Executing

Maximum 3 replans.

Approval Flow#

Plan built → state AwaitingApproval
User reviews → can approve or reject
Approved → state Approved
Execution → state Executing
Each step:
- StepHandler callback called before/after
- Tracked via RunLedger (side effects, tools, files)
- Retry on ErrorTransient / ErrorLogic
- Replan on ErrorFatal

Run Ledger#

Tracking execution side effects:

Tools used
Files affected
Resources created/deleted
Time and tokens per step

Progress Tracking#

ProgressUpdate {
    PlanID        string
    CurrentStepID int
    CurrentTitle  string
    TotalSteps    int
    Completed     int
    Progress      float64  // 0.0 – 1.0
    Status        string
}

Plan Report Format#

Plan v2: "Refactor authentication" [Completed]
  ✓ Step 1: Explore structure (12.3s, 1.2K tokens)
  ✓ Step 2: Write interfaces (8.1s, 2.1K tokens)
  ✗ Step 3: Implement handlers (failed: timeout)
  ✓ Step 3': Implement handlers (replan) (15.2s, 3.4K tokens)
  ⊘ Step 4: Old cleanup (skipped: replaced by replan)
  ✓ Step 5: Run tests (5.1s, 0.8K tokens)

Configuration#

plan:
  enabled: true
  require_approval: true
  auto_detect: true               # Auto-detect complex tasks
  clear_context: true             # Clear context before planning
  delegate_steps: true            # Delegate steps to agents
  abort_on_step_failure: false    # Don't abort on step failure
  planning_timeout: 60s
  algorithm: beam                 # beam, mcts, astar

Planning Slash Commands#

Command	Description
`/plan`	Toggle planning mode
`/resume-plan list`	List unfinished plans
`/resume-plan <id>`	Resume a specific plan
`/tree-stats`	Tree planner statistics