Universal Planner

Purpose

Produce professional, structured planning documentation for any software engineering scenario. This skill adapts its workflow, depth, and output structure based on the type of work — from full SDLC documentation for a new product idea to a focused root-cause analysis and fix plan for a bug.

It replaces the need for separate planning skills by detecting the planning mode from the user’s input and activating only the relevant workflow phases.

Critical Rules

RULE 1 — PLANNING ONLY: NEVER EXECUTE

This skill produces documentation only. It MUST NOT implement, code, build, deploy, or carry out any task defined in the plan. Once all planning documents are complete, summarize what was produced and stop. Execution is a separate responsibility.

RULE 2 — CONTEXT-FIRST: RESPECT EXISTING PATTERNS

Before making any planning decision on an existing codebase, this skill MUST explore and understand the project’s established patterns, conventions, and architecture. Every proposal MUST align with what already exists. When something genuinely new is needed, the deviation must be explicitly documented and justified — never silently introduced.

This rule does not apply to NEW_PROJECT mode (there is no existing codebase to discover).

RULE 3 — ADAPTIVE MODE DETECTION

Detect the planning mode from the user’s input (see Mode Detection below). If the mode is ambiguous, ask the user. Never force a mode that doesn’t match the scenario — the wrong mode produces irrelevant documentation.

RULE 4 — PROFESSIONAL QUALITY

Output must read as if produced by a senior engineering team. Avoid vague language, placeholder text, or generic filler. Every statement must be specific to the project. Quantify non-functional requirements. Use Mermaid diagrams for architecture, data models, and flows. Use ADR format for architecture decisions.

RULE 5 — COMPLETENESS

Generate ALL documents required by the active mode. No file should be skipped or left empty. Each file must contain substantive, meaningful content specific to the project. Verify completeness before handoff.

RULE 6 — ASSUMPTION TRANSPARENCY

When information is missing or vague, infer reasonable defaults and document every assumption in the analysis. Never silently assume technical decisions. The development team must be able to validate all assumptions before implementation begins.

Planning Modes

Mode Detection

Detect the mode from the user’s input using these signals:

Mode Capabilities Matrix

Output Structure

All output goes into .synapsync/planning/{project-name}/.

.synapsync/planning/{project-name}/
├── README.md                              # Project overview and document navigation
│
├── discovery/                              # Codebase Discovery (all modes except NEW_PROJECT)
│   └── CONVENTIONS.md                     #   Existing patterns, components, conventions
│
├── requirements/                           # SDLC Phase 1 (NEW_PROJECT only)
│   ├── problem-definition.md              #   Problem statement and value proposition
│   ├── goals-and-metrics.md               #   SMART goals and KPIs
│   ├── stakeholders-and-personas.md       #   User personas and stakeholder map
│   ├── functional-requirements.md         #   MoSCoW-prioritized requirements
│   ├── non-functional-requirements.md     #   Performance, security, scalability targets
│   ├── assumptions-and-constraints.md     #   Inferred assumptions and known constraints
│   └── out-of-scope.md                    #   Excluded features and boundary definitions
│
├── design/                                 # System Design (NEW_PROJECT + ARCHITECTURE)
│   ├── system-overview.md                 #   System context and technology recommendations
│   ├── architecture-decisions.md          #   ADRs for key decisions
│   ├── high-level-architecture.md         #   Component diagram and communication patterns
│   ├── data-model.md                      #   Entity relationships and storage strategy
│   ├── core-flows.md                      #   Sequence diagrams for critical flows
│   └── non-functional-design.md           #   Performance, security, and scalability design
│
├── analysis/                               # Analysis (all modes — content adapts per mode)
│   └── ANALYSIS.md
│
├── planning/                               # Strategy (all modes)
│   └── PLANNING.md
│
├── execution/                              # Concrete task breakdown (all modes)
│   └── EXECUTION.md
│
└── sprints/                                # Sprint tracking (all modes)
    ├── PROGRESS.md                        #   Master progress dashboard
    └── SPRINT-{N}-{name}.md              #   Detailed sprint plans with checkboxes

Naming Convention

Use kebab-case for {project-name}, inferred from the user’s input:

• “expense tracker app” → expense-tracker
• “Refactor the auth module” → refactor-auth-module
• “Fix login timeout bug” → fix-login-timeout
• “CI/CD pipeline manager” → cicd-pipeline-manager

Shared Workflow Steps

These steps are shared across all modes. Mode-specific steps are documented in the next section.

Step: Codebase Discovery (all modes except NEW_PROJECT)

