Planning System
Relevant source files
The following files were used as context for generating this wiki page:
The Planning System is a core component of SkillKit designed to facilitate structured development through the creation, validation, and execution of development plans. It enables developers and AI agents to break down complex goals into manageable, atomic tasks with clear dependencies, expected outputs, and technical metadata. Sources: packages/core/src/plan/generator.ts, packages/cli/src/commands/plan.ts:8-15
The system bridges the gap between high-level architectural design and low-level implementation by providing a standardized StructuredPlan format. This format can be generated from templates, parsed from Markdown files, or created programmatically to drive automated development workflows. Sources: packages/core/src/plan/parser.ts:8-12, packages/core/src/methodology/packs/planning/design-first/SKILL.md:120-125
Architecture and Components
The Planning System is composed of several specialized modules that handle the lifecycle of a development plan.
The diagram above illustrates the data flow between the primary components of the planning system. Sources: packages/core/src/plan/parser.ts, packages/core/src/plan/generator.ts, packages/cli/src/commands/plan.ts:85-130
Core Components Summary
| Component | Description | Primary File |
|---|---|---|
PlanParser | Converts Markdown documents into StructuredPlan objects. | parser.ts |
PlanGenerator | Programmatically builds plans, applies templates, and exports to Markdown. | generator.ts |
PlanValidator | Ensures plans are complete, lack circular dependencies, and meet quality gates. | packages/core/src/plan/tests/plan.test.ts:168-180 |
PlanExecutor | Orchestrates the execution of tasks, handling dependency ordering and failures. | packages/core/src/plan/tests/plan.test.ts:380-390 |
PlanCommand | CLI interface providing actions like parse, validate, execute, and generate. | plan.ts:13-35 |
Structured Plan Data Model
The system operates on a StructuredPlan object, which contains the project's goal, technical stack, and an array of PlanTask objects. Sources: packages/core/src/plan/generator.ts:114-124
Task Decomposition
Tasks are designed to be atomic units of work, typically estimated at 5 minutes for AI agents or 1-2 hours for human developers. Sources: packages/core/src/plan/generator.ts:108, packages/core/src/methodology/packs/planning/task-decomposition/SKILL.md:20-25
The Entity Relationship diagram shows the hierarchy from a high-level Plan down to individual execution steps. Sources: packages/core/src/plan/generator.ts:133-162, packages/core/src/plan/parser.ts:153-170
Plan Generation and Templating
The PlanGenerator allows for rapid plan creation using predefined TASK_TEMPLATES. These templates standardize common workflows such as creating components, adding API endpoints, or fixing bugs. Sources: packages/core/src/plan/generator.ts:30-85
Available Task Templates
| Template Name | Description | Common Steps |
|---|---|---|
create-component | React component creation | Test, Implement, Verify, Commit |
add-api-endpoint | API route with validation | Test, Route Handler, Logic, Verify |
fix-bug | Bug fix with regression test | Failing Test, Fix, Verify, Commit |
refactor | Behavior-preserving cleanup | Verify (Pre), Implement, Verify (Post) |
Sources: packages/core/src/plan/generator.ts:36-84
Step Type Inference
When parsing Markdown, the system automatically infers the StepType based on keywords in the description:
- test: Triggered by "test", "spec", "assert".
- verify: Triggered by "verify", "check", "confirm".
- commit: Triggered by "commit", "git".
- setup: Triggered by "setup", "initialize".
Sources: packages/core/src/plan/parser.ts:333-355
Execution Logic and Dependency Management
The PlanExecutor ensures that tasks are executed in the correct order based on their dependencies. Sources: packages/core/src/plan/tests/plan.test.ts:413-420
The sequence diagram demonstrates the workflow from CLI invocation to shell command execution. Sources: packages/cli/src/commands/plan.ts:213-245, packages/core/src/plan/tests/plan.test.ts:420-435
Execution Features
- Dry Run: Simulates execution without making actual changes using the
dryRunExecutor. Sources: packages/cli/src/commands/plan.ts:223 - Stop on Error: Optional flag to halt the entire plan if a single task fails. Sources: packages/cli/src/commands/plan.ts:68
- Dependency Awareness: Automatically skips tasks if their required parent tasks have failed. Sources: packages/core/src/plan/tests/plan.test.ts:448-460
Validation and Quality Gates
The PlanValidator checks for structural integrity and adherence to development methodologies. Sources: packages/core/src/plan/tests/plan.test.ts:182-205
Validation Checks:
- Structural: Ensures presence of plan name, goal, and at least one task.
- Integrity: Detects duplicate task IDs and non-existent task dependencies.
- Logic: Identifies circular dependencies where Task A depends on B, and B depends on A. Sources: packages/core/src/plan/tests/plan.test.ts:240-270
- Methodology: In strict mode, verifies quality requirements like the presence of test steps for every implementation task. Sources: packages/core/src/plan/tests/plan.test.ts:316-335
Integration with Development Methodologies
The Planning System is often the first step in applying specific methodologies:
- Design First: Encourages creating the Markdown plan and design document before any implementation code is written. Sources: packages/core/src/methodology/packs/planning/design-first/SKILL.md:12-18
- Task Decomposition: Used to split a high-level requirement into "Atomic Tasks" that fit the
StructuredPlanschema. Sources: packages/core/src/methodology/packs/planning/task-decomposition/SKILL.md:12-16 - Red-Green-Refactor: Supported via
generatoroptions that automatically inject "Write failing test" and "Commit changes" steps into every new task. Sources: packages/core/src/plan/generator.ts:165-175
Summary
The SkillKit Planning System provides a robust framework for transforming ambiguous development goals into executable, verifiable task lists. By combining Markdown parsing, template-based generation, and dependency-aware execution, it ensures that both human developers and AI agents follow a structured, high-quality development lifecycle. Sources: packages/core/src/plan/generator.ts:8-12, packages/cli/src/commands/plan.ts:15-30