Planning System Overview

The NikCLI Planning System is an intelligent, AI-powered execution planning framework that breaks down complex development tasks into structured, executable plans with comprehensive risk assessment, dependency management, and interactive approval workflows.

Core Concepts

What is the Planning System?

The Planning System transforms high-level user goals into detailed, executable plans that:

Analyze project context and requirements
Generate structured execution steps with dependencies
Assess risks and provide mitigation strategies
Execute plans with real-time progress tracking
Validate results and handle failures gracefully

Key Components

System Architecture

Planning Manager

The central orchestrator that coordinates plan generation, validation, approval, and execution:

import { PlanningManager } from '@nikcli/planning'

const planner = new PlanningManager(process.cwd(), {
  maxStepsPerPlan: 50,
  requireApprovalForRisk: 'high',
  enableRollback: true,
  logLevel: 'info',
  timeoutPerStep: 60000
})

// Generate and execute a plan
const result = await planner.planAndExecute(
  'Add authentication to the API',
  '/path/to/project'
)

Plan Generator

Analyzes user requests and generates comprehensive execution plans:

const context: PlannerContext = {
  userRequest: 'Implement user authentication',
  projectPath: process.cwd(),
  availableTools: [...],
  projectAnalysis: {
    fileCount: 150,
    languages: ['typescript', 'javascript'],
    frameworks: ['express', 'react'],
    hasTests: true,
    hasDocumentation: true
  }
}

const plan = await planGenerator.generatePlan(context)

Plan Executor

Executes validated plans with monitoring, approval, and error handling:

const executor = new PlanExecutor(toolRegistry, {
  requireApprovalForRisk: 'high',
  enableRollback: true,
  timeoutPerStep: 60000,
  autoApproveReadonly: true
})

const result = await executor.executePlan(plan)

Planning Lifecycle

1. Context Analysis

The system begins by analyzing the project context:

// Automatic project analysis
const projectAnalysis = {
  fileCount: 250,
  languages: ['typescript', 'javascript', 'css'],
  frameworks: ['next.js', 'tailwind'],
  hasTests: true,
  hasDocumentation: true
}

// Workspace context integration
const workspaceContext = await workspaceRAG.getContextForTask(userGoal)

2. Plan Generation

AI-powered plan generation creates structured execution steps:

const plan: ExecutionPlan = {
  id: 'plan-abc123',
  title: 'Implement User Authentication',
  description: 'Add JWT-based authentication with refresh tokens',
  steps: [
    {
      id: 'step-1',
      type: 'validation',
      title: 'Validate Request',
      description: 'Check prerequisites and dependencies',
      riskLevel: 'low',
      reversible: true,
      estimatedDuration: 2000
    },
    {
      id: 'step-2',
      type: 'tool',
      title: 'Install Dependencies',
      description: 'Install jsonwebtoken and bcrypt packages',
      toolName: 'manage-packages',
      toolArgs: {
        action: 'install',
        packages: ['jsonwebtoken', 'bcrypt']
      },
      riskLevel: 'low',
      reversible: true,
      dependencies: ['step-1']
    },
    // ... more steps
  ],
  status: 'pending',
  estimatedTotalDuration: 300000,
  riskAssessment: {
    overallRisk: 'medium',
    destructiveOperations: 0,
    fileModifications: 5,
    externalCalls: 2
  }
}

3. Risk Assessment

Comprehensive risk analysis with mitigation strategies:

const riskAssessment: RiskAssessment = {
  overallRisk: 'medium',
  destructiveOperations: 0,
  fileModifications: 5,
  externalCalls: 2
}

// Risk scoring algorithm
const riskScore = calculatePlanRiskScore(plan) // 0-100

4. Plan Validation

Pre-execution validation ensures plan integrity:

const validation: PlanValidationResult = {
  isValid: true,
  errors: [],
  warnings: [
    'Plan contains high-risk operations',
    'Plan includes 2 potentially destructive operations'
  ],
  suggestions: [
    'Consider breaking this plan into smaller chunks'
  ]
}

5. User Approval

Interactive approval for risky operations:

const approval: PlanApprovalResponse = {
  approved: true,
  modifiedSteps: ['step-5'], // Steps to skip
  userComments: 'Skip database migration for now',
  timestamp: new Date()
}

6. Execution

Step-by-step execution with real-time tracking:

