specweave 0.1.5 → 0.1.7

package/SPECWEAVE.md

@@ -13,46 +13,58 @@ This file contains quick reference for developing with SpecWeave:
 
 ---
 
-## SpecWeave Auto-Routing (CRITICAL)
+## Using SpecWeave with Slash Commands (CRITICAL)
 
-**MANDATORY BEHAVIOR**: This project has SpecWeave installed (`.specweave/` directory exists).
+**IMPORTANT**: SpecWeave uses **EXPLICIT SLASH COMMANDS** - no auto-activation, no proactive detection!
 
-### Auto-Detection & Routing Rules
+### How SpecWeave Works
 
-1. **ALWAYS check for SpecWeave FIRST** before responding to ANY user request
-2. **ROUTE ALL development-related questions** through `specweave-detector` skill
-3. **EVEN GENERIC questions** may need SpecWeave context (e.g., "Analyze BTC/USD" → suggest creating trading analysis feature)
+SpecWeave follows the **spec-kit approach**: You MUST use slash commands explicitly.
 
-### Detection Logic
+**To use SpecWeave**: Type a slash command (e.g., `/pi "Feature description"`)
 
-```javascript
-if (directoryExists('.specweave/config.yaml')) {
-  // SpecWeave is installed
-  // Route through specweave-detector for ALL development requests
-  activateSpecWeaveMode();
-}
-```
+### Quick Command Reference
+
+| Alias | Full Command | Purpose | Example |
+|-------|--------------|---------|---------|
+| `/init` | `/create-project` | Initialize SpecWeave project | `/init my-saas` |
+| `/pi` | `/create-increment` | **Plan Product Increment** | `/pi "User auth"` |
+| `/si` | `/start-increment` | Start working on increment | `/si 0001` |
+| `/at` | `/add-tasks` | Add tasks to increment | `/at 0001 "Add tests"` |
+| `/vi` | `/validate-increment` | Validate increment quality | `/vi 0001 --quality` |
+| `/done` | `/close-increment` | Close increment | `/done 0001` |
+| `/ls` | `/list-increments` | List all increments | `/ls` |
+
+**Why Slash Commands?**
+- ✅ **100% reliable** - Always works, no guessing
+- ✅ **Clear intent** - You know exactly when SpecWeave is active
+- ✅ **Fast** - Short aliases like `/pi` save keystrokes
+- ✅ **Memorable** - Domain-specific names (PI = Product Increment from Agile/SAFe)
+
+### Typical Workflow
+
+```bash
+# 1. Initialize project
+npx specweave init my-saas
+
+# 2. Plan your first increment (use slash command!)
+/pi "User authentication with JWT and RBAC"
 
-### Routing Examples
+# 3. Validate
+/vi 0001 --quality
 
-| User Request | Detection | Action |
-|-------------|-----------|--------|
-| "Create authentication" | Development request | ✅ Route to `specweave-detector` → `increment-planner` |
-| "Analyze BTC/USD prices" | Could be feature request | ✅ Route to `specweave-detector` → Suggest: "Create BTC analysis feature?" |
-| "Add payment processing" | Development request | ✅ Route to `specweave-detector` → `increment-planner` |
-| "Fix bug in login" | Development request | ✅ Route to `specweave-detector` → Load context → Implement |
-| "What's for lunch?" | Non-development | ❌ Respond normally (out of domain) |
+# 4. Start working
+/si 0001
 
-### Activation Behavior
+# 5. Implement (regular conversation, no slash commands needed here)
+User: "Let's implement the backend API"
+Claude: [implements based on plan.md and tasks.md]
 
-**When SpecWeave is detected**:
-- ✅ Show indicator: `🔷 SpecWeave Active`
-- ✅ Route development requests automatically
-- ✅ Load context via `context-loader` when needed
-- ✅ Use appropriate agents (PM, Architect, DevOps, etc.)
-- ✅ Adapt to detected tech stack (TypeScript, Python, Go, etc.)
+# 6. Close when done
+/done 0001
+```
 
-**Rule**: When in doubt, route through SpecWeave. Let `specweave-detector` decide if it's a valid development request.
+**Remember**: Type `/pi` first, THEN implement! Otherwise you lose all SpecWeave benefits (specs, architecture, test strategy).
 
 ---
 