Before any planning begins, explore the existing project to understand its patterns, architecture, and conventions. This step is non-negotiable.

Deliverable: discovery/CONVENTIONS.md

What to explore:

1. Project Structure: Folder organization, module boundaries, monorepo vs single-app
2. UI Patterns (if applicable): Component library, design system, reusable components, styling approach, design tokens
3. Backend Patterns (if applicable): API structure, error handling, middleware, service/repository layers, validation
4. State Management: How the app manages state
5. Data Layer: ORM/database patterns, migration conventions, model definitions
6. Naming Conventions: File naming, variable naming, component naming, route naming
7. Testing Patterns: Framework, file location, mocking approach, coverage expectations
8. Shared Utilities: Existing helpers, hooks, services, and abstractions already available
9. Dependencies & Tooling: Key libraries in use, build tools, linters, formatters

Output format:

# Project Conventions: {Project Name}

## Architecture
- Pattern: [e.g., Feature-based modules, MVC, Clean Architecture]
- Key directories: [e.g., src/features/, src/shared/, src/core/]

## UI Components (if applicable)
- Design system: [e.g., Custom components in src/components/ui/]
- Key components: [e.g., Button, FormField, Modal — with paths]
- Styling: [e.g., Tailwind CSS with tokens in tailwind.config.ts]

## Backend Patterns (if applicable)
- API style: [e.g., REST with Express routers in src/routes/]
- Error handling: [e.g., Custom AppError class in src/utils/errors.ts]
- Validation: [e.g., Zod schemas in src/schemas/]

## State Management
- Approach: [e.g., Zustand stores in src/stores/]

## Naming Conventions
- Files: [e.g., kebab-case for files, PascalCase for components]
- Functions: [e.g., camelCase, verbs for actions]

## Testing
- Framework: [e.g., Vitest + Testing Library]
- Location: [e.g., __tests__/ adjacent to source]

## Shared Utilities
- [List key reusable modules with paths]

## Key Dependencies
- [List critical libraries and their purpose]

IMPORTANT: Every subsequent document MUST reference CONVENTIONS.md. If a planning decision conflicts with an established convention, it must be explicitly called out and justified.

Step: Analysis

Investigate and document what you need to build or change. The analysis content adapts per mode (see Mode-Specific Workflows below).

Deliverable: analysis/ANALYSIS.md

Common sections (all modes):

1. Executive Summary: What are we doing and why?
2. Current State Assessment: What exists today?
3. Conventions Reference (if applicable): Which existing patterns are relevant
4. Technical Analysis: Technologies, tools, architectural implications
5. Constraints & Risks: Limitations, risks with probability and mitigation
6. Success Criteria: How we measure done

Step: Planning

Define the implementation strategy based on analysis findings. All proposals must align with CONVENTIONS.md (when applicable).

Deliverable: planning/PLANNING.md

Common sections (all modes):

1. Implementation Strategy: High-level approach — how it fits within existing architecture
2. Conventions Alignment (if applicable): Patterns to reuse, justified deviations
3. Execution Phases: Major milestones with name, description, objectives, deliverables, dependencies
4. Resource Plan: Who/what is needed
5. Risk Mitigation: Handling identified risks

Step: Execution Plan

Define concrete tasks structured by phase. Each task specifies which existing patterns/components to use.

Deliverable: execution/EXECUTION.md

Common sections (all modes):

1. Execution Overview: Summary of phases
2. Phase Breakdown: For each phase — objectives, tasks, success criteria
3. Resource Allocation: Task ownership
4. Risk Monitoring: Ongoing risk assessment

Task format requirement: Every task in the execution plan must follow the standard task structure (see Sprint Structure Standards below).

Step: Sprint Plans (Optional)

Before generating sprint documents, ASK the user:

“The analysis, planning, and execution plan are complete. Do you want me to generate the sprint tracking documents (PROGRESS.md and SPRINT-*.md files) now, or would you prefer to stop here and generate them later with universal-planner-executor?”

• If the user says yes → Generate sprints/PROGRESS.md + sprints/SPRINT-{N}-{name}.md following the Sprint Structure Standards below.
• If the user says no → Skip sprint generation and proceed directly to Handoff. The user can later use universal-planner-executor to generate sprints from the execution plan.

Deliverables (when generated): sprints/PROGRESS.md + sprints/SPRINT-{N}-{name}.md

See Sprint Structure Standards for format specifications.

Step: Handoff

Summarize all produced documents and their locations. Indicate the plan is ready for execution. This skill STOPS here.

