Lesson 06.2: Core Workflow

Duration: 60 minutes | Difficulty: Beginner

Learning Objectives

By the end of this lesson, you will understand:

The three core phases of SpecWeave development
When and how to use each command
The complete increment lifecycle
Supporting commands for workflow management

The Three Phases

SpecWeave development follows a simple cycle:

Phase	Command	Purpose
Plan	`/sw:increment`	Create specifications
Build	`/sw:do`	Implement tasks
Validate	`/sw:done`	Verify quality

Phase 1: Plan (`/sw:increment`)

This is where the magic starts. A single description becomes complete specifications.

How It Works

/sw:increment "User authentication with email/password login"

The AI agents create:

spec.md — PM Agent
- Feature scope definition
- User stories (As a... I want... So that...)
- Acceptance criteria (testable conditions)
plan.md — Architect Agent
- Architecture Decision Records (ADRs)
- Component design
- Technology choices
- Risk assessment
tasks.md — Tech Lead Agent
- Task breakdown
- Dependencies
- BDD test scenarios
- Estimated complexity

Example Output

/sw:increment "Task tracker CLI with add, list, complete, delete"

Creating increment 0001-task-tracker-cli...

📋 PM Agent creating spec.md...
   ✓ Feature scope defined
   ✓ 4 user stories created
   ✓ 12 acceptance criteria defined

🏗️ Architect Agent creating plan.md...
   ✓ 2 architecture decisions recorded
   ✓ Component design complete
   ✓ Error handling strategy defined

📝 Tech Lead Agent creating tasks.md...
   ✓ 10 tasks created
   ✓ Dependencies mapped
   ✓ BDD scenarios written

Increment 0001-task-tracker-cli ready!

Review specs at:
  .specweave/increments/0001-task-tracker-cli/spec.md
  .specweave/increments/0001-task-tracker-cli/plan.md
  .specweave/increments/0001-task-tracker-cli/tasks.md

Key Principles

One increment = One feature — Don't pack too much into one increment
Review before proceeding — Read the specs, suggest changes
Smaller is better — More increments with fewer tasks each

Phase 2: Build (`/sw:do`)

With specifications approved, implementation begins.

How It Works

/sw:do

SpecWeave:

Loads the active increment
Identifies pending tasks
Implements each task sequentially
Updates task status
Syncs with specs

During Implementation

/sw:do

Loading increment 0001-task-tracker-cli...

📋 Task Progress: 0/10 complete

Working on T-001: Set up project structure
  ✓ Created package.json
  ✓ Created src/ directory
  ✓ Initialized storage module
  → T-001 complete

Working on T-002: Implement task data model
  ✓ Created Task interface
  ✓ Added validation functions
  → T-002 complete

Working on T-003: Implement add task function
  ...

📊 Progress: 3/10 tasks complete

Key Principles

Tasks are atomic — Each task is a single unit of work
Tests accompany code — BDD scenarios become tests
Progress is tracked — Status updates in real-time
Context is maintained — AI knows the full spec

Pausing and Resuming

Life happens. You can pause and resume:

# Pause current work
/sw:pause 0001

# Resume later
/sw:resume 0001

# Check status
/sw:status

Phase 3: Validate (`/sw:done`)

Before marking complete, quality gates must pass.

How It Works

/sw:done 0001

SpecWeave validates:

Task Completion
- All tasks marked complete
- No pending tasks remain
Acceptance Criteria
- Each AC has a corresponding task
- All ACs satisfied by tests
Test Coverage
- Unit tests exist
- Coverage meets threshold (default: 70%)
Code Quality
- No critical linting errors
- No security vulnerabilities

Example Output

/sw:done 0001

Validating increment 0001-task-tracker-cli...

📋 Task Completion
   ✓ 10/10 tasks complete

✅ Acceptance Criteria
   ✓ AC-US1-01: Task can be added (T-003)
   ✓ AC-US1-02: Task ID is auto-generated (T-003)
   ✓ AC-US2-01: All tasks can be listed (T-004)
   ... (12/12 satisfied)

🧪 Test Coverage
   ✓ Unit tests: 85%
   ✓ Integration tests: 72%
   ✓ Meets threshold (70%)

🔒 Code Quality
   ✓ No linting errors
   ✓ No security vulnerabilities

═══════════════════════════════════════════════
  Increment 0001-task-tracker-cli COMPLETE
═══════════════════════════════════════════════

📄 Completion report:
   .specweave/increments/0001-task-tracker-cli/completion-report.md

If Validation Fails

/sw:done 0001

Validating increment 0001-task-tracker-cli...

📋 Task Completion
   ⚠️ 8/10 tasks complete
   Pending: T-009, T-010

❌ Cannot mark complete. Fix issues:
   - Complete pending tasks: T-009, T-010

The Flow Command: `/sw:next`

Pro tip: Instead of running /sw:done then deciding what's next, use /sw:next:

/sw:next

This single command:

Validates current increment — Checks if work is complete
Auto-closes if ready — PM validates and closes automatically
Runs quality assessment — Post-closure quality check
Suggests next work — Intelligent recommendations

Example: Happy Path

/sw:next

📊 Checking current increment...

Active: 0001-task-tracker-cli

