specweave 0.1.8 → 0.1.9

package/README.md

@@ -3,7 +3,7 @@
 > **Spec-Driven Development Framework** - Where specifications and documentation are the source of truth
 
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
-[![Version](https://img.shields.io/badge/version-0.1.8-blue.svg)](https://github.com/anton-abyzov/specweave/releases/tag/v0.1.8)
+[![Version](https://img.shields.io/badge/version-0.1.9-blue.svg)](https://github.com/anton-abyzov/specweave/releases/tag/v0.1.9)
 [![Status](https://img.shields.io/badge/status-beta-blue.svg)]()
 [![Website](https://img.shields.io/badge/website-spec--weave.com-green.svg)](https://spec-weave.com)
 
@@ -147,15 +147,21 @@ User: /done 0001  # Close increment with slash command
 ✅ Increment 0001 closed successfully
 ```
 
-**How it works** (append-only increment workflow: 0001 → 0002 → 0003):
+**How it works** (smart append-only workflow: 0001 → 0002 → 0003):
 1. `specweave init` → ALL components pre-installed (10 agents + 35+ skills)
 2. **Use `/inc "feature"`** → PM creates specs + plan + auto-generates tasks
-3. **Use `/build 0001`** → Execute implementation (hooks after EVERY task)
-4. **Use `/validate 0001`** → Optional quality check (LLM-as-judge)
-5. **Use `/done 0001`** → PM validates 3 gates (tasks ✅ + tests ✅ + docs ✅)
-6. All components ready - no waiting, no installation
-
-**Why slash commands?** Auto-activation doesn't work reliably - slash commands ensure SpecWeave ALWAYS activates when you want it.
+   - **Smart**: Auto-closes previous increment if PM gates pass
+3. **Use `/build` or `/build 0001`** → Execute implementation (hooks after EVERY task)
+   - **Smart**: Auto-resumes from next incomplete task
+4. **Use `/progress`** → Check status, task completion %, next action
+5. **Use `/validate 0001`** → Optional quality check (LLM-as-judge)
+6. Repeat: `/inc "next feature"` → Auto-closes if ready, creates next increment
+
+**Why smart workflow?**
+- ✅ No manual `/done` needed (auto-closes on next `/inc`)
+- ✅ No task tracking needed (`/build` auto-resumes)
+- ✅ `/progress` shows exactly where you are
+- ✅ Natural flow: finish → start next
 
 ---
 
@@ -297,28 +303,33 @@ specweave/
 # Option A: Comprehensive (Enterprise) - 500-600+ pages upfront
 # Option B: Incremental (Startup) - Build as you go
 
-# 2. Plan increment with slash command (PM-led process)
+# 2. Plan increment (PM-led, auto-closes previous if ready)
 /inc "user authentication"
 # Alias for /increment
 # PM-led: Market research → spec.md → plan.md → auto-generate tasks.md
-# Creates: spec.md, plan.md, tasks.md (auto-generated!), tests.md
+# Smart: Auto-closes previous increment if PM gates pass
 
-# 3. Build it (hooks run after EVERY task)
-/build 0001
-# Executes tasks sequentially
+# 3. Build it (smart resume, hooks after EVERY task)
+/build
+# Or: /build 0001
+# Smart: Auto-resumes from next incomplete task
 # Hooks automatically update CLAUDE.md, README.md, CHANGELOG.md
 
-# 4. Validate quality (optional)
+# 4. Check progress anytime
+/progress
+# Shows: task completion %, PM gates status, next action
+# No increment ID needed - finds active increment automatically
+
+# 5. Validate quality (optional)
 /validate 0001 --quality
 # LLM-as-judge quality assessment
 
-# 5. Close increment (PM validates 3 gates)
-/done 0001
-# Gate 1: Tasks completed (P1 required)
-# Gate 2: Tests passing (>80% coverage)
-# Gate 3: Documentation updated
+# 6. Start next feature (auto-closes previous)
+/inc "payment processing"
+# Auto-closes 0001 if gates pass, creates 0002
+# No manual /done needed!
 
-# 6. Sync with tools (optional)
+# 7. Sync with tools (optional)
 /sync-github  # Sync to GitHub issues
 ```
 

package/SPECWEAVE.md

@@ -25,14 +25,15 @@ SpecWeave follows the **spec-kit approach**: You MUST use slash commands explici
 
 ### Quick Command Reference
 
-**Core Workflow** (4 commands):
+**Core Workflow** (Smart Commands):
 
 | Alias | Full Command | Purpose | Example |
 |-------|--------------|---------|---------|
-| `/inc` | `/increment` | **Plan Product Increment** (PM-led) | `/inc "User auth"` |
-| - | `/build` | Execute implementation (hooks after every task) | `/build 0001` |
+| `/inc` | `/increment` | **Plan Increment** (PM-led, auto-closes previous) | `/inc "User auth"` |
+| - | `/build` | Execute (smart resume, hooks after every task) | `/build` or `/build 0001` |
+| - | `/progress` | **Show status** (task %, PM gates, next action) | `/progress` |
 | - | `/validate` | Validate quality (optional LLM judge) | `/validate 0001 --quality` |
-| - | `/done` | Close increment (PM validates 3 gates) | `/done 0001` |
+| `/done` | `/done` | Close explicitly (optional, /inc auto-closes) | `/done 0001` |
 
 **Supporting Commands**:
 - `/create-project` - Initialize SpecWeave project
@@ -41,37 +42,61 @@ SpecWeave follows the **spec-kit approach**: You MUST use slash commands explici
 - `/generate-docs` - Generate doc site
 - `/sync-github` - Sync to GitHub
 
-**Why ONE Alias (/inc)?**
-- ✅ `/inc` is THE most used command (every new feature starts here)
-- ✅ Append-only increment workflow: 0001 → 0002 → 0003 → ...
-- ✅ Other commands used once per increment (no aliases needed)
-- ✅ Clear and explicit workflow
+**Smart Workflow Features**:
+- ✅ `/inc` suggests options if previous incomplete (never forces closure)
+- ✅ `/inc` auto-closes previous only if PM gates pass (seamless happy path)
+- ✅ `/build` auto-resumes from next incomplete task
+- ✅ `/progress` shows exactly where you are
+- ✅ `/done` is optional (use when explicit closure needed)
+- ✅ Natural flow: finish → start next (with user control)
 
-### Typical Workflow
+### Typical Workflow (Smart & Natural)
 
 ```bash
 # 1. Initialize project
 npx specweave init my-saas
 
-# 2. Plan your first increment (use /inc - the ONLY alias!)
+# 2. Plan your first increment
 /inc "User authentication with JWT and RBAC"
+# PM-led: market research → spec → plan → auto-generate tasks
 
 # 3. Review generated docs
 #    spec.md, plan.md, tasks.md (auto-generated!), tests.md
 
-# 4. Build it (hooks run after EVERY task)
-/build 0001
+# 4. Build it (smart resume, hooks after EVERY task)
+/build
+# Auto-resumes from next incomplete task
+# No need to track which task you're on!
 
-# 5. Validate quality (optional)
-/validate 0001 --quality
+# 5. Check progress anytime
+/progress
+# Shows: 5/12 tasks (42%), next: T006, PM gates status
+
+# 6. Continue building
+/build
+# Picks up where you left off
 
-# 6. Close when done (PM validates: tasks ✅ + tests ✅ + docs ✅)
-/done 0001
+# 7. Validate quality (optional)
+/validate 0001 --quality
 
-# 7. Repeat for next feature
+# 8. Start next feature (auto-closes previous!)
 /inc "Payment processing"
+# Smart: Auto-closes 0001 if PM gates pass
+# No manual /done needed!
+
+# 9. Keep building
+/build
+# Auto-finds active increment 0002
+
+# Repeat: /inc → /build → /progress → /inc (auto-closes) → /build...
 ```
 
+**Key Insight**: Natural flow without administrative overhead!
+- No manual tracking (`/build` auto-resumes)
+- No manual closure (`/inc` auto-closes if ready)
+- Check progress anytime (`/progress`)
+- Focus on building, not project management
+
 **Remember**: Type `/inc` first, THEN build! Otherwise you lose all SpecWeave benefits (specs, architecture, auto-generated tasks, test strategy).
 
 ---
@@ -201,14 +226,21 @@ npx specweave list --installed      # See what's installed
 
 **CRITICAL**: SpecWeave uses **EXPLICIT SLASH COMMANDS** - type them to activate the framework!
 
-### Core Workflow (4 Commands)
+### Core Workflow (Smart Commands)
 
 | Command | Alias | Purpose | Example |
 |---------|-------|---------|---------|
-| `/increment` | `/inc` | Plan Product Increment (PM-led, auto-generates tasks) | `/inc "user authentication"` |
-| `/build` | - | Execute implementation (hooks after EVERY task) | `/build 0001` |
+| `/increment` | `/inc` | Plan Increment (PM-led, auto-closes previous if ready) | `/inc "user authentication"` |
+| `/build` | - | Execute (smart resume from next incomplete task) | `/build` or `/build 0001` |
+| `/progress` | - | Show status (task %, PM gates, next action) | `/progress` |
 | `/validate` | - | Validate quality (optional LLM judge) | `/validate 0001 --quality` |
-| `/done` | - | Close increment (PM validates 3 gates: tasks, tests, docs) | `/done 0001` |
+| `/done` | - | Close explicitly (optional, /inc auto-closes) | `/done 0001` |
+
+**Smart Features**:
+- `/inc` suggests options if previous incomplete, auto-closes if PM gates pass
+- `/build` auto-resumes from next incomplete task (no task ID needed)
+- `/progress` auto-finds active increment (no ID needed)
+- `/done` optional in happy path (use for explicit closure only)
 
 ### Supporting Commands
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "specweave",
-  "version": "0.1.8",
-  "description": "Replace vibe coding with spec-driven development. 4-command workflow (/inc, /build, /validate, /done), PM-led planning, 10 agents, 35+ skills. Visit spec-weave.com",
+  "version": "0.1.9",
+  "description": "Replace vibe coding with spec-driven development. Smart workflow: /inc auto-closes previous, /build auto-resumes, /progress shows status. PM-led planning, 10 agents, 35+ skills. spec-weave.com",
   "main": "dist/index.js",
   "bin": {
     "specweave": "./bin/specweave.js"

package/src/commands/build.md

@@ -12,12 +12,18 @@ You are helping the user implement a SpecWeave increment by executing tasks from
 ## Usage
 
 ```bash
+# Auto-resumes from last incomplete task
 /build <increment-id>
+
+# Or let it find active increment automatically
+/build
 ```
 
 ## Arguments
 
-- `<increment-id>`: Required. Increment ID (e.g., "001", "0001", "1", "0042")
+- `<increment-id>`: Optional. Increment ID (e.g., "001", "0001", "1", "0042")
+  - If omitted, finds the active in-progress increment automatically
+  - **Smart resume**: Automatically starts from next incomplete task
 
 ---
 
@@ -54,9 +60,42 @@ You are helping the user implement a SpecWeave increment by executing tasks from
 🎯 Ready to build!
 ```
 
-### Step 2: Update Status to In-Progress
+### Step 2: Smart Resume - Find Next Incomplete Task
+
+**🎯 CRITICAL: Auto-resume functionality** - no need to remember which task you were on!
+
+1. **Parse tasks.md**:
+   - Scan all tasks in order
+   - Check completion status (`[x]` = complete, `[ ]` = incomplete)
+   - Find first incomplete task
+
+2. **Determine starting point**:
+   - If all tasks complete → Show completion message
+   - If tasks incomplete → Resume from first incomplete task
+   - If no tasks started → Start from T001
+
+3. **Show resume context**:
+   ```
+   📊 Resume Context:
 
-Update `spec.md` frontmatter:
+   Completed: 3/12 tasks (25%)
+   ├─ [✅] T001: Setup auth module (P1)
+   ├─ [✅] T002: Create user model (P1)
+   ├─ [✅] T003: Implement JWT tokens (P1)
+   └─ [⏳] T004: Add password hashing (P1) ← RESUMING HERE
+
+   Remaining: 9 tasks (estimated 2 weeks)
+   ```
+
+**Why smart resume?**
+- ✅ No manual tracking needed
+- ✅ Seamlessly continue after breaks
+- ✅ Prevents duplicate work
+- ✅ Shows progress at a glance
+
+### Step 3: Update Status to In-Progress (if needed)
+
+If status is "planned", update `spec.md` frontmatter:
 
 ```yaml
 ---
@@ -66,7 +105,9 @@ started: 2025-10-28      # ← Start date
 ---
 ```
 
-### Step 3: Execute Tasks Sequentially
+If already "in-progress", keep existing metadata.
+
+### Step 4: Execute Tasks Sequentially
 
 **For each task in tasks.md**:
 

package/src/commands/increment.md

@@ -1,20 +1,104 @@
 ---
-name: create-increment
-description: Create a new SpecWeave increment interactively with spec.md and tasks.md
+name: increment
+description: Plan new Product Increment - PM-led process (market research, spec, plan, auto-generate tasks). Auto-closes previous increment if PM gates pass.
 ---
 
-# Create New Increment
+# Plan Product Increment
 
-You are helping the user create a new SpecWeave increment.
+**PM-Led Workflow**: From market research to ready-to-build increment.
+
+You are helping the user create a new SpecWeave increment with automatic closure of previous increment if ready.
 
 ## Steps:
 
-1. **Find next increment number**:
-   - Scan `.specweave/increments/` directory
-   - Find highest number (e.g., 002)
-   - Next increment: 003
+### Step 0: Smart Check Previous Increment (if applicable)
+
+**🎯 CRITICAL: Suggest, don't force** - help user make informed decision!
+
+1. **Check for in-progress increments**:
+   ```bash
+   # Find increments with status: in-progress
+   grep -r "status: in-progress" .specweave/increments/*/spec.md
+   ```
+
+2. **If previous increment found, validate PM gates**:
+   - **Gate 1**: All P1 tasks completed?
+   - **Gate 2**: Tests passing (>80% coverage)?
+   - **Gate 3**: Documentation updated (CLAUDE.md, README.md)?
+
+3. **Decision matrix** (NEVER force, ALWAYS suggest):
+   ```
+   All gates ✅ → Auto-close previous, create new (seamless)
+
+   Any gate ❌ → STOP and present options (user decides):
+      Option A: Complete 0001 first (recommended)
+         → Finish remaining work before starting new
+
+      Option B: Move incomplete tasks to 0002
+         → Transfer T006, T007 to new increment
+         → Close 0001 as "completed with deferrals"
+
+      Option C: Cancel new increment
+         → Stay on 0001, continue working
+         → User will retry /inc when ready
+   ```
+
+**CRITICAL**: NEVER auto-close with incomplete work! Always give user control.
+
+4. **Auto-close output** (if gates pass):
+   ```
+   📊 Previous Increment Check
+
+   Found: 0001-user-authentication (in-progress)
+
+   PM Gate Validation:
+   ├─ Gate 1 (Tasks): 8/8 P1 completed ✅
+   ├─ Gate 2 (Tests): 5/5 passing (85% coverage) ✅
+   └─ Gate 3 (Docs): CLAUDE.md ✅, README.md ✅
+
+   ✅ Auto-closing increment 0001...
+
+   Proceeding with new increment 0002...
+   ```
+
+5. **Prompt output** (if gates fail):
+   ```
+   ⚠️ Previous Increment Incomplete
+
+   Found: 0001-user-authentication (in-progress)
+
+   PM Gate Validation:
+   ├─ Gate 1 (Tasks): 6/8 P1 completed ❌ (2 P1 tasks remaining)
+   ├─ Gate 2 (Tests): 3/5 passing (60% coverage) ❌
+   └─ Gate 3 (Docs): CLAUDE.md ✅, README.md ⏳
+
+   Options:
+   A. Complete 0001 first (recommended)
+      → Run `/build 0001` to finish remaining tasks
+
+   B. Force close 0001 and defer tasks to 0002
+      → Transfer T006, T007 to new increment
+
+   C. Cancel and stay on 0001
+      → Continue working on authentication
 
-2. **Detect tech stack** (CRITICAL - framework-agnostic):
+   What would you like to do? (A/B/C)
+   ```
+
+**Why suggest, not force?**
+- ✅ User stays in control (no surprises)
+- ✅ Natural flow in happy path (auto-close if ready)
+- ✅ Clear options when incomplete (complete, defer, or cancel)
+- ✅ Enforces quality awareness (can't ignore incomplete work)
+- ✅ No manual `/done` needed when gates pass
+
+### Step 1: Find next increment number
+
+- Scan `.specweave/increments/` directory
+- Find highest number (e.g., 002)
+- Next increment: 003
+
+### Step 2: Detect tech stack (CRITICAL - framework-agnostic)
    - Check `.specweave/config.yaml` for tech_stack configuration
    - If not found, detect from project files:
      - `package.json` → TypeScript/JavaScript
@@ -27,42 +111,47 @@ You are helping the user create a new SpecWeave increment.
    - If detection fails, ask user: "What language/framework are you using?"
    - Store detected tech stack for later use
 
-3. **Ask user for details**:
-   - "What would you like to build?" (get high-level description)
-   - "What's the short name?" (e.g., "user-authentication" for increment 003-user-authentication)
-   - "Priority? (P1/P2/P3)" (default: P1)
-
-4. **Activate role-orchestrator**:
-   - Analyze user's description
-   - Determine which strategic agents are needed:
-     - pm-agent (product strategy)?
-     - architect-agent (system design)?
-     - devops-agent (infrastructure)?
-     - security-agent (security review)?
-     - qa-lead-agent (testing strategy)?
-
-5. **Ask clarifying questions** (if needed):
-   - Target users/scale?
-   - Technology preferences? (if not detected)
-   - Budget constraints?
-   - Deployment platform?
-   - Payment processing needed?
-   - Authentication method?
-
-6. **Run strategic agents** (with user approval):
-   - **Pass detected tech stack to ALL agents** (CRITICAL!)
-   - PM agent creates pm-analysis.md
-   - Architect agent creates architecture.md, ADRs (using detected tech stack)
-   - DevOps agent creates infrastructure.md (platform-specific)
-   - Security agent creates security.md (framework-specific security)
-   - QA agent creates test-strategy.md (framework-specific tests)
-
-7. **Present strategic docs for review**:
-   - Show summary of all strategic outputs
-   - Ask: "Review docs with /review-docs or approve to continue?"
-   - Wait for user approval
-
-8. **Create spec.md** (based on strategic docs):
+### Step 3: Ask user for details
+
+- "What would you like to build?" (get high-level description)
+- "What's the short name?" (e.g., "user-authentication" for increment 003-user-authentication)
+- "Priority? (P1/P2/P3)" (default: P1)
+
+### Step 4: Activate role-orchestrator
+
+- Analyze user's description
+- Determine which strategic agents are needed:
+  - pm-agent (product strategy)?
+  - architect-agent (system design)?
+  - devops-agent (infrastructure)?
+  - security-agent (security review)?
+  - qa-lead-agent (testing strategy)?
+
+### Step 5: Ask clarifying questions (if needed)
+
+- Target users/scale?
+- Technology preferences? (if not detected)
+- Budget constraints?
+- Deployment platform?
+- Payment processing needed?
+- Authentication method?
+
+### Step 6: Run strategic agents (with user approval)
+
+- **Pass detected tech stack to ALL agents** (CRITICAL!)
+- PM agent creates pm-analysis.md
+- Architect agent creates architecture.md, ADRs (using detected tech stack)
+- DevOps agent creates infrastructure.md (platform-specific)
+- Security agent creates security.md (framework-specific security)
+- QA agent creates test-strategy.md (framework-specific tests)
+
+### Step 7: Present strategic docs for review
+
+- Show summary of all strategic outputs
+- Ask: "Review docs with /review-docs or approve to continue?"
+- Wait for user approval
+
+### Step 8: Create spec.md (based on strategic docs)
    - Frontmatter with increment number, title, priority, status, dependencies
    - **Include detected tech stack in frontmatter** (see format below)
    - Overview section
@@ -73,23 +162,27 @@ You are helping the user create a new SpecWeave increment.
    - Success criteria
    - Dependencies
 
-9. **Create tasks.md** (task-builder skill):
-   - Analyze all strategic docs
-   - Break down into phases (framework-specific)
-   - Create tasks with:
-     - Agent references (use framework-specific agents if available)
-     - File paths (framework-specific paths: src/ for TS, app/ for Django, etc.)
-     - Implementation snippets (framework-specific code)
-     - Acceptance criteria
-     - Documentation updates
-
-10. **Save increment**:
-    - Create `.specweave/increments/####-name/`
-    - Save spec.md
-    - Save tasks.md
-    - Save strategic docs (pm-analysis.md, architecture.md, etc.)
-
-11. **Output to user**:
+### Step 9: Create tasks.md (task-builder skill)
+
+**🎯 CRITICAL: Auto-generate tasks from plan.md**
+
+- Analyze all strategic docs
+- Break down into phases (framework-specific)
+- Create tasks with:
+  - Agent references (use framework-specific agents if available)
+  - File paths (framework-specific paths: src/ for TS, app/ for Django, etc.)
+  - Implementation snippets (framework-specific code)
+  - Acceptance criteria
+  - Documentation updates
+
+### Step 10: Save increment
+
+- Create `.specweave/increments/####-name/`
+- Save spec.md
+- Save tasks.md (auto-generated!)
+- Save strategic docs (pm-analysis.md, architecture.md, etc.)
+
+### Step 11: Output to user
     ```
     ✅ Created increment 0003-user-authentication
 

package/src/commands/progress.md

@@ -0,0 +1,258 @@
+---
+name: progress
+description: Show current increment progress, task completion %, PM gate status, and next action
+---
+
+# Progress Tracking
+
+**Quick Status Check**: See exactly where you are in your current increment.
+
+Shows:
+- Active increment status
+- Task completion percentage
+- PM gate preview (tasks, tests, docs)
+- Next action to take
+- Time tracking
+
+---
+
+## Usage
+
+```bash
+# Check current progress
+/progress
+
+# Show progress for specific increment
+/progress 0001
+```
+
+---
+
+## What It Shows
+
+### 1. Active Increment Info
+- Increment ID and name
+- Current status (planned, in-progress, completed)
+- Time started and last activity
+
+### 2. Task Progress (with %)
+- Visual task list with completion indicators
+- Percentage complete (P1 tasks weighted higher)
+- Next incomplete task highlighted
+- Stuck/blocked task warnings
+
+### 3. PM Gates Preview
+- **Gate 1**: Tasks completed (P1 required)
+- **Gate 2**: Tests passing (>80% coverage)
+- **Gate 3**: Documentation updated
+
+### 4. Next Action Guidance
+- Suggests exact command to run next
+- Warns about WIP limit violations
+- Alerts for long-inactive increments
+
+---
+
+## Example Output
+
+### Normal Progress
+
+```
+📊 Current Progress
+
+Active Increment: 0001-user-authentication
+Status: in-progress (started 2 hours ago)
+
+Task Progress: 3/12 completed (25%)
+├─ [✅] T001: Setup auth module (P1) - 5 min ago
+├─ [✅] T002: Create user model (P1) - 10 min ago
+├─ [✅] T003: Implement JWT tokens (P1) - 15 min ago
+├─ [⏳] T004: Add password hashing (P1) ← NEXT
+├─ [ ] T005: Create login endpoint (P1)
+├─ [ ] T006: Add logout endpoint (P2)
+└─ 6 more tasks...
+
+PM Gates Preview:
+├─ Gate 1 (Tasks): 3/8 P1 tasks done (38%) ⏳
+├─ Gate 2 (Tests): 2/5 passing (40%) ⏳
+└─ Gate 3 (Docs): CLAUDE.md ✅, README.md ⏳
+
+Last Activity: 5 minutes ago
+Next Action: Run `/build 0001` to resume at T004
+
+💡 Tip: `/build` auto-resumes from last incomplete task!
+```
+
+### No Active Work
+
+```
+📊 Current Progress
+
+No active increment found.
+
+Recent Increments:
+├─ 0003-payment-flow (completed) - 1 day ago
+├─ 0002-user-profile (completed) - 2 days ago
+└─ 0001-auth (closed) - 3 days ago
+
+Next Action: Run `/inc "feature description"` to start new work
+
+💡 Tip: `/inc` is your starting point for all new features
+```
+
+### Multiple In-Progress (WIP Limit Warning)
+
+```
+📊 Current Progress
+
+⚠️ Warning: 2 increments in-progress (exceeds recommended WIP limit: 1)
+
+Active Increments:
+1. 0002-payment-flow (in-progress)
+   └─ Task Progress: 5/10 completed (50%)
+
+2. 0003-notifications (in-progress)
+   └─ Task Progress: 2/8 completed (25%)
+
+Recommendation: Focus on completing 0002 before starting new work.
+
+Next Action: Run `/build 0002` to continue payment-flow
+```
+
+### Stuck/Inactive Increment
+
+```
+📊 Current Progress
+
+Active Increment: 0001-user-authentication
+Status: in-progress (started 2 days ago)
+
+⚠️ Warning: Last activity was 6 hours ago
+└─ Current task T005 may be stuck or blocked
+
+Task Progress: 4/12 completed (33%)
+├─ [✅] T001: Setup auth module (P1)
+├─ [✅] T002: Create user model (P1)
+├─ [✅] T003: Implement JWT tokens (P1)
+├─ [✅] T004: Add password hashing (P1)
+├─ [🔄] T005: Create login endpoint (P1) ← STUCK? (6 hours)
+├─ [ ] T006: Add logout endpoint (P2)
+└─ 6 more tasks...
+
+Next Action:
+1. Run `/build 0001` to retry T005
+2. Or manually review T005 for blockers
+3. Or skip T005 and defer to next increment
+
+💡 Tip: Long-running tasks may need breaking down
+```
+
+---
+
+## Implementation
+
+**How `/progress` works**:
+
+### Step 1: Find Active Increment
+
+```bash
+# Check for in-progress increments
+find .specweave/increments -name "tasks.md" -exec grep -l "status: in-progress" {} \;
+```
+
+### Step 2: Parse Tasks and Calculate %
+
+```bash
+# Read tasks.md
+# Count completed vs total
+# Weight P1 tasks higher (2x), P2 (1.5x), P3 (1x)
+# Calculate percentage
+
+Example:
+- P1 tasks: 3/8 complete = 3*2 / 8*2 = 6/16 (37.5%)
+- P2 tasks: 2/3 complete = 2*1.5 / 3*1.5 = 3/4.5 (66%)
+- P3 tasks: 1/1 complete = 1*1 / 1*1 = 1/1 (100%)
+
+Overall: (6 + 3 + 1) / (16 + 4.5 + 1) = 10/21.5 = 46.5%
+```
+
+### Step 3: Check PM Gates
+
+```bash
+# Gate 1: Tasks
+# - Count P1 tasks completed
+# - Status: ✅ all done, ⏳ in progress, ❌ blocked
+
+# Gate 2: Tests
+# - Run test suite (npm test or equivalent)
+# - Check coverage report
+# - Status: ✅ >80%, ⏳ 50-80%, ❌ <50%
+
+# Gate 3: Docs
+# - Check if CLAUDE.md updated recently
+# - Check if README.md mentions new feature
+# - Status: ✅ updated, ⏳ partial, ❌ outdated
+```
+
+### Step 4: Determine Next Action
+
+```bash
+if [[ $in_progress_count -eq 0 ]]; then
+    echo "Run \`/inc\` to start new feature"
+elif [[ $in_progress_count -gt 1 ]]; then
+    echo "⚠️ Multiple increments active. Focus on completing one."
+    echo "Run \`/build $oldest_increment\`"
+elif [[ $next_task != "" ]]; then
+    echo "Run \`/build $increment_id\` to resume at $next_task"
+else
+    echo "All tasks complete! Run \`/done $increment_id\` to close."
+fi
+```
+
+---
+
+## When to Use `/progress`
+
+Use `/progress` when you:
+- ✅ Come back after a break and need context
+- ✅ Want to see overall completion status
+- ✅ Need to know which task to work on next
+- ✅ Forgot which increment you're working on
+- ✅ Want to check if PM gates will pass
+- ✅ Suspect a task is stuck or blocked
+- ✅ Have multiple increments and need to prioritize
+
+**Typical workflow**:
+```bash
+# Morning: Check what you were working on
+/progress
+
+# Shows: "Active: 0002-payments, Task 5/10 (50%)"
+# Shows: "Next: /build 0002 to resume at T006"
+
+/build 0002
+# Auto-resumes from T006
+```
+
+---
+
+## Pro Tips
+
+1. **No increment ID needed** - `/progress` automatically finds active increment
+2. **Smart resume** - `/build` picks up where you left off (no task ID needed)
+3. **WIP limits** - Keep 1-2 increments active max for focus
+4. **Completion %** - P1 tasks weighted higher (they're critical path)
+5. **Time tracking** - Warns if tasks are stuck (>2 hours inactive)
+
+---
+
+## Related Commands
+
+- `/inc` - Start new increment (auto-closes previous if ready)
+- `/build` - Execute tasks (auto-resumes from next incomplete)
+- `/validate` - Run quality checks (optional)
+- `/done` - Explicitly close increment (optional if `/inc` auto-closes)
+
+---
+
+**💡 Remember**: `/progress` is your "where am I?" command. Use it anytime you need orientation!

package/src/templates/CLAUDE.md.template

@@ -12,16 +12,17 @@ This project uses **SpecWeave** - a specification-first AI development framework
 
 SpecWeave uses **EXPLICIT SLASH COMMANDS** - no auto-activation, no proactive detection.
 
-**How to use**:
-1. ✅ **Use `/pi "feature description"`** to create a new increment (Plan Product Increment)
-2. ✅ **Use `/si 0001`** to start working on an increment
-3. ✅ **Use `/done 0001`** to close an increment
-4. ✅ **Regular conversation** for implementation after planning
-
-**Why slash commands?**
-- Auto-activation doesn't work reliably in Claude Code
-- Explicit commands ensure SpecWeave ALWAYS activates when you want it
-- Short aliases (`/pi`, `/si`, `/done`) save keystrokes
+**Smart Workflow** (Natural & Efficient):
+1. ✅ **`/inc "feature description"`** - Plan increment (PM-led, auto-closes previous if ready)
+2. ✅ **`/build`** - Execute tasks (smart resume, hooks after EVERY task)
+3. ✅ **`/progress`** - Check status (task %, PM gates, next action)
+4. ✅ **Repeat**: `/inc "next"` → auto-closes previous if done
+
+**Why smart workflow?**
+- No manual tracking (`/build` auto-resumes from next incomplete task)
+- No manual closure (`/inc` suggests options if previous incomplete)
+- Check progress anytime (`/progress`)
+- Natural flow: finish → start next
 
 **See**: Full command list below in "Quick Commands" section