@@ -177,23 +189,29 @@ npx specweave list --installed      # See what's installed
 
 ---
 
-## Quick Reference: Slash Commands
-
-| Command | Purpose | Example |
-|---------|---------|---------|
-| `/create-project` | Bootstrap new SpecWeave project | `/create-project --type python` |
-| `/create-increment` | Create new feature/increment | `/create-increment "user auth"` |
-| `/start-increment` | Start working on an increment | `/start-increment 0001` |
-| `/add-tasks` | Add tasks to existing increment | `/add-tasks 0001 "implement login"` |
-| `/validate-increment` | Validate with rule-based + optional AI quality | `/validate-increment 0001 --quality` |
-| `/close-increment` | Close increment with leftover transfer | `/close-increment 0001` |
-| `/list-increments` | List all increments with status | `/list-increments` |
-| `/review-docs` | Review strategic docs vs code | `/review-docs --increment=0003` |
-| `/generate-docs` | Generate documentation site | `/generate-docs` |
-| `/sync-github` | Sync increment to GitHub issues | `/sync-github` |
+## Quick Reference: Slash Commands (MUST USE!)
+
+**CRITICAL**: SpecWeave uses **EXPLICIT SLASH COMMANDS** - type them to activate the framework!
+
+| Command | Alias | Purpose | Example |
+|---------|-------|---------|---------|
+| `/create-project` | `/init` | Bootstrap new SpecWeave project | `/init my-saas --type python` |
+| `/create-increment` | `/pi` | **Plan Product Increment** (create new feature) | `/pi "user authentication"` |
+| `/start-increment` | `/si` | Start working on an increment | `/si 0001` |
+| `/add-tasks` | `/at` | Add tasks to existing increment | `/at 0001 "implement login"` |
+| `/validate-increment` | `/vi` | Validate with rule-based + optional AI quality | `/vi 0001 --quality` |
+| `/close-increment` | `/done` | Close increment with leftover transfer | `/done 0001` |
+| `/list-increments` | `/ls` | List all increments with status | `/ls --status=in-progress` |
+| `/review-docs` | - | Review strategic docs vs code | `/review-docs --increment=0003` |
+| `/generate-docs` | - | Generate documentation site | `/generate-docs` |
+| `/sync-github` | - | Sync increment to GitHub issues | `/sync-github` |
 
 **All commands are framework-agnostic** (adapt to detected tech stack)
 
+**💡 Pro Tip**: Use short aliases (`/pi`, `/vi`, `/si`, `/done`, `/ls`, `/at`, `/init`) for speed during active development!
+- **PI** = Product Increment (standard Agile terminology)
+- **Why explicit?** Auto-activation doesn't work reliably - slash commands ensure SpecWeave ALWAYS activates
+
 **See**: [Command Reference](.claude/commands/) for all available commands
 
 ---
@@ -227,8 +245,8 @@ npx specweave list --installed      # See what's installed
 
 | Skill | Purpose | Activates When |
 |-------|---------|----------------|
-| `specweave-detector` | Auto-detect SpecWeave projects | Any request in SpecWeave project |
-| `increment-planner` | Plan features with context | Creating/planning features |
+| `specweave-detector` | Slash command documentation | User asks about SpecWeave commands |
+| `increment-planner` | Plan features with context | `/pi` or `/create-increment` command |
 | `skill-router` | Route to appropriate skills | Ambiguous requests |
 | `context-loader` | Load context selectively | Working on increments |
 | `diagrams-generator` | Coordinate diagram creation | "create diagram", "draw diagram", C4, sequence, ER |
@@ -284,11 +302,17 @@ backlog → planned → in-progress → completed → closed
 
 **Naming Convention**: 4-digit format (0001-9999), e.g., `0001-feature-name`, `0042-user-auth`, `0123-payment-flow`
 
