home / skills / anton-abyzov / specweave / increment-planner
/plugins/specweave/skills/increment-planner
This skill plans and generates SpecWeave increments with PM and Architect collaboration, creating spec.md, plan.md, and tasks.md with ACs and living docs.
npx playbooks add skill anton-abyzov/specweave --skill increment-plannerReview the files below or copy the command above to add this skill to your agents.
---
name: increment-planner
description: Plan and create SpecWeave increments with PM and Architect agent collaboration. Use when starting new features, hotfixes, bugs, or any development work that needs specification and task breakdown. Creates spec.md, plan.md, tasks.md with proper AC-IDs and living docs integration.
visibility: public
context: fork
model: opus
hooks:
PreToolUse:
- matcher: Write
hooks:
- type: command
command: bash plugins/specweave/hooks/v2/guards/spec-template-enforcement-guard.sh
---
# Increment Planner Skill
**Self-contained increment planning for ANY user project after `specweave init`.**
## Progressive Disclosure
Load phases as needed to reduce context:
| Phase | When to Load | File |
|-------|--------------|------|
| Pre-flight | Starting planning | `phases/00-preflight.md` |
| Project Context | Resolving project/board | `phases/01-project-context.md` |
| Create Increment | Creating files | `phases/02-create-increment.md` |
| Reference | Examples, troubleshooting | `phases/03-reference.md` |
## Quick Reference
### Increment Types
| Type | Use When | WIP Limit |
|------|----------|-----------|
| **feature** | New functionality | Max 2 |
| **hotfix** | Production broken | Unlimited |
| **bug** | Needs RCA | Unlimited |
| **change-request** | Business changes | Max 2 |
| **refactor** | Technical debt | Max 1 |
| **experiment** | POC/spike | Unlimited |
### Directory Structure
```
.specweave/increments/####-name/
├── metadata.json # REQUIRED - create FIRST
├── spec.md # REQUIRED - user stories, ACs
├── plan.md # OPTIONAL - architecture
└── tasks.md # REQUIRED - implementation
```
## Workflow Overview
```
STEP 0: Pre-flight (TDD mode, multi-project)
→ Load phases/00-preflight.md
STEP 1: Project Context (resolve project/board)
→ Load phases/01-project-context.md
STEP 2: Create Increment (via Template API)
→ Load phases/02-create-increment.md
STEP 3: Guide User (complete in main conversation)
```
## Critical Rules
### 1. Project Field is MANDATORY
Every US MUST have `**Project**:` field:
```markdown
### US-001: Feature Name
**Project**: my-app # ← REQUIRED!
**As a** user...
```
Get project: `specweave context projects`
### 2. Use Template Creator API
**Direct Write is FORBIDDEN!** Use:
```bash
specweave create-increment --id "0021-name" --project "my-app"
```
### 3. NO Agent Spawning
Skills MUST NOT spawn Task() agents (causes crashes).
Guide user to complete in MAIN conversation.
### 4. Increment Naming
Format: `####-descriptive-kebab-case`
```
✅ 0001-user-authentication
❌ 0001 (no description)
❌ my-feature (no number)
```
## Token Budget
- **Quick reference** (this file): ~400 tokens
- **Each phase**: ~300-500 tokens
- **Total if all loaded**: ~2000 tokens
**Load phases on-demand, not all at once!**
## Delegation
- **Pre-flight checks**: `/sw:increment` command handles WIP, discipline
- **Spec completion**: PM skill (in main conversation)
- **Architecture**: Architect skill (in main conversation)
- **Task generation**: Test-aware planner (in main conversation)
## Usage
```typescript
// Direct invocation
Skill({ skill: "sw:increment-planner", args: "--description=\"Add auth\"" })
// Via command (recommended - handles pre-flight)
/sw:increment "Add user authentication"
```
> **NOTE**: Use `sw:` prefix! Plain `increment-planner` fails.
This skill plans and creates SpecWeave increments by coordinating Product Manager and Architect inputs to produce spec.md, plan.md, and tasks.md with proper AC-IDs and living-docs integration. It guides you through pre-flight checks, project binding, increment naming, and uses the Template Creator API to generate increment scaffolding. Use it to start features, hotfixes, bugs, refactors, or experiments with disciplined, reproducible increments. It enforces required metadata and naming conventions to keep increments consistent and traceable.
The skill loads phased guidance on demand (pre-flight, project context, create increment, reference) to minimize token use and surface only relevant steps. It validates mandatory fields like Project and increment naming, enforces rules (no direct file writes), and instructs you to run the SpecWeave create-increment command to produce the metadata.json, spec.md, plan.md (optional), and tasks.md files. It does not spawn agents; instead it coordinates PM and Architect collaboration inside the main conversation and hands off task generation to the test-aware planner.
Can the skill write files directly into the repository?
No. The skill requires using the SpecWeave create-increment command or Template Creator API to generate files; direct writes are forbidden.
What naming convention must I use for increments?
Use a four-digit numeric prefix followed by descriptive kebab-case (e.g., 0001-user-authentication).
Does the skill spawn agents to generate tasks or architecture?
No. It does not spawn Task agents; PM and Architect work happens in the main conversation and the test-aware planner handles task generation.