status

Show comprehensive increment status overview with progress tracking and suggestions.

Synopsis

specweave status [options]

Description

The status command displays a comprehensive overview of all increments in your project, including:

• Overall progress (X/Y increments complete)
• Active increments (currently working)
• Paused increments (temporarily blocked)
• Completed increments (done and shipped)
• Abandoned increments (cancelled work)
• WIP limit status (are you at capacity?)
• Warnings (stale work, context switching)
• Suggestions (next actions)

Use status when:

• 📊 Checking overall project progress
• 🔍 Finding which increment to work on
• ⚠️ Identifying stale or blocked work
• 📈 Understanding WIP limit status

Check Status Daily

Run specweave status at the start of each day to understand current work and identify any issues early.

Options

No arguments (default)

Show all increments with summary.

specweave status

--verbose or -v

Show detailed information (progress %, age, last activity).

specweave status --verbose

--type <type>

Filter by increment type (feature, hotfix, bug, etc.).

specweave status --type=feature

Examples

Example 1: Basic Status Check

$ specweave status

📊 Increment Status

📈 Overall Progress: 3/8 increments complete (38%)

▶️  Active (1):
  ● 0007-smart-increment-discipline [feature] (80% complete)

⏸️  Paused (1):
  ⏸ 0005-kubernetes-migration [feature]
     Reason: Waiting for DevOps approval

📈 WIP Limit:
  ✅ Active increments: 1/1

📊 Summary:
   Active: 1
   Paused: 1
   Completed: 3
   Abandoned: 3
   Total: 8

💡 Continue work with: specweave do

What you see:

• ✅ Overall progress (3/8 = 38%)
• ✅ 1 active increment (80% complete)
• ✅ 1 paused increment (with reason)
• ✅ WIP limit status (1/1 - at capacity)
• ✅ Summary of all statuses
• ✅ Next action suggestion

Example 2: Multiple Active Increments (WIP Limit Warning)

$ specweave status

📊 Increment Status

📈 Overall Progress: 2/10 increments complete (20%)

▶️  Active (3):
  ● 0007-payment-integration [feature]
  ● 0008-notification-system [feature]
  ● 0009-refactor [refactor]

📈 WIP Limit:
  ⚠️  Active increments: 3/1 (EXCEEDS LIMIT!)
     💡 Run 'specweave pause <id>' to pause one before starting new work

📊 Summary:
   Active: 3  # ← Too many!
   Paused: 0
   Completed: 2
   Total: 10

⚠️  WARNING: High context switching detected!
   Research shows: 3+ concurrent tasks = 40-60% productivity loss

💡 Suggestions:
   - Complete one increment before continuing
   - Or pause 2 increments to free capacity

Key insight: Status command warns when WIP limit is exceeded!

Example 3: Verbose Output

$ specweave status --verbose

📊 Increment Status

📈 Overall Progress: 4/10 increments complete (40%)

▶️  Active (2):
  ● 0007-payment-integration [feature]
     Progress: 75% (15/20 tasks)
     Age: 5 days
     Last activity: 2 hours ago
     Last: Implemented Stripe webhook handler

  ● 0009-refactor [refactor]
     Progress: 30% (6/20 tasks)
     Age: 12 days
     Last activity: 1 day ago
     Last: Extracted service layer

⏸️  Paused (1):
  ⏸ 0008-kubernetes [feature]
     Progress: 20% (4/20 tasks)
     Paused: 7 days ago
     Reason: Waiting for DevOps approval on cluster config
     ⚠️  STALE! Review or abandon?

✅ Completed (4):
  0001-core-framework (completed 30 days ago)
  0002-core-enhancements (completed 25 days ago)
  0003-model-selection (completed 20 days ago)
  0004-plugin-architecture (completed 15 days ago)

📈 WIP Limit:
  ⚠️  Active increments: 2/1 (EXCEEDS LIMIT!)

📊 Summary:
   Active: 2
   Paused: 1
   Completed: 4
   Total: 10

💡 Suggestions:
   - Complete 0007 first (75% done, almost there!)
   - Resume or abandon 0008 (stale, paused 7 days)

Verbose mode shows:

• Task progress percentages
• Age (how long increment has been active)
• Last activity timestamp
• Last task completed
• Stale warnings for paused increments

Example 4: Filter by Type

$ specweave status --type=feature

📊 Feature Increments