-**Commands**:
+**Commands** (MUST USE SLASH COMMANDS!):
 ```bash
-/create-increment "feature name"      # Create new increment (auto-numbered, e.g., 0003-feature-name)
-/add-tasks 0001 "task description"    # Add tasks to existing
-/close-increment 0001                 # Close with leftover transfer
+# Use short aliases (recommended)
+/pi "feature name"                    # Create new increment (auto-numbered, e.g., 0003-feature-name)
+/at 0001 "task description"           # Add tasks to existing
+/done 0001                             # Close with leftover transfer
+
+# Or full commands
+/create-increment "feature name"      # Same as /pi
+/add-tasks 0001 "task description"    # Same as /at
+/close-increment 0001                 # Same as /done
 ```
 
 **See**: [Increment Lifecycle Guide](.specweave/docs/internal/delivery/guides/increment-lifecycle.md) for complete lifecycle management
@@ -659,8 +683,27 @@ Attempt 2/3: Refining with feedback...
 
 ---
 
-**Quick Start**: Run `/create-project` to initialize a new SpecWeave project
+**Quick Start**:
+
+**CRITICAL**: SpecWeave uses **EXPLICIT SLASH COMMANDS** - type `/pi` to activate!
+
+```bash
+# Initialize project
+npx specweave init my-project
+
+# Create your first feature (use slash command!)
+/pi "feature description"
+
+# Typical workflow
+1. /pi "feature" → SpecWeave creates specs
+2. Regular conversation → Claude implements code
+3. /done 0001 → Close increment
+```
+
+**Remember**: Type `/pi` first, THEN implement! Otherwise you lose all SpecWeave benefits (specs, architecture, test strategy).
+
+**Need help?**: Type `/pi` to see examples, or ask about specific workflows.
 
