Workflow Planning Skill - Quick Reference

This skill enables structured, systematic development workflows. The assistant should apply these patterns when users need to break down complex projects, create implementation plans, or execute multi-step development tasks with clear checkpoints.

Inspired by: Obra Superpowers patterns for structured agent workflows.

Quick Reference

Command Purpose When to Use

/brainstorm

Generate ideas and approaches Starting new features, exploring solutions

/write-plan

Create detailed implementation plan Before coding, after requirements clarification

/execute-plan

Implement plan step-by-step When plan is approved, ready to code

/checkpoint

Review progress, adjust plan Mid-implementation, after major milestones

/summarize

Capture learnings, document decisions End of session, before context reset

When to Use This Skill

The assistant should invoke this skill when a user requests:

• Break down a complex feature into steps

• Create an implementation plan

• Brainstorm approaches to a problem

• Execute a multi-step development task

• Track progress on a project

• Review and adjust mid-implementation

The Three-Phase Workflow

Phase 1: Brainstorm

Purpose: Explore the problem space and generate potential solutions.

/brainstorm [topic or problem]

OUTPUT:

1. Problem Understanding

   • What are we solving?
   • Who is affected?
   • What are the constraints?

2. Potential Approaches (3-5)

   • Approach A: [description, pros, cons]
   • Approach B: [description, pros, cons]
   • Approach C: [description, pros, cons]

3. Questions to Resolve

   • [List of unknowns needing clarification]

4. Recommended Approach

   • [Selected approach with justification]

Phase 2: Write Plan

Purpose: Create a detailed, actionable implementation plan.

/write-plan [feature or task]

OUTPUT:

Implementation Plan: [Feature Name]

Goal

[Single sentence describing the outcome]

Success Criteria

• Criterion 1
• Criterion 2
• Criterion 3

Steps (with estimates)

Step 1: [Name] (~Xh)

• What: [specific actions]
• Files: [files to modify/create]
• Dependencies: [what must exist first]
• Verification: [how to confirm done]

Risks & Mitigations

Open Questions

• [Questions to resolve before starting]

Dependency Graph for Parallel Execution

When a plan will be executed with multiple subagents, each task must declare its dependencies explicitly. This enables the orchestrator to determine which tasks can run in parallel.

Task Dependency Graph

Rules for dependency graphs:

• Every task declares depends_on: [] with explicit task IDs (empty array = no blockers).

• Tasks with no dependencies can start immediately (in parallel).

• No circular dependencies — the graph must be a DAG (directed acyclic graph).

• Each task should specify its file ownership to prevent parallel conflicts.

Parallel Execution Strategies

Swarm Waves (Accuracy-First) — Launch one subagent per unblocked task, in dependency-respecting waves. Wait for each wave to complete before launching the next. Best for production code and complex interdependencies.

Super Swarms (Speed-First) — Launch as many subagents as possible at once, regardless of dependencies. Best for prototypes and greenfield scaffolding. Expect merge conflicts.

See references/planning-templates.md for the full swarm-ready plan template.

Phase 3: Execute Plan

Purpose: Implement the plan systematically with checkpoints.

/execute-plan [plan reference]

EXECUTION PATTERN:

1. Load the plan
2. For each step: a. Announce: "Starting Step X: [name]" b. Execute actions c. Verify completion d. Report: "Step X complete. [brief summary]"
3. After completion: a. Run all verification criteria b. Report final status

Worktree-First Delivery

For production coding sessions, wrap /execute-plan with a delivery guardrail:

• Create one isolated worktree per feature.

• Execute only the approved plan scope in that worktree.

• Run repo-defined quality gate(s) before PR (example: npm run test:analytics-gate ).

• Open one focused PR per feature branch.

./scripts/git/feature-workflow.sh start <feature-slug> cd .worktrees/<feature-slug>

implement plan steps

../../scripts/git/feature-workflow.sh gate ../../scripts/git/feature-workflow.sh pr --title "feat: <summary>"

Agent Session Management

Key rules from production experience (Feb 2026):

• One feature per session. Context exhaustion causes rework. A sprawling session (38 messages, 3+ continuations) produced multiple errors; a focused session (5 messages) shipped clean.

• Write a plan before touching 3+ files. Sessions with pre-written numbered plans had near-zero rework.

• Verify SDK types before executing plan steps. Documentation may describe APIs that no longer match actual TypeScript definitions.

See references/session-patterns.md for the full production evidence table and checkpoint protocol for long sessions.

Command Preflight Protocol

Before broad edits, tests, or reviews — run a 60-second preflight:

• pwd / git branch --show-current / ls -la

• test -e <path> to verify target paths before heavy commands

• npx <tool> --help to validate flags before first use

• Quote paths containing [] , * , ? , or spaces

See references/operational-checklists.md for the full git/branch safety preflight, E2E/server preflight, shell safety gate, and SDK type verification.

Structured Patterns

Hypothesis-Driven Development

PATTERN: Test assumptions before committing

Before implementing:

1. State hypothesis: "If we [action], then [expected outcome]"
2. Define experiment: "To test this, we will [minimal test]"
3. Execute experiment
4. Evaluate: "Hypothesis confirmed/rejected because [evidence]"
5. Proceed or pivot based on result

Incremental Implementation

Build in verifiable increments: smallest testable unit → implement and verify → expand scope → verify at each expansion → integrate and verify whole.