🔍 PM Validation:
  ✅ Gate 1: All tasks complete (10/10)
  ✅ Gate 2: All tests passing (85% coverage)
  ✅ Gate 3: Documentation updated

🎯 Auto-closing increment 0001...
  ✓ Status: completed
  ✓ Quality score: 87/100 (GOOD)

🎉 Increment 0001 closed successfully!

🎯 Next Work Suggestions:

No planned increments found.
Time to plan your next feature!

Run: /sw:increment "feature description"

Example: Not Ready Yet

/sw:next

📊 Checking current increment...

❌ Gate 1: 2 P1 tasks incomplete (8/10)

Options:
A. Complete remaining work (recommended)
B. Force close and defer tasks
C. Stay on current increment

What would you like to do? [A/B/C]

Why /sw:next is special:

✅ One command for the entire completion flow
✅ No need to remember /done → /qa → /increment sequence
✅ Intelligent suggestions from backlog
✅ Never forces actions — you stay in control

Supporting Commands

`/sw:status`

View current state:

/sw:status

SpecWeave Status
════════════════════

Active Increment: 0001-task-tracker-cli
  Status: in_progress
  Tasks: 6/10 complete (60%)
  ACs: 8/12 satisfied (67%)

WIP Limit: 1 (current: 1)

`/sw:progress`

Detailed progress view:

/sw:progress 0001

Increment: 0001-task-tracker-cli
═══════════════════════════════

User Stories & Tasks:
─────────────────────
US-001: Add Task
  [x] T-001: Project setup
  [x] T-002: Task data model
  [x] T-003: Add task function
  [ ] T-004: Add task tests

US-002: List Tasks
  [x] T-005: List function
  [ ] T-006: List tests

`/sw:validate`

Run validation without completing:

/sw:validate 0001

Validation Results:
  Tasks: 6/10 complete
  ACs: 8/12 satisfied
  Coverage: 72%
  Issues: 2 pending tasks

`/sw:sync-docs`

Sync living documentation:

/sw:sync-docs

Syncing documentation...
  ✓ Updated API reference
  ✓ Updated feature docs
  ✓ Updated changelog

The Complete Lifecycle

State Transitions

From	To	Trigger
None	Planning	`/sw:increment`
Planning	Review	Specs generated
Review	Building	Specs approved
Building	Paused	`/sw:pause`
Paused	Building	`/sw:resume`
Building	Validating	`/sw:done`
Validating	Complete	All gates pass

Best Practices

1. Small Increments

# ❌ Too big
/sw:increment "Complete e-commerce platform"

# ✓ Right size
/sw:increment "User registration with email verification"
/sw:increment "Product catalog display"
/sw:increment "Shopping cart functionality"

2. Review Specs Before Building

/sw:increment "Feature X"

# STOP! Review before proceeding:
cat .specweave/increments/0001-feature-x/spec.md
cat .specweave/increments/0001-feature-x/plan.md
cat .specweave/increments/0001-feature-x/tasks.md

# Make adjustments if needed, then:
/sw:do

3. Complete Before Starting New

# ❌ Don't jump between increments
/sw:increment "Feature A"
/sw:do  # Partially done
/sw:increment "Feature B"  # Starting new!

# ✓ Complete one at a time
/sw:increment "Feature A"
/sw:do
/sw:done 0001
/sw:increment "Feature B"

4. Use Status Commands

# Regular check-ins
/sw:status        # Quick status
/sw:progress 0001 # Detailed progress
/sw:validate 0001 # Pre-validate

Key Takeaways

Three phases: Plan → Build → Validate — never skip
/sw:increment creates specifications — the foundation
/sw:do implements with context — not just code generation
/sw:done validates quality — gates ensure completeness
Supporting commands help manage — status, progress, validate

Next Lesson

Now let's create your first real increment and see this workflow in action.

→ Continue to Lesson 06.3: Your First Increment

Learning Objectives​

The Three Phases​

Phase 1: Plan (/sw:increment)​

How It Works​

Example Output​

Key Principles​

Phase 2: Build (/sw:do)​

How It Works​

During Implementation​

Key Principles​

Pausing and Resuming​

Phase 3: Validate (/sw:done)​

How It Works​

Example Output​

If Validation Fails​

The Flow Command: /sw:next​

Example: Happy Path​

Example: Not Ready Yet​

Supporting Commands​

/sw:status​

/sw:progress​

/sw:validate​

/sw:sync-docs​

The Complete Lifecycle​

State Transitions​

Best Practices​

1. Small Increments​

2. Review Specs Before Building​

3. Complete Before Starting New​

4. Use Status Commands​

Key Takeaways​

Next Lesson​

Learning Objectives

The Three Phases

Phase 1: Plan (`/sw:increment`)

How It Works

Example Output

Key Principles

Phase 2: Build (`/sw:do`)

How It Works

During Implementation

Key Principles

Pausing and Resuming

Phase 3: Validate (`/sw:done`)

How It Works

Example Output

If Validation Fails

The Flow Command: `/sw:next`

Example: Happy Path

Example: Not Ready Yet

Supporting Commands

`/sw:status`

`/sw:progress`

`/sw:validate`

`/sw:sync-docs`

The Complete Lifecycle

State Transitions

Best Practices

1. Small Increments

2. Review Specs Before Building

3. Complete Before Starting New

4. Use Status Commands

Key Takeaways

Next Lesson