const result: PlanExecutionResult = {
  planId: 'plan-abc123',
  status: 'completed',
  startTime: new Date(),
  endTime: new Date(),
  stepResults: [
    {
      stepId: 'step-1',
      status: 'success',
      output: { validated: true },
      duration: 1500,
      timestamp: new Date()
    }
  ],
  summary: {
    totalSteps: 8,
    successfulSteps: 7,
    failedSteps: 1,
    skippedSteps: 0
  }
}

Plan Types

Standard Plans

Generated from user requests with full analysis:

const plan = await planner.generatePlanOnly(
  'Add API rate limiting',
  '/path/to/project'
)

Enhanced Plans (TodoPlan)

Rich todo-based plans with detailed metadata:

import { EnhancedPlanningSystem } from '@nikcli/planning'

const enhancedPlanner = new EnhancedPlanningSystem()

const plan = await enhancedPlanner.generatePlan(
  'Implement GraphQL API',
  {
    maxTodos: 20,
    includeContext: true,
    showDetails: true,
    saveTodoFile: true
  }
)

Autonomous Plans

AI-driven plans with automatic execution:

import { AutonomousPlanner } from '@nikcli/planning'

const autonomousPlanner = new AutonomousPlanner(workspacePath)

for await (const event of autonomousPlanner.createAndExecutePlan(
  'Optimize application performance'
)) {
  console.log(`${event.type}: ${event.content}`)
}

Execution Models

Sequential Execution

Steps execute in dependency order:

const orderedSteps = executor.resolveDependencyOrder(plan.steps)

for (const step of orderedSteps) {
  await executor.executeStep(step, plan)
}

Parallel Execution

Independent steps can run concurrently:

const independentSteps = steps.filter(step =>
  !step.dependencies || step.dependencies.length === 0
)

await Promise.all(
  independentSteps.map(step => executor.executeStep(step, plan))
)

Agent-Delegated Execution

Complex steps delegated to specialized agents:

{
  type: 'tool',
  metadata: {
    agent: 'react-agent',
    task: 'Create authentication UI components'
  }
}

Risk Management

Risk Levels

Four risk levels determine approval requirements:

Level	Description	Auto-Approve	Example Operations
Low	Read-only, non-destructive	✅ Yes	File reading, analysis
Medium	File modifications	⚠️ Optional	Creating files, updates
High	Potentially destructive	❌ No	Deletions, replacements
Critical	System-level changes	❌ No	Package installations, migrations

Risk Assessment Algorithm

function calculatePlanRiskScore(plan: ExecutionPlan): number {
  let score = 0

  // Base score from overall risk
  if (plan.riskAssessment.overallRisk === 'high') score += 50
  else if (plan.riskAssessment.overallRisk === 'medium') score += 25

  // Add points for destructive operations
  score += Math.min(plan.riskAssessment.destructiveOperations * 5, 20)

  // Add points for file modifications
  score += Math.min(plan.riskAssessment.fileModifications * 3, 15)

  // Add points for external calls
  score += Math.min(plan.riskAssessment.externalCalls * 2, 10)

  return Math.min(score, 100)
}

Mitigation Strategies

const riskAssessment = {
  overallRisk: 'high',
  riskFactors: [
    'Contains 3 destructive operations',
    'Large number of file modifications (15)'
  ],
  mitigationStrategies: [
    'Review all destructive commands before execution',
    'Ensure backups are available before execution',
    'Execute in dependency order with validation'
  ]
}

Tool Integration

Tool Capabilities

The planning system integrates with the tool registry:

const toolCapabilities: PlanningToolCapability[] = [
  {
    name: 'write-file-tool',
    description: 'Write content to file',
    riskLevel: 'medium',
    reversible: true,
    estimatedDuration: 4000,
    requiredArgs: ['filePath', 'content'],
    optionalArgs: ['options']
  }
]

Secure Tool Routing

High-risk operations route through secure wrappers:

// Secure command execution
await secureTools.executeCommand('npm install express', {
  requireApproval: true,
  auditLog: true
})

// Secure file operations
await secureTools.applyConfigPatch(filePath, operations, {
  createBackup: true,
  validateSchema: true
})

Context Awareness

Workspace Context

Integration with RAG system for intelligent planning:

const workspaceContext = workspaceRAG.getContextForTask(userGoal)