Mode-Specific Workflows

NEW_PROJECT Mode

For building a product from scratch. Produces the most comprehensive documentation.

Workflow: Analyze Idea → Requirements → System Design → Analysis → Planning → Execution → Sprints → Handoff

Additional Step: Adaptive Architecture Detection

Before writing documentation, detect the product domain and adapt:

Additional Step: Requirements Analysis (7 files in requirements/)

Generate all 7 requirement files. See Requirements Specifications below.

Additional Step: System Design (6 files in design/)

Generate all 6 design files. See Design Specifications below.

Analysis adapts to: Product feasibility, technology selection, resource assessment, market analysis.

Scale adaptation:

NEW_FEATURE Mode

For adding functionality to an existing project.

Workflow: Discovery → Analysis → Planning → Execution → Sprints → Handoff

Analysis adapts to:

• Feature architecture and component breakdown
• Integration points with existing modules
• Data flow and interface definitions
• Dependencies on existing code and shared utilities

Recommended sprint structure:

• Sprint 1: Setup — scaffolding, models, interfaces
• Sprint 2: Core — business logic, services
• Sprint 3: UI/Integration — components, views, integration
• Sprint 4: Testing — unit, e2e, polish

REFACTOR Mode

For restructuring existing code without changing behavior.

Workflow: Discovery → Analysis → Planning → Execution → Sprints → Handoff

Analysis adapts to:

• Current vs target architecture comparison
• Code duplication identification (percentage where possible)
• Architectural inconsistencies and pattern violations
• Folder responsibility definitions (what SHOULD go where vs what IS where)
• Missing abstractions or over-engineering
• Dependency issues (circular, incorrect layering)

Recommended sprint structure:

• Sprint 1: Cleanup — delete legacy code, consolidate duplicates
• Sprint 2: Migration — state/architecture migration
• Sprint 3: Extraction — logic extraction and pattern enforcement
• Sprint 4: Verification — testing and documentation

BUG_FIX Mode

For investigating and planning a fix for a specific issue.

Workflow: Discovery → Analysis → Planning → Execution → Sprints → Handoff

Analysis adapts to:

• Root Cause Analysis: Trace the bug to its source, identify all affected code paths
• Impact Assessment: Severity (Critical/High/Medium/Low), affected features/users, regression risk
• Solution Design: Proposed fix approach, alternative solutions, trade-offs
• Test Cases: Verification tests and regression prevention tests

Recommended sprint structure:

• Sprint 1: Investigation — reproduce, trace, identify root cause
• Sprint 2: Implementation — implement fix, refactor if needed
• Sprint 3: Verification — test, review, deploy

TECH_DEBT Mode

For reducing technical debt in an existing codebase.

Workflow: Discovery → Analysis → Planning → Execution → Sprints → Handoff

Analysis adapts to:

• Debt Inventory: Dead code, deprecated dependencies, outdated patterns, code duplication, missing tests, documentation gaps
• Impact vs Effort Matrix: Categorize items as Quick Wins (high impact, low effort), Critical Fixes, Strategic Improvements, Nice-to-Have
• Prioritization: Ordered by impact on maintainability, developer experience, and risk
• Modernization Path: Patterns to migrate to, dependencies to update, code to sunset

Recommended sprint structure:

• Sprint 1: Quick Wins — easy fixes with high impact
• Sprint 2: Cleanup — delete dead code, consolidate duplicates
• Sprint 3: Modernization — update patterns, upgrade dependencies
• Sprint 4: Testing — add missing test coverage

ARCHITECTURE Mode

For evolving system architecture or planning major structural changes.

Workflow: Discovery → System Design → Analysis → Planning → Execution → Sprints → Handoff

Additional Step: System Design (6 files in design/)

Same as NEW_PROJECT, but for an existing system. The design documents describe the target architecture, while CONVENTIONS.md documents the current architecture.

Analysis adapts to:

• Current vs target architecture gap analysis
• Migration path and backwards compatibility strategy
• Risk assessment for each architectural change
• Feature flag and rollback strategies
• Data migration requirements

Recommended sprint structure:

• Sprint 1: Foundation — infrastructure, base patterns, feature flags
• Sprint 2: Migration — core component migration
• Sprint 3: Integration — reconnect migrated components
• Sprint 4: Cleanup — remove legacy code, feature flags, verification

Requirements Specifications (NEW_PROJECT mode)

problem-definition.md

goals-and-metrics.md

stakeholders-and-personas.md

functional-requirements.md

Use MoSCoW prioritization: Must Have, Should Have, Could Have, Won’t Have (this release).

