| name | software-planning |
| description | Planning complex software tasks via a three-document model (IMPLEMENTATION_PLAN.md, WIP.md, LEARNINGS.md) in small, known-good increments. Triggers: starting significant development, breaking down complex features, architecture planning, multi-session projects, feature breakdown, work planning, task tracking, WIP management, incremental development. Language modules available for Python, TypeScript.
|
| allowed-tools | ["Read","Write","Edit","Glob","Grep","Bash"] |
| compatibility | Claude Code |
Software Planning in Small Increments
All work must be done in small, known-good increments. Each increment leaves the codebase in a working state.
Create and maintain planning documents (IMPLEMENTATION_PLAN.md, WIP.md, LEARNINGS.md) following the agent intermediate documents placement convention.
Satellite files (loaded on-demand):
- references/document-templates.md -- WIP.md and LEARNINGS.md templates, parallel mode, end-of-feature workflow
- references/decomposition-guide.md -- feature breakdown examples, spike steps, anti-patterns, Claude Code agent usage
- references/agent-pipeline-details.md -- boundary discipline, parallel execution, intra-stage parallelism, pipeline engagement tables
- references/coordination-details.md -- pipeline worktree lifecycle, BDD/TDD execution, batched improvement procedure, context-engineer/doc-engineer parallel details, fragment files
- references/intra-step-review.md -- intra-step pair-review: trigger predicate (auto-signals + planner override), reviewer input/output contract, iteration bound, escalation, composition table vs self-review and full verifier,
review: field schema
- references/tier-templates.md -- parametric tier-prompt scaffolds (Standard/Full/Lightweight) with seven angle-bracket placeholders; payload links to the coordination rule's delegation checklists
- references/adr-authoring-protocols.md -- ADR file creation, index regeneration, supersession protocol
- phases/refactoring.md -- refactoring phase integration
- contexts/python.md -- Python-specific quality gates and step templates
- assets/ARCHITECTURE_TEMPLATE.md -- 8-section template for
.ai-state/DESIGN.md architect-facing design target
- references/architecture-documentation.md -- dual-audience architecture documentation methodology: lifecycle, section ownership, validation models for both architect and developer documents
- references/behavioral-contract.md -- four-behavior contract deep dive: definitions, per-agent application, objection templates, DRY relationship
- references/design-synthesis.md -- activation-gated pre-implementation synthesis: lens catalog, activation formula, convergence signals; composed from existing skills (security / performance / simplicity / testability)
- references/project-principles.md -- per-project standards artifact (
.ai-state/principles.yaml): schema, authoring boundary + decision test, advisory/blocking guidance, absent-behavior contract, migration path to project_profile.yaml
For the up-front design discipline behind boundary and interface choices —
SOLID as balanced-coupling heuristics, the strength/distance/volatility model, and
the agent-as-consumer lens — compose with the software-design-principles skill.
Planning is where boundaries are chosen before code exists; that skill is the
canon, this one decomposes the chosen design into safe steps.
Three-Document Model
For significant work, maintain three documents:
| Document | Purpose | Lifecycle |
|---|
| IMPLEMENTATION_PLAN.md | What we're doing | Created at start, changes need approval |
| WIP.md | Where we are now | Updated constantly, always accurate |
| LEARNINGS.md | What we discovered | Temporary, merged at end then deleted |
Document Relationships
IMPLEMENTATION_PLAN.md (static) WIP.md (living) LEARNINGS.md (temporary)
┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐
│ Goal │ │ Current step │ │ Gotchas │
│ Acceptance │ ──► │ Status │ ──► │ Patterns │
│ Steps 1-N │ │ Blockers │ │ Decisions │
│ (approved) │ │ Next action │ │ Edge cases │
└─────────────────┘ └─────────────────┘ └─────────────────┘
END OF FEATURE: Merge LEARNINGS into CLAUDE.md / ADRs, then DELETE all three docs
Language Context
When planning work in a specific language or tech stack, load the relevant context overlay alongside this skill. Contexts augment the planning workflow with language-specific quality gates, step templates, and testing patterns — without duplicating content from language skills.
Available contexts:
How contexts integrate:
- IMPLEMENTATION_PLAN.md: Add a
Tech Stack field linking to the relevant context and skills
- Step templates: Use language-specific templates for common step types (new module, add dependency, etc.)
- Quality gates: Run language-specific format → lint → type check → test before each commit
- Testing field: Choose testing approach based on language-specific patterns
If no context exists for your language, use the generic planning workflow and reference language-specific documentation directly.
Phase Delegations
Some plan steps delegate to a specialized skill for their methodology. A phase is a group of consecutive steps that follow a specialized skill's workflow while remaining tracked by the plan.
Available phases:
How phases integrate:
- Detection: During plan creation, look for signals that a phase is needed (each phase doc lists its signals)
- Step marking: Tag delegated steps with
[Phase: <Name>] in the step title and a Skill field pointing to the delegated skill
- Entry/exit criteria: Each phase defines what must be true before starting and after completing
- Scoped: Phase steps serve the plan's goal — they are not open-ended improvement
Delegated step template:
### Step N: [Phase: <Name>] One sentence description
**Skill**: [<Skill Name>](link/to/SKILL.md)
**Implementation**: What structural change will we make?
**Testing**: How do we verify behavior is preserved / new behavior works?
**Done when**: Concrete exit condition
Contexts and phases compose: A plan can use a language context (Python quality gates) and a phase (refactoring methodology) simultaneously. The context provides the quality checks; the phase provides the approach.
Spec-Driven Development Integration
For medium and large features, the spec-driven-development skill provides behavioral specification format, requirement ID conventions, and traceability threading patterns. The two skills compose:
- Software-planning provides the three-document model, step decomposition, and execution workflow
- Spec-driven-development provides the behavioral specification format and requirement traceability
- The implementation-planner loads both when working on medium/large features
- Trivial and small tasks use software-planning alone — no spec overhead
The SDD skill is a phase delegation peer, not a dependency: planning works without it, and SDD methodology can be loaded independently for reference.
What Makes a "Known-Good Increment"
Each step MUST:
- Leave the system in a working state
- Be independently testable
- Have clear done criteria
- Fit in a single commit
- Be describable in one sentence
If you can't describe a step in one sentence, break it down further.
Step Size Heuristics
Too big if:
- Takes more than one session
- Requires multiple commits to complete
- Has multiple "and"s in description
- Involves more than 3-5 files
- Tests would be too complex to write
Right size if:
- One clear objective
- One logical change
- Can explain to someone in 30 seconds
- Obvious when done
- Single responsibility
Testing in Plan Steps (BDD/TDD)
Behavioral tests first. Tests are designed from the acceptance criteria in the systems plan — they encode what the system should do, not how it does it. The test-engineer and implementer work concurrently on paired steps with disjoint file sets.
Paired step pattern:
- Test step (test-engineer): design behavioral tests from acceptance criteria
- Implementation step (implementer): write production code
- Integration checkpoint (implementer): run full test suite, fix all failures including pre-existing broken tests (boy scout rule)
Create paired test steps when:
- The step implements behavioral acceptance criteria
- Complex algorithms or business logic
- Critical user flows or integration points
- Edge cases in important features
- Fixing bugs (regression tests)
Skip paired test steps when:
- Obvious code with no logic (simple wiring, config)
- Framework-provided functionality
- Code that will be deleted soon
Commit Discipline
NEVER commit without user approval.
After completing a step:
- Verify formatters and linters pass (fix mode already applied)
- Verify type checker passes (if configured)
- Run relevant tests if they exist
- Verify system is in working state
- Update WIP.md with progress
- Capture any learnings in LEARNINGS.md
- STOP and ask: "Ready to commit [description]. Approve?"
Only proceed with commit after explicit approval.
IMPLEMENTATION_PLAN.md Structure
# Plan: [Feature Name]
## Goal
[One sentence describing the outcome]
## Tech Stack
[Language/framework and relevant context, e.g., "Python 3.13 with pixi — see [Python context](contexts/python.md)"]
## Acceptance Criteria
- [ ] Criterion 1
- [ ] Criterion 2
- [ ] Criterion 3
## Steps
### Step 1: [One sentence description]
**Implementation**: What code will we write?
**Tests**: groups=[<group_id>, ...] tier=<step|phase|pipeline> selector=<auto|manual> [reason=<enum> when selector=manual]
**Testing**: What needs testing? (if critical/complex)
**Done when**: How do we know it's complete?
### Step N: [One sentence description]
**Implementation**: ...
**Tests**: groups=[...] tier=... selector=...
**Testing**: ...
**Done when**: ...
Tests: field (optional): activates the test-topology protocol for this step. Absence means the protocol is inactive — the full suite runs (today's default behavior, backward-compatible). When present: groups lists group ids from .ai-state/TEST_TOPOLOGY.md; tier is step (narrow), phase (medium), or pipeline (full); selector is auto (runner derives the invocation from the group's selectors entries) or manual (implementer specifies the invocation directly). When selector=manual, reason must be one of: scope-mismatch, cross-pocket-bridge, topology-stale, tier-escalation-debug, other; other requires note=.... See skills/testing-strategy/references/test-topology.md for the full protocol. The topology protocol activates at Standard and Full tiers only.
Acceptance criteria source: In the agent pipeline, copy criteria verbatim from SYSTEMS_PLAN.md — the architect's criteria are authoritative and drive test design downstream. In manual planning (no SYSTEMS_PLAN.md), define criteria directly in the plan as concrete, testable conditions for "done."
Plan Changes Require Approval
If the plan needs to change:
- Explain what changed and why
- Propose updated steps
- Wait for approval before proceeding
Plans are not immutable, but changes must be explicit and approved.
WIP.md Structure
Track current step, status (IMPLEMENTING/TESTING/REVIEWING/WAITING/COMPLETE), progress checklist, blockers, and next action. Supports sequential mode (default) and parallel mode for concurrent steps.
If WIP.md doesn't reflect reality, update it immediately. Update when starting a step, when status changes, when blockers appear/resolve, after each commit, and at end of each session.
--> See references/document-templates.md for full WIP.md templates (sequential and parallel modes).
LEARNINGS.md Structure
Sections: Assumptions & Constraints Taken, Gotchas, Patterns That Worked, Decisions Made, Edge Cases, Technical Debt. Capture learnings immediately as they occur -- don't wait until the end. Every entry must be tagged with the source: **[agent-name]** (e.g., [implementation-planner], [implementer], [verifier], [main-agent]).
--> See references/document-templates.md for the full template.
When recording entries in ### Decisions Made, decision-making agents (systems-architect, implementation-planner) also create an ADR file in .ai-state/decisions/ following the adr-conventions rule. See the ADR authoring protocols reference for the file creation workflow.
Workflow
START: Create IMPLEMENTATION_PLAN.md (get approval) + WIP.md + LEARNINGS.md
FOR EACH STEP:
1. Update WIP.md (IMPLEMENTING)
2. Write implementation + tests (if critical)
3. Format → lint (fix mode) → type check → test
4. Capture learnings, update WIP.md (WAITING)
5. WAIT FOR COMMIT APPROVAL
END: Verify all criteria met, merge learnings, delete all three docs
Context Compaction Checkpoints
In long pipelines, the main agent should run /compact at natural phase boundaries to keep context clean. Recommended points:
- After research + architecture (high file reading is done; implementation needs clean context)
- After each implementation group completes (test output and diffs accumulate)
- Before verification (verifier benefits from a focused context with just the plan and outcomes)
The PreCompact hook snapshots pipeline documents to .ai-work/PIPELINE_STATE.md automatically. After compacting, re-read that file and WIP.md to restore orientation. Use /compact Focus on [current phase] with a hint when context is dominated by a prior phase's artifacts.
Conversation Checkpoints
At phase boundaries and before verification, the orchestrator pauses to surface the critical assumptions and constraints taken — digested from the ## Assumptions & Constraints Taken section of LEARNINGS.md — so the user can reflect or roll back. See coordination-details.md#conversation-checkpoints for the digest shape, rollback routing, and automated-mode behavior.
End of Feature
When all steps are complete: verify all acceptance criteria met, merge learnings to permanent locations (CLAUDE.md, ADRs, issue tracker), then delete all planning documents.
--> See references/document-templates.md for the full verification, merge, and cleanup workflow.
Breaking Down Complex Features
Start with a specific goal (not vague), identify concrete acceptance criteria, then decompose by asking "What's the smallest change that moves toward the goal?" Validate each step can be described in one sentence and done in one session.
--> See references/decomposition-guide.md for a full worked example with OAuth2, step validation checklist, and spike steps for unknowns.
Handling Unknowns
Use timeboxed spike steps for exploratory work. Spikes must produce a decision documented in LEARNINGS.md, then update the plan.
--> See references/decomposition-guide.md for spike step templates and characteristics.
Anti-Patterns
Critical gotchas (most common planning failures):
- Letting WIP.md become stale -- state drift between plan and reality causes cascading wrong decisions downstream
- Vague "done when" criteria -- "when it works" is not verifiable; leads to premature step completion or scope creep
- Changing plans silently -- unannounced plan changes break coordination and trust; all changes require discussion and approval
- Steps spanning multiple commits -- violates the known-good-increment principle; if a step needs multiple commits, break it down further
- Keeping planning docs after feature complete -- stale documents pollute future context loads; merge learnings to permanent locations and delete
--> See references/decomposition-guide.md for the full list of planning anti-patterns to avoid.
Claude Code Usage
The implementation-planner agent uses this skill directly for step decomposition, document creation, and execution supervision. For manual planning without agents, use Write and Edit tools directly. For simple single-session tasks, use TaskCreate/TaskUpdate/TaskList.
--> See references/decomposition-guide.md for the full agent crew workflow and selection table.
Quick Reference
Update Triggers
| Trigger | Update |
|---|
| Start new step | WIP.md status and progress |
| Discover gotcha | LEARNINGS.md gotchas section |
| Make decision | LEARNINGS.md decisions section |
| Take load-bearing assumption | LEARNINGS.md assumptions section |
| Complete step | WIP.md progress checklist |
| Hit blocker | WIP.md blockers section |
| Plan changes | IMPLEMENTATION_PLAN.md + get approval |
| End of session | WIP.md next action |
Checklist Before Commit Approval
Related Skills
- spec-driven-development -- behavioral specification format and REQ traceability; load together for medium/large features
- refactoring -- refactoring phase methodology delegated from plan steps
- python-development -- Python language context (quality gates, tooling)
- roadmap-planning -- upstream: roadmap items flow into this skill's step decomposition
