Planning Skill

Create consistent, dual-purpose implementation plans that are readable by humans and executable by AI agents.

Quick Start

When creating a new plan, copy the template from assets/PLAN_TEMPLATE.md and fill in the sections. The template includes all required structure with placeholder text to replace.

Plan Structure

Every plan follows this structure:

# {NNN}: {Title}

**Status**: Draft | In Progress | Complete | Blocked  
**Created**: YYYY-MM-DD  
**Author**: {author or "AI-assisted planning session"}

---

## Overview
{2-3 sentences: What does this plan accomplish? Why does it matter?}

## Goals
{Numbered list with bold goal names and brief explanations}

## Architecture
{High-level design: diagrams, data flow, component relationships}

## Dependencies
{External packages, internal modules, other plans this depends on}

## References
{Links to docs, issues, related files, external resources}

---

## Implementation Phases

### Phase N: {Phase Title}

**Status**: Not Started | In Progress | Complete  
**Depends on**: None | Phase N

#### Context
{Background info: relevant files, current state, patterns to follow, code snippets}

#### Tasks

##### N.1 {Task Title}
**Status**: ☐ Not Started | ◐ In Progress | ✓ Complete  
**Requires**: None | Task N.M  
**Acceptance Criteria**: {What "done" looks like - specific, testable}

**Context**:
- File: `src/path/to/file.ts`
- Pattern: {Existing pattern to follow or reference}

**Sub-tasks**:
- [ ] {Specific technical step with file/function names}
- [ ] {Implementation detail}
- [ ] {Verification step - test, lint, build}

Section Guidelines

Header

• NNN: Zero-padded 3-digit number (e.g., 001, 042)
• Status values: Draft (initial), In Progress (active work), Complete (all phases done), Blocked (waiting on external dependency)

Overview

• 2-3 sentences maximum
• Answer: What? Why? Impact?
• No implementation details here

Goals

Format:

1. **Goal Name** - Why this matters, what success looks like
2. **Another Goal** - Brief explanation

Architecture

• Include ASCII diagrams for data/control flow
• Document key design decisions
• Show component relationships
• Keep diagrams under 30 lines

Dependencies

Split into categories when helpful:

**External Packages**:
- `package-name@^version` - Purpose

**Internal Modules**:
- `src/module/` - What it provides

**Related Plans**:
- [Plan 001](001-plan-name.md) - Why it's related

References

• External documentation links
• GitHub issues/PRs
• Related workspace files (use relative paths)

Phase Guidelines

Phase Structure

• Phases are sequential – later phases assume earlier ones complete
• Keep phases focused: 3-7 tasks per phase
• Name phases by outcome: “Core Infrastructure”, “API Integration”, “CLI Commands”

Phase Context Block

Include information agents need to execute tasks:

• Relevant file paths in the codebase
• Existing patterns to follow (with code snippets if short)
• Current state of the system
• Design constraints or decisions

Example:

#### Context
The workflow executor is in `src/workflows/executor.ts`. Node execution 
happens in the `executeNode()` function starting at line 45. Follow the 
existing pattern of returning `NodeResult` objects.