-**Need help?**: Ask Claude to load the relevant guide from `.specweave/docs/internal/delivery/guides/`
+**SpecWeave Documentation**: https://spec-weave.com
 
 **Last Updated**: Auto-updated via `post-task-completion` hook

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "specweave",
-  "version": "0.1.5",
+  "version": "0.1.7",
   "description": "Spec-Driven Development framework with AI-powered autonomous agents for building SaaS applications",
   "main": "dist/index.js",
   "bin": {

package/src/commands/README.md

@@ -0,0 +1,173 @@
+# SpecWeave Slash Commands
+
+This directory contains all slash commands for SpecWeave, including both full commands and short aliases.
+
+## Command Aliases
+
+SpecWeave provides short aliases for frequently used commands to speed up your workflow:
+
+| Full Command | Alias | Description |
+|--------------|-------|-------------|
+| `/create-project` | `/init` | Initialize new SpecWeave project |
+| `/create-increment` | `/pi` | Plan Product Increment (create new increment) |
+| `/start-increment` | `/si` | Start working on increment |
+| `/add-tasks` | `/at` | Add tasks to increment |
+| `/validate-increment` | `/vi` | Validate increment quality |
+| `/close-increment` | `/done` | Close completed increment |
+| `/list-increments` | `/ls` | List all increments |
+
+## Usage
+
+### Full Commands (Explicit)
+
+Use full commands when:
+- ✅ Writing scripts or automation
+- ✅ Documentation and tutorials
+- ✅ Sharing commands with team members
+- ✅ Clarity is more important than speed
+
+**Example**:
+```bash
+/create-increment "User authentication with OAuth"
+/validate-increment 0001 --quality
+/close-increment 0001
+```
+
+### Aliases (Quick)
+
+Use aliases when:
+- ✅ Active development (speed matters)
+- ✅ Iterative workflow (creating/validating frequently)
+- ✅ Command-line muscle memory
+- ✅ Personal productivity
+
+**Example**:
+```bash
+/ci "User authentication with OAuth"
+/vi 0001 --quality
+/done 0001
+```
+
+## Typical Workflow
+
+**Using aliases for speed**:
+```bash
+# 1. Initialize project
+/init my-saas
+
+# 2. Plan Product Increment (PI = Product Increment in Agile)
+/pi "User authentication"
+
+# 3. Start working
+/si 0001
+
+# 4. Add tasks as needed
+/at 0001 "Implement login endpoint"
+/at 0001 "Add password validation"
+
+# 5. Check progress
+/ls --status=in-progress
+
+# 6. Validate before closing
+/vi 0001 --quality
+
+# 7. Close when done
+/done 0001
+```
+
+**Using full commands for clarity**:
+```bash
+# Same workflow with explicit commands
+/create-project my-saas
+/create-increment "User authentication"
+/start-increment 0001
+/add-tasks 0001 "Implement login endpoint"
+/list-increments --status=in-progress
+/validate-increment 0001 --quality
+/close-increment 0001
+```
+
+## All Available Commands
+
+### Core Workflow Commands
+
+| Command | Alias | Description |
+|---------|-------|-------------|
+| `/create-project` | `/init` | Bootstrap new SpecWeave project with auto-detection |
+| `/create-increment` | `/pi` | Plan Product Increment with PM/Architect/QA planning |
+| `/start-increment` | `/si` | Start working on an increment (load context, create branch) |
+| `/add-tasks` | `/at` | Add tasks to existing increment |
+| `/validate-increment` | `/vi` | Validate increment (120 rules + optional LLM quality judge) |
+| `/close-increment` | `/done` | Close increment with leftover task handling |
+| `/list-increments` | `/ls` | List all increments with status and progress |
+
+### Documentation & Review Commands
+
+| Command | Alias | Description |
+|---------|-------|-------------|
+| `/review-docs` | - | Review strategic docs vs implementation |
+| `/generate-docs` | - | Generate documentation site (Docusaurus/MkDocs) |
+
+### Integration Commands
+
+| Command | Alias | Description |
+|---------|-------|-------------|
+| `/sync-github` | - | Sync increment to GitHub issues with subtasks |
+
+## Alias Design Philosophy
+
+**Why separate files instead of symlinks?**
+
+1. **Cross-platform compatibility** - Works on Windows, macOS, Linux, cloud IDEs
+2. **Clear documentation** - Each alias explains what it references
+3. **Consistent user experience** - Both commands work identically
+4. **Easy maintenance** - Update main command, aliases stay in sync via reference
+
+**Trade-off**: Slight content duplication, but improved UX and compatibility.
+
+## Creating Custom Aliases
+
+You can create your own project-specific aliases:
+
+**1. Create `.claude/commands/custom-alias.md`**:
+```markdown
+---
+description: Your custom command description
+---
+
+# Custom Alias
+
+This is a shorthand for `/some-long-command`.
+
+<!-- Paste full command content or reference it -->
+```
+
+**2. Use it**:
+```bash
+/custom-alias
+```
+
+## Installation
+
+Aliases are automatically installed when you:
+- Run `specweave init` (new projects)
+- Install SpecWeave as dependency (`npm install specweave --save-dev`)
+
+For manual installation:
+```bash
+npm run install:commands
+```
+
+## Documentation
+
+- **Command Reference**: See `.claude/commands/` for all available commands
+- **CLAUDE.md**: Quick reference table with all commands and aliases
+- **Official Docs**: https://spec-weave.com/docs/commands
+
+---
+
+**💡 Pro Tip**: Learn the aliases - they'll save you hundreds of keystrokes per day!
+
+**Most used**: `/pi`, `/si`, `/vi`, `/done`, `/ls`
+
+**PI** = Product Increment (standard Agile/Scrum terminology)

package/src/commands/at.md

@@ -0,0 +1,114 @@
+---
+description: 🔥 Shorthand for /add-tasks - Add tasks to increment (Alias)
+---
+
+# Add Tasks (Short Alias)
+
+**⚡ Quick Alias**: This is a shorthand command for `/add-tasks`.
+
+Use this when you want to quickly add tasks to an increment without typing the full command name.
+
+---
+
+## Full Command
+
+For complete documentation, see `/add-tasks`.
+
+This alias provides the exact same functionality as the full command.
+
+---
+
+## Usage
+
+```bash
+/at <increment-id> <task-description>
+```
+
+**Examples**:
+```bash
+/at 0001 "Implement login endpoint"
+/at 0001 "Add password validation"
+/at 0001 "Write E2E tests for auth flow"
+```
+
+---
+
+## What This Does
+
+1. **Analyzes task** against spec/plan
+2. **Determines priority** (P1, P2, P3)
+3. **Estimates effort** (based on complexity)
+4. **Identifies dependencies** (from existing tasks)
+5. **Adds to tasks.md** with proper formatting
+6. **Updates progress** percentage
+
+---
+
+## Task Format
+
+Tasks are added with:
+- ✅ **Task ID** (auto-numbered: T001, T002, ...)
+- ✅ **Description** (clear, actionable)
+- ✅ **Priority** (P1/P2/P3)
+- ✅ **Estimated time** (based on analysis)
+- ✅ **Dependencies** (if any)
+- ✅ **Status** (Pending by default)
+
+**Example Output**:
+```markdown
+### T012: Implement login endpoint
+**Priority**: P1
+**Estimated**: 2 hours
+**Depends on**: T008
+**Status**: [ ] Pending
+
+**Implementation**:
+- Create POST /api/auth/login endpoint
+- Validate email and password
+- Return JWT token on success
+- Handle rate limiting
+```
+
+---
+
+## Bulk Add
+
+You can add multiple tasks by calling the command multiple times or providing a list:
+
+```bash
+/at 0001 "Task 1"
+/at 0001 "Task 2"
+/at 0001 "Task 3"
+```
+
+---
+
+## When to Add Tasks
+
+**During planning**:
+- Breaking down large features
+- After spec/plan review
+
+**During implementation**:
+- Discovered new requirements
+- Technical debt identified
+- Bug fixes needed
+
+**After review**:
+- Feedback from code review
+- QA findings
+- Security audit results
+
+---
+
+## Other Useful Aliases
+
+- `/ci` - Create increment (shorthand for `/create-increment`)
+- `/si` - Start increment (shorthand for `/start-increment`)
+- `/vi` - Validate increment (shorthand for `/validate-increment`)
+- `/done` - Close increment (shorthand for `/close-increment`)
+- `/ls` - List increments (shorthand for `/list-increments`)
+
+---
+
+**💡 Tip**: Add tasks as you discover them - don't wait until sprint planning!

package/src/commands/done.md

@@ -0,0 +1,103 @@
+---
+description: 🔥 Shorthand for /close-increment - Close completed increment (Alias)
+---
+
+# Close Increment (Short Alias)
+
+**⚡ Quick Alias**: This is a shorthand command for `/close-increment`.
+
+Use this when you want to quickly close an increment without typing the full command name.
+
+---
+
+## Full Command
+
+For complete documentation, see `/close-increment`.
+
+This alias provides the exact same functionality as the full command.
+
+---
+
+## Usage
+
+```bash
+/done <increment-id>
+```
+
+**Examples**:
+```bash
+/done 0001
+/done 0042
+```
+
+---
+
+## What This Does
+
+1. **Validates completion**:
+   - ✅ All P1 tasks completed
+   - ✅ Tests passing
+   - ✅ Documentation updated
+   - ⚠️ Warns if incomplete
+
+2. **Handles leftover tasks**:
+   - Prompts to transfer incomplete tasks to new increment
+   - OR mark as deferred/cancelled
+   - Ensures no work is lost
+
+3. **Updates status** to `closed` in `tasks.md`
+
+4. **Archives increment** (if configured)
+
+5. **Suggests next steps**:
+   - Merge PR (if using git workflow)
+   - Deploy (if using CI/CD)
+   - Create release notes
+
+---
+
+## Before Closing Checklist
+
+**Required**:
+- [ ] All P1 tasks completed
+- [ ] Tests passing
+- [ ] Code reviewed
+- [ ] Documentation updated
+
+**Optional** (based on project):
+- [ ] Performance validated
+- [ ] Security reviewed
+- [ ] Accessibility tested
+- [ ] E2E tests passing
+
+---
+
+## Leftover Task Handling
+
+If you have incomplete tasks, you'll be prompted:
+
+```
+⚠️ Incomplete Tasks Found: 3
+
+Options:
+1. Transfer to new increment (recommended)
+2. Mark as deferred (with reason)
+3. Cancel tasks (not recommended)
+
+What would you like to do?
+```
+
+**Best Practice**: Transfer to new increment to maintain continuity.
+
+---
+
+## Other Useful Aliases
+
+- `/ci` - Create increment (shorthand for `/create-increment`)
+- `/si` - Start increment (shorthand for `/start-increment`)
+- `/vi` - Validate increment (shorthand for `/validate-increment`)
+- `/ls` - List increments (shorthand for `/list-increments`)
+
+---
+
+**💡 Tip**: Always run `/vi --quality` before `/done` to ensure quality.