specweave 0.1.7 → 0.1.9

package/src/commands/inc.md

@@ -0,0 +1,85 @@
+---
+name: inc
+description: Shorthand for /increment - Plan new Product Increment (PM-led process)
+---
+
+# Plan Product Increment (Quick Alias)
+
+**⚡ Quick Alias**: This is a shorthand for `/increment`.
+
+This is the **most frequently used command** in SpecWeave's append-only increment workflow. Every new feature starts here.
+
+---
+
+## Why This Alias Exists
+
+In an append-only increment workflow:
+- `/increment` is your starting point for ALL new work
+- You'll use it dozens/hundreds of times
+- Short alias saves time and mental overhead
+- Other commands are used less frequently (no aliases needed)
+
+---
+
+## Usage
+
+```bash
+/inc "feature description"
+```
+
+**Examples**:
+```bash
+/inc "User authentication with JWT"
+/inc "Payment processing with Stripe"
+/inc "Real-time notifications"
+```
+
+---
+
+## What This Does
+
+Runs the full `/increment` command, which:
+
+1. **Detects tech stack** (TypeScript, Python, Go, etc.)
+2. **PM-led planning**:
+   - Market research
+   - Create spec.md (WHAT & WHY)
+   - Create plan.md (HOW)
+   - **Auto-generate tasks.md** from plan
+   - Create tests.md (test strategy)
+3. **Strategic agent review**:
+   - Architect designs system
+   - Security reviews threats
+   - QA defines test strategy
+   - DevOps plans infrastructure
+4. **User review checkpoint**
+5. **Ready to build**: `/build 0001`
+
+---
+
+## Typical Workflow
+
+```bash
+# 1. Plan increment (most common command - use alias!)
+/inc "User authentication"
+
+# 2. Review generated docs
+#    spec.md, plan.md, tasks.md, tests.md
+
+# 3. Build it
+/build 0001
+
+# 4. Validate quality (optional)
+/validate 0001 --quality
+
+# 5. Close when done
+/done 0001
+```
+
+---
+
+**💡 Pro Tip**: `/inc` is the ONLY aliased command. Use full names for others (`/build`, `/validate`, `/done`) to keep the workflow clear and explicit.
+
+---
+
+For complete documentation, see `/increment`.

package/src/commands/increment.md

@@ -0,0 +1,316 @@
+---
+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.
+---
+
+# Plan Product 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:
+
+### 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
+
+   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
+     - `requirements.txt` or `pyproject.toml` → Python
+     - `go.mod` → Go
+     - `Cargo.toml` → Rust
+     - `pom.xml` or `build.gradle` → Java
+     - `*.csproj` → C#/.NET
+   - Detect framework (NextJS, Django, FastAPI, Spring Boot, etc.)
+   - If detection fails, ask user: "What language/framework are you using?"
+   - Store detected tech stack for later use
+
+### 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
+   - Business value
+   - User stories with acceptance tests
+   - Functional requirements
+   - Out of scope
+   - Success criteria
+   - Dependencies
+
+### 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
+
+       Detected tech stack:
+       - Language: {detected-language} (e.g., Python, TypeScript, Go, Java)
+       - Framework: {detected-framework} (e.g., Django, FastAPI, NextJS, Spring Boot)
+       - Database: {specified-database} (e.g., PostgreSQL, MySQL, MongoDB)
+       - Platform: {specified-platform} (e.g., AWS, Hetzner, Vercel, self-hosted)
+
+       Location: .specweave/increments/0003-user-authentication/
+
+       📋 Files created:
+       - spec.md (6 user stories, 15 requirements)
+       - tasks.md (42 implementation tasks using {framework} patterns)
+       - pm-analysis.md (product strategy)
+       - architecture.md (system design for {framework})
+       - infrastructure.md ({platform} deployment)
+       - security.md ({framework}-specific security)
+       - test-strategy.md (E2E tests for {framework})
+
+       ⏱️  Estimated effort: 3-4 weeks
+
+       Next steps:
+       1. Review docs: /review-docs
+       2. Start implementation: Begin with Task T001 in tasks.md
+       3. Sync to GitHub: /sync-github
+    ```
+
+## Frontmatter Format (spec.md):
+
+**IMPORTANT**: Tech stack is DETECTED from `.specweave/config.yaml` or project files, NOT hardcoded!
+
+```yaml
+---
+increment: 003-user-authentication
+title: "User Authentication System"
+priority: P1
+status: planned
+created: 2025-10-26
+dependencies: []
+structure: user-stories
+
+# Tech stack is DETECTED, not hardcoded
+tech_stack:
+  detected_from: ".specweave/config.yaml"  # or "package.json", "requirements.txt", etc.
+  language: "{detected-language}"          # e.g., "typescript", "python", "go", "java", "rust"
+  framework: "{detected-framework}"        # e.g., "nextjs", "django", "fastapi", "spring-boot", "gin"
+  database: "{specified-database}"         # e.g., "postgresql", "mysql", "mongodb", "sqlite"
+  orm: "{detected-orm}"                    # e.g., "prisma", "django-orm", "sqlalchemy", "hibernate"
+
+# Platform is SPECIFIED by user or detected from config
+platform: "{specified-platform}"           # e.g., "hetzner", "aws", "vercel", "self-hosted"
+estimated_cost: "{calculated-based-on-platform}"
+---
+```
+
+**Example for TypeScript/NextJS project**:
+```yaml
+tech_stack:
+  detected_from: "package.json"
+  language: "typescript"
+  framework: "nextjs"
+  database: "postgresql"
+  orm: "prisma"
+platform: "vercel"
+estimated_cost: "$20/month"
+```
+
+**Example for Python/Django project**:
+```yaml
+tech_stack:
+  detected_from: "requirements.txt"
+  language: "python"
+  framework: "django"
+  database: "postgresql"
+  orm: "django-orm"
+platform: "hetzner"
+estimated_cost: "$12/month"
+```
+
+**Example for Go/Gin project**:
+```yaml
+tech_stack:
+  detected_from: "go.mod"
+  language: "go"
+  framework: "gin"
+  database: "postgresql"
+  orm: "gorm"
+platform: "aws"
+estimated_cost: "$25/month"
+```
+
+## Frontmatter Format (tasks.md):
+
+```yaml
+---
+increment: 003-event-booking-saas
+status: planned
+dependencies:
+  - 001-skills-framework
+  - 002-role-based-agents
+phases:
+  - infrastructure
+  - backend
+  - frontend
+  - testing
+  - deployment
+estimated_tasks: 42
+estimated_weeks: 3-4
+---
+```
+
+## Autonomous Mode (Advanced):
+
+If user says "autonomous mode" or "full automation":
+1. Run all strategic agents
+2. Create increment
+3. **Start implementation immediately** (with permission)
+4. Ask clarification questions only when critical
+5. Suggest doc updates when needed
+6. Complete full implementation autonomously
+
+## Error Handling:
+
+- If `.specweave/` not found: "Error: Not a SpecWeave project. Run /create-project first."
+- If user description too vague: Ask more clarifying questions
+- If strategic agents not available: "Warning: Some agents missing. Continue with basic spec?"
+
+---
+
+**Important**: This is the main entry point for creating new work in SpecWeave.

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/commands/{validate-increment.md → validate.md}

@@ -1,5 +1,5 @@
 ---
-name: validate-increment
+name: validate
 description: Validate SpecWeave increment with rule-based checks and optional AI quality assessment
 ---
 

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