Current signature:
\`\`\`typescript
async function executeNode(node: WorkflowNode, ctx: Context): Promise<NodeResult>
\`\`\`

Task Guidelines

Task Structure

Every task includes:

1. Status marker: ☐ (not started), ◐ (in progress), ✓ (complete)
2. Requires: Explicit dependencies on other tasks
3. Acceptance Criteria: Specific, testable definition of done
4. Context: Files, patterns, relevant code
5. Sub-tasks: Checkable technical steps

Writing Effective Tasks

• Start task titles with action verbs: Create, Implement, Add, Update, Refactor
• Make acceptance criteria measurable: “Tests pass”, “Exports function X”, “Handles error case Y”
• Include specific file paths in context
• Reference existing patterns when applicable

Sub-task Guidelines

Each sub-task should be:

• Atomic: One specific action
• Technical: Include file/function names
• Verifiable: Clear when done

Example sub-tasks:

- [ ] Create `src/telemetry/provider.ts` with `initTracer()` function
- [ ] Export `getTracer()` from `src/telemetry/index.ts`
- [ ] Add unit tests in `tests/telemetry/provider.test.ts`
- [ ] Verify: `npm test telemetry` passes

Verification Requirements

Verification is mandatory at both task and phase levels to ensure quality and catch AI hallucinations early.

Task-Level Verification

Every task must end with a verification sub-task that proves the work is complete:

**Sub-tasks**:
- [ ] Create `src/plugins/loader.ts`
- [ ] Implement `loadPlugin()` function
- [ ] Add unit tests in `tests/plugins/loader.test.ts`
- [ ] **Verify**: `npm test loader` passes

Verification types (use at least one per task):

• npm test {pattern} – Unit tests pass
• npm build – Code compiles without errors
• npm lint – No lint errors introduced
• Manual check: {specific behavior to observe}

Phase-Level Verification

Every phase must end with a verification task that integrates and tests all phase work:

##### 1.X Phase 1 Verification
**Status**: ☐ Not Started  
**Requires**: All previous phase tasks  
**Acceptance Criteria**: All Phase 1 features work together

**Sub-tasks**:
- [ ] Run full test suite: `npm test`
- [ ] Run build: `npm build`
- [ ] Run lint: `npm lint`
- [ ] Manual integration test: {describe end-to-end behavior}
- [ ] Document any issues found in task notes

Why Verification Matters

1. Catches hallucinations – AI must prove work is complete with passing tests
2. Incremental quality – Issues found early, not at the end
3. Clear done state – No ambiguity about task completion
4. TDD alignment – Tests are written as part of implementation, not afterthought

Dependency Format

**Requires**: 1.2, 1.3

Use task numbers from the same plan. For cross-plan dependencies:

**Requires**: Plan 001 Phase 2 complete

Context Block Patterns

For File Modifications

**Context**:
- File: `src/commands/index.ts`
- Add command to `commands` array at line 23
- Follow pattern of existing commands (see `init.ts`)

For New Features

**Context**:
- Create new directory: `src/feature/`
- Pattern: Follow structure of `src/workflows/`
- Exports: Re-export from `src/feature/index.ts`

For Integrations

**Context**:
- API docs: https://example.com/api
- Auth: Use token from `ctx.config.apiKey`
- Error handling: Wrap in `try/catch`, return `Result<T>` type

Status Tracking

Plan-Level Status

Update in header as work progresses:

• Draft → initial creation
• In Progress → at least one phase started
• Complete → all phases complete
• Blocked → external blocker documented in Overview

Phase-Level Status

**Status**: Not Started | In Progress | Complete

Task-Level Status

Use status markers for quick scanning:

• ☐ – Not started
• ◐ – In progress
• ✓ – Complete

Sub-task Checkboxes

- [ ] Not done
- [x] Complete

Example Plan Skeleton

# 015: Add Plugin System

**Status**: Draft  
**Created**: 2026-01-27  
**Author**: AI-assisted planning session

---

## Overview

Implement a plugin system for cosmos-cli that allows users to extend 
functionality with custom commands and workflows without modifying core code.

## Goals

1. **Extensibility** - Users can add commands without forking
2. **Discoverability** - Plugins auto-register and appear in help
3. **Isolation** - Plugin errors don't crash the CLI

## Architecture

\`\`\`
┌─────────────────┐     ┌─────────────────┐
│   Core CLI      │────▶│  Plugin Loader  │
└─────────────────┘     └────────┬────────┘
                                 │
         ┌───────────────────────┼───────────────────────┐
         ▼                       ▼                       ▼
┌─────────────────┐     ┌─────────────────┐     ┌─────────────────┐
│  ~/.cosmos/     │     │  node_modules/  │     │  ./plugins/     │
│  plugins/       │     │  cosmos-plugin-*│     │  (local)        │
└─────────────────┘     └─────────────────┘     └─────────────────┘
\`\`\`

## Dependencies

**External Packages**:
- None required (use dynamic import)

**Internal Modules**:
- `src/commands/` - Command registration pattern
- `src/core/project.ts` - Project root discovery

## References

- [Commander.js Plugin Pattern](https://github.com/tj/commander.js)
- [Related: Plan 006](006-project-root-discovery.md)

---

## Implementation Phases

### Phase 1: Plugin Loader

**Status**: Not Started  
**Depends on**: None

#### Context
Commands are registered in `src/commands/index.ts`. Each command exports 
a function that receives the Commander program instance. Plugins should 
follow this same pattern.

#### Tasks

##### 1.1 Create Plugin Discovery Module
**Status**: ☐ Not Started  
**Requires**: None  
**Acceptance Criteria**: Finds plugins in ~/.cosmos/plugins/ and node_modules/

**Context**:
- File: Create `src/plugins/discovery.ts`
- Pattern: Similar to `src/workflows/discovery.ts`

**Sub-tasks**:
- [ ] Create `src/plugins/discovery.ts`
- [ ] Implement `discoverPlugins()` function
- [ ] Search ~/.cosmos/plugins/ for plugin.json files
- [ ] Search node_modules/ for cosmos-plugin-* packages
- [ ] Return array of `PluginManifest` objects
- [ ] Add unit tests in `tests/plugins/discovery.test.ts`

**TDD**:
- [ ] `tests/plugin/discovery.test.ts` created first with failing tests
- [ ] `tests/plugin/discovery.test.ts` passes after implemenation integrated

##### 1.2 Create Plugin Loader
**Status**: ☐ Not Started  
**Requires**: 1.1  
**Acceptance Criteria**: Loads and validates plugin modules safely

**Context**:
- File: Create `src/plugins/loader.ts`
- Use dynamic import() for loading
- Wrap in try/catch for isolation

**Sub-tasks**:
- [ ] Create `src/plugins/loader.ts`
- [ ] Implement `loadPlugin(manifest: PluginManifest)` function
- [ ] Validate plugin exports required interface
- [ ] Handle load errors gracefully (log warning, continue)
- [ ] Add unit tests with mock plugins
- [ ] **Verify**: `npm test loader` passes

**TDD**:
- [ ] `tests/plugin/loader.test.ts` created first with failing tests
- [ ] `tests/plugin/loader.test.ts` passes after mock plugins integrated

##### 1.3 Phase 1 Verification
**Status**: ☐ Not Started  
**Requires**: 1.1, 1.2  
**Acceptance Criteria**: Plugin discovery and loading work end-to-end

**Sub-tasks**:
- [ ] Run full test suite: `npm test`
- [ ] Run build: `npm build`
- [ ] Manual test: Create mock plugin, verify it loads and registers

Naming Convention

Plan files: {NNN}-{kebab-case-title}.md

Examples:

• 001-opentelemetry-observability.md
• 015-add-plugin-system.md
• 042-migrate-to-esm.md

Place all plans in the plans/ directory at the project root.