See references/planning-templates.md for an authentication feature example with 5 increments.

Progress Tracking

PATTERN: Maintain visible progress

[X] Step 1: Create database schema [X] Step 2: Implement API endpoints [IN PROGRESS] Step 3: Add frontend form [ ] Step 4: Write tests

Current: Step 3 of 4 (75% complete) Blockers: None Next: Complete form validation

Work in Progress (WIP) Limits

Limit concurrent work: individual (2-3 tasks), team stories (team size + 1), in-progress column (3-5 items), code review (2-3 PRs). If limits are never reached, lower them. If constantly blocked, investigate the bottleneck.

See references/planning-templates.md for the full WIP limits reference and setting guidelines.

Milestone Checkpointing and Scope Budgeting

For multi-step execution, constrain scope and checkpoint progress at milestone boundaries.

• Define explicit session scope at start: 1-2 deliverables only.

• If a new request expands beyond scope, create a follow-up milestone.

Milestone Checkpoint Contract

At each milestone, record:

• completed outputs (files/features/tests)

• verification results (commands + pass/fail)

• unresolved blockers

• next bounded action

Stop Conditions

Stop and rescope when any occur:

• repeated nonzero failures without new evidence

• context churn (re-reading same files repeatedly)

• more than 3 independent domains active in one session

See references/session-scope-budgeting.md for full scope budgeting model and enforcement rules.

Session Management

Starting a Session

Session initialized.

• Project: [name]
• Goal: [today's objective]
• Context loaded: [files, previous decisions]
• Plan status: [steps remaining]

Ready to continue from: [last checkpoint]

Ending a Session

/summarize

OUTPUT:

Session Summary

Completed

• [List of completed items]

In Progress

• [Current state of incomplete work]

Decisions Made

• [Key decisions with rationale]

Next Session

• [First task for next time]

Context to Preserve

[Critical information for continuity]

Decision Framework

When faced with choices:

1. State the decision clearly
2. List options (2-4)
3. For each option: Pros / Cons / Effort / Risk
4. Recommendation with justification
5. Reversibility assessment

Example:

Recommendation: Sessions for MVP, plan JWT migration for scale.

Integration with Other Skills

With Testing Skill

/write-plan with TDD:

Step 1: Write failing test Step 2: Implement minimal code Step 3: Verify test passes Step 4: Refactor Step 5: Add edge case tests

With Architecture Skill

/brainstorm system design:

1. Requirements clarification
2. Component identification
3. Interface definition
4. Data flow mapping
5. Implementation plan

Definition of Ready / Done (DoR/DoD)

assets/template-dor-dod.md - Checklists for work readiness and completion.

assets/template-work-item-ticket.md - Ticket template with DoR/DoD and testable acceptance criteria.

Key sections: Definition of Ready / Done checklists, Acceptance Criteria templates (Gherkin), Estimation Guidelines (story point scale 1-21+), Planning Levels (Roadmap → Sprint → Task), Cross-Functional RACI.

Do / Avoid

GOOD: Do

• Check DoR before pulling work into sprint

• Verify DoD before marking complete

• Size stories using reference scale

• Slice large stories (>8 points)

• Document acceptance criteria upfront

• Include risk buffer in estimates

BAD: Avoid

• Starting work without clear acceptance criteria

• Declaring "done" without testing

• Working on stories too big to finish in sprint

• Skipping code review "to save time"

• Deploying without staging verification

Anti-Patterns

Anti-Pattern Problem Fix

No DoR Unclear requirements discovered mid-sprint Gate sprint entry with DoR

Soft DoD "Done" means different things Written DoD checklist

Mega-stories Never finish, hard to track Slice to <8 points

Missing AC Built wrong thing Gherkin format AC

No ownership Work falls through cracks RACI for every epic

Hope-based estimates Always late Use reference scale + buffer

AI/Automation

Note: AI can assist but should not replace human judgment on priorities and acceptance.

• Generate acceptance criteria - Draft from story description (needs review)

• Suggest story slicing - Based on complexity analysis

• Dependency mapping - Identify blocking relationships

• AI-augmented planning - Use LLMs to draft plans, but validate assumptions

AI-generated criteria and estimates require human calibration before committing to them.

Navigation

Resources

• references/planning-templates.md - Plan templates, incremental implementation, WIP limits

• references/session-patterns.md - Multi-session management, production lessons (Feb 2026)

• references/session-scope-budgeting.md - Scope budgeting rules and stop/rescope criteria

• references/operational-checklists.md - Preflight protocols, verification, failure ledger, subagent limits

• references/flow-metrics.md - DORA metrics, WIP limits, flow optimization

• references/agile-ceremony-patterns.md - Sprint ceremonies, retrospectives, facilitation patterns

• references/technical-debt-management.md - Debt classification, prioritization, remediation workflows

• references/remote-async-workflows.md - Async-first patterns, distributed team coordination

• assets/template-dor-dod.md - DoR/DoD checklists, estimation, cross-functional coordination

• assets/template-work-item-ticket.md - Work item ticket template

• assets/template-milestone-checkpoint.md - Milestone checkpoint record

• data/sources.json - Workflow methodology references

Related Skills

• ../software-architecture-design/SKILL.md - System design planning

• ../docs-ai-prd/SKILL.md - Requirements to plan conversion

• ../qa-testing-strategy/SKILL.md - TDD workflow integration

• ../qa-debugging/SKILL.md - Systematic debugging plans