// Returns:
{
  projectInfo: {
    name: 'my-app',
    type: 'web-application',
    stack: ['typescript', 'react', 'express']
  },
  relevantFiles: [
    { path: 'src/auth/index.ts', summary: 'Auth module' }
  ],
  dependencies: [...],
  recentChanges: [...]
}

Project Analysis

Automatic detection of project characteristics:

const analysis = {
  fileCount: 250,
  languages: ['typescript', 'javascript'],
  frameworks: ['next.js', 'prisma'],
  hasTests: true,
  hasDocumentation: true,
  testFramework: 'vitest',
  buildTool: 'vite'
}

Progress Tracking

Real-time Updates

Track execution progress in real-time:

planner.on('stepStart', ({ stepId, stepIndex }) => {
  console.log(`Starting step ${stepIndex + 1}`)
})

planner.on('stepComplete', ({ stepId, stepIndex }) => {
  console.log(`Completed step ${stepIndex + 1}`)
})

planner.on('planExecutionComplete', ({ planId }) => {
  console.log('Plan execution completed')
})

Progress Metrics

const progress = {
  completedSteps: 5,
  totalSteps: 10,
  percentage: 50,
  currentStep: 'Installing dependencies',
  estimatedTimeRemaining: 120000
}

Error Handling

Failure Strategies

async function handleStepFailure(
  step: ExecutionStep,
  result: StepExecutionResult
): Promise<'abort' | 'skip' | 'retry' | 'continue'> {
  if (step.riskLevel === 'low') {
    // Non-critical: continue with warning
    return 'continue'
  }

  if (step.reversible && config.enableRollback) {
    // Offer rollback for reversible steps
    return await promptUser(['abort', 'skip', 'retry'])
  }

  // Critical failure: abort
  return 'abort'
}

Rollback Support

const step: ExecutionStep = {
  reversible: true,
  metadata: {
    rollbackPlan: [
      'Delete created files',
      'Restore original configuration'
    ]
  }
}

Performance Considerations

Optimization Strategies

Parallel Execution: Run independent steps concurrently
Caching: Cache tool results for repeated operations
Lazy Loading: Load context only when needed
Streaming: Stream large outputs incrementally

Timeouts

{
  timeoutPerStep: 60000, // 1 minute per step
  maxStepsPerPlan: 50,   // Prevent overly complex plans
}

Best Practices

Plan Design

✅ DO:

Break complex tasks into 5-15 manageable steps
Set realistic duration estimates
Use clear, actionable step titles
Define proper dependencies
Include validation steps

❌ DON’T:

Create monolithic plans with 50+ steps
Skip risk assessment
Ignore error handling
Omit user feedback for risky operations

Execution

✅ DO:

Review high-risk operations before approval
Monitor execution progress
Handle failures gracefully
Log execution results

❌ DON’T:

Auto-approve destructive operations
Ignore validation warnings
Skip dependency checks
Bypass approval system

Next Steps

Plan Generation

Learn how to generate intelligent execution plans

Execution Flow

Understand the plan execution lifecycle

Plan Templates

Explore pre-built plan templates

Interactive Planning

Master interactive plan approval and modification

Tool System - Understand tool integration
Agent System - Learn about agent delegation
Context & RAG - Explore context awareness
Configuration - Configure planning behavior

Getting Started

CLI Reference

User Guide

Agent System

Planning System

Context & RAG

Architecture

Troubleshooting

​Planning System Overview

​Core Concepts

​What is the Planning System?

​Key Components

​System Architecture

​Planning Manager

​Plan Generator

​Plan Executor

​Planning Lifecycle

​1. Context Analysis

​2. Plan Generation

​3. Risk Assessment

​4. Plan Validation

​5. User Approval

​6. Execution

​Plan Types

​Standard Plans

​Enhanced Plans (TodoPlan)

​Autonomous Plans

​Execution Models

​Sequential Execution

​Parallel Execution

​Agent-Delegated Execution

​Risk Management

​Risk Levels

​Risk Assessment Algorithm

​Mitigation Strategies

​Tool Integration

​Tool Capabilities

​Secure Tool Routing

​Context Awareness

​Workspace Context

​Project Analysis

​Progress Tracking

​Real-time Updates

​Progress Metrics

​Error Handling

​Failure Strategies

​Rollback Support

​Performance Considerations

​Optimization Strategies

​Timeouts

​Best Practices

​Plan Design

​Execution

​Next Steps