non-functional-requirements.md

assumptions-and-constraints.md

This file is critical — it captures everything inferred from vague input.

out-of-scope.md

Design Specifications (NEW_PROJECT + ARCHITECTURE modes)

system-overview.md

architecture-decisions.md

Document each key decision using ADR format:

### ADR-{N}: {Decision Title}

**Status:** Proposed
**Context:** {Why this decision is needed}
**Decision:** {What was decided}
**Alternatives Considered:**
- {Alternative 1}: {Why rejected}
- {Alternative 2}: {Why rejected}
**Consequences:** {Trade-offs and implications}

Include ADRs for: application architecture style, frontend framework (if applicable), database selection, authentication approach, API design style, hosting and deployment strategy.

high-level-architecture.md

data-model.md

core-flows.md

Document the 3-5 most critical flows using:

### Flow: {Flow Name}

**Actor:** {Who initiates}
**Trigger:** {What starts this flow}
**Preconditions:** {What must be true}

**Steps:**
1. {Step description}
2. {Step description}

**Postconditions:** {What is true after completion}
**Error Scenarios:** {What can go wrong and how to handle it}

Include a Mermaid sequence diagram for each flow.

non-functional-design.md

Sprint Structure Standards

All sprint documents across all modes MUST follow these standards.

PROGRESS.md Format

# Progress: {Project Name}

## Executive Summary
{One paragraph describing the project and current status}

## Sprint Overview

| Sprint | Name | Status | Objectives |
|--------|------|--------|------------|
| 1 | {Name} | NOT_STARTED / IN_PROGRESS / COMPLETED | {One-line objective} |
| 2 | {Name} | NOT_STARTED / IN_PROGRESS / COMPLETED | {One-line objective} |

## Global Metrics

| Metric | Target | Current | Status |
|--------|--------|---------|--------|
| {Metric 1} | {Goal} | {Current} | NOT_STARTED / IN_PROGRESS / COMPLETED |

## Blockers & Issues

| Issue | Impact | Resolution | Status |
|-------|--------|------------|--------|
| {Issue} | {What it blocks} | {Mitigation} | OPEN / RESOLVED |

## Document Index
- [CONVENTIONS.md](../discovery/CONVENTIONS.md) (if applicable)
- [ANALYSIS.md](../analysis/ANALYSIS.md)
- [PLANNING.md](../planning/PLANNING.md)
- [EXECUTION.md](../execution/EXECUTION.md)
- Sprint plans: [Sprint 1](./SPRINT-1-{name}.md), [Sprint 2](./SPRINT-2-{name}.md), ...

SPRINT-{N}-{name}.md Format

# Sprint {N}: {Sprint Name}

**Duration:** {X-Y days}
**Objective:** {Clear one-line objective}
**Status:** NOT_STARTED | IN_PROGRESS | COMPLETED
**Dependencies:** {Prerequisites from other sprints}

---

## Phase {N}.1: {Phase Name}

**Objective:** {What this phase achieves}

### Prerequisites
- [ ] {Required items before starting}

### Tasks

#### Task {N}.1.1: {Task Description}
**File(s):** `{paths}`
**Convention:** {Which existing pattern/component to use, if applicable}

