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
| Risk | Likelihood | Impact | Mitigation |
|------|-----------|--------|------------|
| Risk 1 | Medium | High | Plan B if... |

### 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

| Task ID | Name | depends_on | Files | Agent Scope |
|---------|------|------------|-------|-------------|
| T1 | Setup database schema | [] | db/schema.sql | db-engineer |
| T2 | Create API routes | [T1] | src/routes/*.ts | backend-dev |
| T3 | Build auth middleware | [T1] | src/middleware/auth.ts | backend-dev |
| T4 | Frontend components | [] | src/components/*.tsx | frontend-dev |
| T5 | Integration tests | [T2, T3, T4] | tests/integration/*.test.ts | qa-agent |

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:
| Option | Pros | Cons | Effort | Risk |
|--------|------|------|--------|------|
| JWT | Stateless, scalable | Token management | 2 days | Low |
| Sessions | Simple, secure | Server state | 1 day | Low |
| OAuth only | No passwords | External dependency | 3 days | Medium |

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

dev-workflow-planning