▶️  Active (2):
  ● 0007-payment-integration [feature]
  ● 0008-notification-system [feature]

⏸️  Paused (1):
  ⏸ 0006-kubernetes [feature]
     Reason: Waiting for DevOps

✅ Completed (3):
  0001-core-framework
  0002-core-enhancements
  0003-model-selection

📊 Feature Summary:
   Active: 2
   Paused: 1
   Completed: 3
   Total: 6

Behavior

Overall Progress Calculation

// Count completed increments
const completed = increments.filter(i => i.status === 'completed');
const total = increments.length;
const progress = Math.round((completed.length / total) * 100);

// Display
console.log(`📈 Overall Progress: ${completed.length}/${total} increments complete (${progress}%)`);

Key insight: Overall progress = completed increments / total increments.

Task Progress Calculation

For each active increment, progress is calculated from tasks.md:

// Count completed tasks: [x] or [X]
const completedMatches = tasksContent.match(/\[x\]/gi);
const completedTasks = completedMatches ? completedMatches.length : 0;

// Count total tasks: [ ] or [x]
const totalMatches = tasksContent.match(/\[ \]|\[x\]/gi);
const totalTasks = totalMatches ? totalMatches.length : 0;

// Calculate percentage
const progress = Math.round((completedTasks / totalTasks) * 100);

WIP Limit Checking

const activeCount = increments.filter(i => i.status === 'active').length;
const limit = 1; // Default: 1 active increment

if (activeCount > limit) {
  console.log('⚠️  Active increments:', activeCount, '/', limit, '(EXCEEDS LIMIT!)');
  console.log('💡 Run "specweave pause <id>" to pause one before starting new work');
}

Status Icons

Status	Icon	Meaning
Active	●	Currently working
Paused	⏸	Temporarily blocked
Completed	✅	Done and shipped
Abandoned	❌	Cancelled/obsolete
Stale	⚠️	Paused >7 days or active >30 days

Warnings and Suggestions

Stale Paused Increments

Paused >7 days → warning:

⏸️  Paused (1):
  ⏸ 0007-kubernetes [feature]
     Paused: 10 days ago
     Reason: Waiting for API keys
     ⚠️  STALE! Review or abandon?

💡 Actions:
   specweave resume 0007  # If unblocked
   specweave abandon 0007 # If no longer needed

Long-Running Active Increments

Active >30 days → warning:

▶️  Active (1):
  ● 0009-big-refactor [refactor]
     Progress: 45% (23/50 tasks)
     Age: 35 days
     ⚠️  Long-running! Consider breaking into smaller increments

💡 Suggestion: Large increments increase risk and reduce velocity

Context Switching Cost

Multiple active → warning:

▶️  Active (3):
  ● 0007-payment
  ● 0008-notifications
  ● 0009-refactor

⚠️  WARNING: High context switching detected!
   Research shows: 3+ concurrent tasks = 40-60% productivity loss

💡 Complete or pause one before continuing

Almost Complete Suggestions

▶️  Active (2):
  ● 0007-payment (90% complete)  # ← Almost done!
  ● 0008-notifications (20% complete)

💡 Suggestions:
   - Complete 0007 first (90% done, almost there!)
   - Then focus on 0008

Common Scenarios

Scenario 1: Daily Standup Check

# Morning routine: Check status
$ specweave status

📊 Increment Status
📈 Overall Progress: 4/10 complete (40%)

▶️  Active (1):
  ● 0007-payment-integration (75% done)

💡 Continue work with: specweave do

# Clear picture of what to work on today!

Scenario 2: Before Starting New Work

# Check capacity before creating new increment
$ specweave status

▶️  Active (1): 0007-payment-integration
📈 WIP Limit: ✅ 1/1

# At capacity! Complete current work first
$ specweave do

# Or pause current work
$ specweave pause 0007 --reason "Hotfix needed"
$ specweave inc "0008-critical-bugfix"  # ✅ Now works

Scenario 3: Sprint Review

# Review sprint progress
$ specweave status

📈 Overall Progress: 6/12 complete (50%)

✅ Completed (2 this sprint):
  0005-user-auth (completed 5 days ago)
  0006-notifications (completed 2 days ago)

▶️  Active (1):
  ● 0007-payment-integration (80% done)
     Age: 10 days
     Almost complete!

📊 Sprint Summary:
   - 2 increments completed
   - 1 increment in progress (80% done)
   - 0 abandoned
   - Velocity: Good!