**Changes:**
```{language}
// BEFORE
{existing code}

// AFTER
{proposed code}

Steps:

• {N}.1.1.1 — {Specific action}
• {N}.1.1.2 — {Specific action}

Verification:

{command to verify task completion}
# Expected: {what should happen}

Phase {N}.2: Final Verification

Code Verifications

• {Verification 1}: {command} — Expected: {result}
• {Verification 2}: {command} — Expected: {result}

Functional Verifications

• Build succeeds
• Tests pass
• Manual smoke test passes

Definition of Done

Sprint {N} is completed when:

• {Criterion 1}
• {Criterion 2}
• {Criterion N}

Risks

Rollback Strategy

{How to revert changes from this sprint if something goes wrong}

Notes

{Space for implementation notes during execution}

### Task Granularity

| Level | Name | Scope | Example |
|-------|------|-------|---------|
| L1 | Sprint | Major milestone (3-7 days) | "Sprint 1: Foundation Setup" |
| L2 | Phase | Logical grouping (0.5-2 days) | "Phase 1.1: Database Schema" |
| L3 | Task | Discrete work item (1-4 hours) | "Task 1.1.1: Create users table" |
| L4 | Subtask | Single action (5-30 min) | "1.1.1.1: Define column types" |

Every task must:
- Have a checkboxed action
- Include file paths when applicable
- Show before/after code snippets for changes
- Include a verification command
- Reference which existing patterns/components to use (when applicable)

---

## Critical Patterns

### Pattern 1: Planning Only — Never Execute

This skill MUST NOT begin implementing, coding, or deploying any planned task. Its output is strictly documentation. Once all documents are created, the skill's work is done.

**Bad**: Creating the plan and then starting to implement Phase 1 tasks
**Good**: Creating all documents, summarizing what was produced, then stopping

### Pattern 2: Respect Existing Patterns — Never Reinvent

Every planning decision on an existing codebase must align with established conventions. Before proposing any component, pattern, or approach, check what already exists.

**Bad**: "Create a new `<button>` element with custom CSS"
**Good**: "Use existing `Button` component from `src/components/ui/Button.tsx` with variant='primary'"

**Bad**: "Set up Redux for state management"
**Good**: "Use existing Zustand store pattern in `src/stores/` as the project already uses Zustand"

### Pattern 3: Justify Every Deviation

When something genuinely new IS needed, the plan must document:
1. **What exists today** and why it doesn't solve the problem
2. **What is proposed** as the new approach
3. **Why the deviation is justified** — concrete technical reasoning
4. **How it aligns** with the project's broader architecture

This goes in the **Conventions Alignment** section of PLANNING.md.

### Pattern 4: Adaptive Depth

Match documentation depth to project scale. A personal CLI tool doesn't need 4 user personas and 7 ADRs. A multi-tenant SaaS platform does. Infer scale from the user's input and adjust.

### Pattern 5: Specific Over Generic

Quantify everything. Measurable statements are testable; vague ones are not.

**Bad**: "The system must be scalable"
**Good**: "The system must handle 1,000 concurrent WebSocket connections with <100ms latency"

**Bad**: "Implement the feature"
**Good**: "Create API endpoint POST /api/v1/registrations with validation for email, password, and name"

### Pattern 6: Diagrams Over Prose

Use Mermaid diagrams for architecture, data models, and flows. Visual representations are faster to understand and less ambiguous than paragraph descriptions.

### Pattern 7: ADR Discipline

Document every significant architectural decision with context, alternatives considered, and consequences. Future team members need to understand the reasoning behind decisions.

### Pattern 8: Cross-Reference Consistency

Reference related documents using relative links. Never duplicate content across files. Every document should be navigable from the README.

### Pattern 9: Phase Dependencies

Always declare phase and sprint dependencies explicitly:

```markdown
### Phase 2: API Integration
**Dependencies**: Phase 1 (Foundation Setup) must be complete
**Blocks**: Phase 3 (Frontend Implementation)

Pattern 10: Task-to-Phase Mapping

Every task in a sprint must map back to an execution phase. No orphan tasks.

Configuration

Project Scale

Sprint Duration

• Weekly: Standard for most projects (recommended)
• Bi-weekly: For slower-moving or larger projects
• Align sprints with execution phases — each sprint should focus on completing 1-2 phases

Integration with Other Skills

Troubleshooting

“Analysis is never-ending”

Set a hard scope boundary. Document unknowns as risks, not blockers. Move to planning with incomplete analysis if needed — the plan can account for investigation tasks.

“Plan proposes patterns that conflict with existing codebase”

Codebase Discovery was skipped or incomplete. Go back and create/update CONVENTIONS.md. Review every proposal against documented conventions.

“Not sure which mode to use”

Ask the user. If the work involves both a new feature and refactoring, use NEW_FEATURE mode and include refactoring as a phase within the execution plan.

“Input is too vague”

Make broader assumptions and document them prominently in ANALYSIS.md. For NEW_PROJECT mode, document in assumptions-and-constraints.md. Still generate all required files.

“Sprint todos get out of sync with execution phases”

Create sprint plans AFTER finalizing the execution plan. Map each sprint task to a specific execution phase. Review alignment before handoff.

“Tasks don’t fit into a single phase”

Cross-cutting concerns (testing, documentation, monitoring) should be tracked as support tasks within the sprint where they’re most relevant, or as a dedicated verification phase at the end of each sprint.

Limitations

1. Planning only: Produces documentation, never executes
2. Requires input: Cannot plan without a description of the work (however vague)
3. Assumptions must be validated: Inferred decisions need team review before implementation
4. Technology recommendations are suggestions: The development team makes final choices
5. Manual tracking: Sprint progress must be updated manually during execution
6. No automated validation: Cannot verify that plans match codebase reality — relies on thorough discovery

Version History