Objective

Create hierarchical project plans with fresh context for autonomous execution.

Quick Start

Use the create workflow to:

1. Determine plan type (Lite vs Standard)
2. Gather project context (vision, constraints, stakeholders)
3. Create plan files (BRIEF.md, ROADMAP.md, phase PLAN.md files)
4. Validate quality (self-contained, atomic tasks, checkpoints)

This workflow provides step-by-step guidance with templates for creating executable plans that can be run with fresh context in autonomous sessions.

Use the edit workflow to:

• Refine existing roadmaps or phase plans
• Update project context or constraints
• Modify task lists or success criteria
• Adjust phase dependencies or structure

Use the audit workflow to:

• Check plan feasibility and completeness
• Validate context management
• Review checkpoint appropriateness
• Ensure executable prompts are self-contained

Plan Types

Lite Plan

Single PLAN.md with 2-3 tasks for smaller projects.

Use when: Simple feature, quick task, focused work

Standard Plan

Hierarchical structure with BRIEF.md + ROADMAP.md + phased PLAN.md files

Use when: Complex project, multiple phases, team coordination

Directory Structure

.cattoolkit/planning/
└── {project-slug}/              # Scoped project folder (kebab-case)
    ├── BRIEF.md                 # Project vision, constraints, scope
    ├── ROADMAP.md               # Architecture, phases, progress tracking
    ├── ADR.md                   # Architecture Decision Records (auto-created)
    ├── ISSUES.md                # Deferred enhancements (auto-created)
    └── phases/
        ├── {number}-{phase-name}/
        │   ├── PLAN.md          # Executable tasks for this phase
        │   ├── SUMMARY.md       # Phase summary
        │   └── ...
        └── ...

Templates Index

Workflow templates in templates/:

• templates/brief.md - BRIEF.md template
• templates/roadmap.md - ROADMAP.md template
• templates/phase-prompt.md - Phase PLAN.md template
• templates/summary.md - Phase summary template
• templates/research-prompt.md - Research phase template
• templates/milestone.md - Milestone completion template
• templates/issues.md - ISSUES.md template
• templates/continue-here.md - Handoff/continue template

Plan templates in assets/templates/:

• assets/templates/lite-plan.md - Single PLAN.md for small projects
• assets/templates/adr-entry.md - Architecture Decision Record entry
• assets/templates/issue-entry.md - Deferred enhancement entry

WHY: Templates ensure plans follow consistent YAML frontmatter and structure patterns with proper state tracking.

Metadata-based State Tracking

Progress tracking uses non-destructive YAML frontmatter instead of filesystem renaming.

Phase Status (YAML Frontmatter)

Each phase's PLAN.md includes frontmatter with status:

---
phase: 01-foundation
type: execute
status: in_progress  # ← Tracks current state
---

Status values:

• in_progress - Currently executing
• completed - Phase complete (all plans finished)

ROADMAP Progress Table

The central ROADMAP.md serves as the single source of truth for project progress:

## Progress

| Phase | Plans Complete | Status | Completed |
|-------|----------------|--------|-----------|
| 1. Foundation | 3/3 | Complete | 2025-01-15 |
| 2. Authentication | 0/2 | Not started | - |
| 3. Core Features | 0/1 | Not started | - |

Benefits:

• Stable paths - No done_ prefixes break relative paths
• Clean git history - Only meaningful changes tracked
• Non-destructive - Original project structure preserved
• Single source of truth - ROADMAP.md shows complete project state

Key Methodology

Plans Are Executable Prompts

• NOT documentation for humans
• Prompts that autonomous sessions RUN to do work
• Must be self-contained (fresh context each time)

Context Management (Critical)

Autonomous sessions start with ZERO context - every plan MUST:

• Explicitly list required files with paths
• Include @ references: @src/database/schema.ts
• Provide the "why" not just the "what"
• Be fully self-contained

Scope Control

• 2-3 tasks per plan maximum
• ~50% context budget for references
• One phase ≈ one autonomous execution session

Checkpoints

Include **[CHECKPOINT]** for:

• Architecture decisions
• Major milestones
• Risk points

ADR (Architecture Decision Records)

When Rule 4 (Architectural Change) is approved during execution:

Create ADR entry in ADR.md:

## ADR-001: [Decision Title]

**Date:** YYYY-MM-DD
**Phase:** [Phase Name]
**Trigger:** Rule 4 - Architectural Change during [task name]

### Decision
[What was decided - concise statement]

### Context
**Current task:** [task name]
**Discovery:** [what prompted this]
**Proposed change:** [architectural modification]

### Rationale
[Why this decision was made]

### Alternatives Considered
[Other approaches evaluated]

### Consequences
**Positive:**
- [Expected benefits]

**Negative:**
- [Trade-offs or drawbacks]

**Impact:**
- [What this affects]

ADR Creation Protocol:

• Auto-increment: Count existing ADR entries and add 1
• Append-only (never delete or modify old entries)
• File location: .cattoolkit/planning/{project-slug}/ADR.md

Deferred Enhancements (ISSUES.md)

Log non-critical improvements for future phases:

## Open Enhancements

### ISS-001: [Brief description]
- **Discovered:** Phase [X] Plan [Y] Task [Z]
- **Type:** [Performance / Refactoring / UX / Testing]
- **Description:** [What could be improved]
- **Impact:** Low (works correctly, this would enhance)
- **Effort:** [Quick / Medium / Substantial]

Plan Numbering

Auto-increment from existing phases:

find .cattoolkit/planning/{project-slug}/phases -type d | wc -l

File Structure

BRIEF.md

• Project vision and goals
• Constraints and scope boundaries
• Success criteria
• Key stakeholders

ROADMAP.md

• Architecture overview
• Phase breakdown
• Dependencies between phases
• Progress tracking

PLAN.md (Phased)

# Execution Context
Files to read before starting

# Tasks
Checkbox list of actions

# Checkpoints
Items with **[CHECKPOINT]** markers

# Success Criteria
Definition of done

Reference Files

• references/plan-format.md - Detailed PLAN.md structure
• references/context-management.md - Context window management
• references/scope-estimation.md - How to size plans appropriately
• references/checkpoints.md - Checkpoint types and usage
• references/cli-automation.md - What can be automated via CLI
• references/hierarchy-rules.md - Plan hierarchy and structure rules
• references/authentication-gates.md - Handling authentication during execution
• references/user-gates.md - User interaction gates
• references/milestone-management.md - Milestone tracking
• references/domain-expertise.md - Domain expertise considerations
• references/research-pitfalls.md - Common research mistakes
• references/git-integration.md - Git workflow integration