Scenario 4: Finding Stale Work

# Identify stale increments
$ specweave status --verbose

⏸️  Paused (3):
  ⏸ 0005-kubernetes (paused 45 days) ⚠️  STALE!
  ⏸ 0007-refactor (paused 30 days) ⚠️  STALE!
  ⏸ 0008-experiment (paused 60 days) ⚠️  STALE!

💡 Action needed: Review or abandon stale work

# Clean up
$ specweave abandon 0005 --reason "Too old, requirements changed"
$ specweave abandon 0008 --reason "Experiment obsolete"
$ specweave resume 0007  # Still relevant

Integration with Other Commands

status → do

$ specweave status
▶️  Active (1): 0007-payment

$ specweave do  # Continue active work

status → pause

$ specweave status
▶️  Active (2): 0007-payment, 0008-notifications
📈 WIP Limit: ⚠️  2/1 (EXCEEDS LIMIT!)

$ specweave pause 0008 --reason "Focus on 0007"

status → resume

$ specweave status
⏸️  Paused (1): 0007-payment (Waiting for API keys)

# API keys arrived
$ specweave resume 0007
$ specweave do  # Continue work

status → abandon

$ specweave status
⏸️  Paused (1): 0008-old-feature (paused 45 days) ⚠️  STALE!

$ specweave abandon 0008 --reason "Too old, requirements changed"

Configuration

Configure WIP limits and staleness thresholds in .specweave/config.json:

{
  "limits": {
    "feature": 1,                    // Max 1 active feature
    "hotfix": 1,                     // Max 1 active hotfix
    "experimentAutoAbandonDays": 14, // Auto-abandon experiments
    "staleness": {
      "paused": 7,                   // Warn if paused > 7 days
      "active": 30                   // Warn if active > 30 days
    }
  }
}

Adjust based on team size:

Team Size	Recommended Limit
Solo (1)	1
Small (2-3)	1-2
Medium (4-7)	2-3
Large (8-15)	3-5

Output Reference

Status Summary

📊 Increment Status

📈 Overall Progress: X/Y increments complete (Z%)

▶️  Active (N):
  ● increment-id [type] (progress%)

⏸️  Paused (N):
  ⏸ increment-id [type]
     Reason: why paused

✅ Completed (N):
  increment-id (completed X days ago)

❌ Abandoned (N):
  increment-id (reason)

📈 WIP Limit:
  ✅/⚠️  Active increments: X/Y

📊 Summary:
   Active: N
   Paused: N
   Completed: N
   Abandoned: N
   Total: N

💡 Suggestions:
   - Next actions based on current state

Error Handling

No Increments

$ specweave status

📊 Increment Status

No increments found.

💡 Create your first increment: specweave inc "feature description"

No Active Increments

$ specweave status

📊 Increment Status

📈 Overall Progress: 4/10 complete (40%)

▶️  Active (0):
  (none)

⏸️  Paused (2):
  ⏸ 0007-feature
  ⏸ 0008-refactor

💡 Resume a paused increment: specweave resume <id>
   Or start new work: specweave inc "feature description"

Best Practices

1. Check Status Daily

# Start of day routine
$ specweave status

# Clear picture of:
# - What to work on
# - Any blocked work
# - Overall progress

2. Before Creating New Increments

# Always check capacity first
$ specweave status

# If at WIP limit:
# - Complete current work, OR
# - Pause current work

3. Weekly Stale Review

# Every Friday: Review stale work
$ specweave status --verbose

# Action on stale increments:
# - Resume if unblocked
# - Abandon if obsolete
# - Update if still blocked

4. Sprint Reviews

# Sprint end: Review progress
$ specweave status

# Metrics:
# - Overall progress (X/Y complete)
# - Velocity (N completed this sprint)
# - Abandonment rate (learning opportunity)

See Also

• pause - Pause active work
• resume - Resume paused work
• abandon - Cancel work permanently
• Status Management - Complete workflow guide

Summary

Key Points:

• ✅ Shows comprehensive project overview
• ✅ Overall progress tracking (X/Y complete)
• ✅ WIP limit status and warnings
• ✅ Stale work detection
• ✅ Context switching warnings
• ✅ Next action suggestions

Command:

specweave status [--verbose] [--type=<type>]

Philosophy:

Visibility drives action. Check status daily, address warnings promptly, maintain focus.