specweave 0.1.6 → 0.1.7

package/README.md

@@ -101,6 +101,8 @@ specweave --help                   # Show help
 
 ## 🚀 Quick Example
 
+**CRITICAL**: SpecWeave uses **EXPLICIT SLASH COMMANDS** - type them to activate the framework!
+
 ```bash
 # Initialize project - ALL components pre-installed!
 npx specweave init my-app
@@ -111,11 +113,11 @@ cd my-app
 # ✅ 35+ skills in .claude/skills/
 # ✅ 10 slash commands in .claude/commands/
 
-# Open Claude Code and start building:
+# Open Claude Code and use slash commands:
 
-User: "Create Next.js authentication with email and OAuth"
+User: /pi "Next.js authentication with email and OAuth"
     ↓
-SpecWeave: 🔷 SpecWeave Active
+SpecWeave: 🔷 SpecWeave Active (/create-increment)
 
            🚀 Creating increment 0001-user-authentication...
            📝 Using nextjs skill (already installed!)
@@ -125,34 +127,39 @@ SpecWeave: 🔷 SpecWeave Active
 ✅ Increment created: .specweave/increments/0001-user-authentication/
 ✅ Files: spec.md, plan.md, tasks.md, tests.md
 
-User: "Create C4 context diagram for authentication"
+User: "Create C4 context diagram for authentication"  # Regular conversation for implementation
     ↓
 SpecWeave: 🎨 Using diagrams-generator skill
            🤖 Coordinating with diagrams-architect agent
 
 ✅ Diagram saved: .specweave/docs/internal/architecture/diagrams/auth.c4-context.mmd
 
-User: "Implement authentication"
+User: "Implement authentication based on plan.md"  # Regular conversation
     ↓
-SpecWeave: 🤖 Orchestrating: PM → Architect → Backend → QA → Docs
+SpecWeave: 🤖 Implementing based on specifications
 
 ✅ Code: src/auth/
 ✅ Tests: tests/auth/
 ✅ Docs: Updated automatically
+
+User: /done 0001  # Close increment with slash command
+✅ Increment 0001 closed successfully
 ```
 
 **How it works**:
 1. `specweave init` → ALL components pre-installed (10 agents + 35+ skills)
-2. `.specweave/` detected → `specweave-detector` activates automatically
-3. User request parsed → routed to appropriate pre-installed skills
-4. Skills coordinate agents → artifacts generated
+2. **Use `/pi "feature"`** → Creates increment with specs (spec.md, plan.md, tasks.md, tests.md)
+3. **Regular conversation** → Implement code based on specifications
+4. **Use `/done 0001`** → Close increment when complete
 5. 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.
+
 ---
 
 ## 🤖 Agents (10 Total - All Pre-Installed!)
 
-SpecWeave includes **10 specialized AI agents** that activate automatically based on your request:
+SpecWeave includes **10 specialized AI agents** that work with slash commands and during implementation:
 
 | Agent | Role | When It Activates |
 |-------|------|-------------------|
@@ -173,11 +180,11 @@ SpecWeave includes **10 specialized AI agents** that activate automatically base
 
 ## 🎯 Skills (35+ Total - All Pre-Installed!)
 
-SpecWeave includes **35+ AI skills** that activate automatically based on your request:
+SpecWeave includes **35+ AI skills** that work with slash commands:
 
 ### Core Framework Skills
-- **specweave-detector** - Auto-detect SpecWeave projects
-- **increment-planner** - Plan features and create specifications
+- **specweave-detector** - Slash command documentation
+- **increment-planner** - Plan features via `/pi` command
 - **skill-router** - Route requests to appropriate skills
 - **context-loader** - Load relevant specifications
 - **role-orchestrator** - Coordinate multiple agents
@@ -281,22 +288,30 @@ specweave/
 
 ### For Greenfield Projects
 
+**IMPORTANT**: Use slash commands to activate SpecWeave!
+
 ```bash
 # 1. Create specifications (optional: comprehensive upfront or incremental)
 # Option A: Comprehensive (Enterprise) - 500-600+ pages upfront
 # Option B: Incremental (Startup) - Build as you go
 
-# 2. Create increment
-/create-increment "user authentication"
+# 2. Create increment with slash command
+/pi "user authentication"
+# Short alias for /create-increment
+# SpecWeave orchestrates: PM → Architect → QA agents
+# Creates: spec.md, plan.md, tasks.md, tests.md
 
-# 3. Implement with auto-role routing
-"Implement user authentication"
-# SpecWeave orchestrates: PM → Architect → Backend → QA → Docs
+# 3. Implement with regular conversation (no slash command needed)
+"Implement user authentication based on plan.md"
+# Claude implements based on specifications
 
-# 4. Generate diagrams
+# 4. Generate diagrams (regular conversation)
 "Create C4 context diagram for authentication"
 
-# 5. Sync with tools (optional)
+# 5. Close increment with slash command
+/done 0001
+
+# 6. Sync with tools (optional)
 /sync-github  # Sync to GitHub issues
 ```
 

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)
 
-### Routing Examples
+### Typical Workflow
+
+```bash
+# 1. Initialize project
+npx specweave init my-saas
 
-| 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) |
+# 2. Plan your first increment (use slash command!)
+/pi "User authentication with JWT and RBAC"
 
-### Activation Behavior
+# 3. Validate
+/vi 0001 --quality
 
-**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.)
+# 4. Start working
+/si 0001
 
-**Rule**: When in doubt, route through SpecWeave. Let `specweave-detector` decide if it's a valid development request.
+# 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]
+
+# 6. Close when done
+/done 0001
+```
+
+**Remember**: Type `/pi` first, THEN implement! Otherwise you lose all SpecWeave benefits (specs, architecture, test strategy).
 
 ---
 
@@ -177,12 +189,14 @@ npx specweave list --installed      # See what's installed
 
 ---
 
-## Quick Reference: Slash Commands
+## 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` | `/ci` | Create new feature/increment | `/ci "user authentication"` |
+| `/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` |
@@ -194,7 +208,9 @@ npx specweave list --installed      # See what's installed
 
 **All commands are framework-agnostic** (adapt to detected tech stack)
 
-**💡 Pro Tip**: Use short aliases (`/ci`, `/vi`, `/si`, `/done`, `/ls`, `/at`, `/init`) for speed during active development!
+**💡 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
 
@@ -229,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 |
@@ -286,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
@@ -661,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.6",
+  "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

@@ -9,7 +9,7 @@ SpecWeave provides short aliases for frequently used commands to speed up your w
 | Full Command | Alias | Description |
 |--------------|-------|-------------|
 | `/create-project` | `/init` | Initialize new SpecWeave project |
-| `/create-increment` | `/ci` | Create new increment |
+| `/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 |
@@ -55,8 +55,8 @@ Use aliases when:
 # 1. Initialize project
 /init my-saas
 
-# 2. Create first increment
-/ci "User authentication"
+# 2. Plan Product Increment (PI = Product Increment in Agile)
+/pi "User authentication"
 
 # 3. Start working
 /si 0001
@@ -94,7 +94,7 @@ Use aliases when:
 | Command | Alias | Description |
 |---------|-------|-------------|
 | `/create-project` | `/init` | Bootstrap new SpecWeave project with auto-detection |
-| `/create-increment` | `/ci` | Create new increment with PM/Architect/QA planning |
+| `/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) |
@@ -168,4 +168,6 @@ npm run install:commands
 
 **💡 Pro Tip**: Learn the aliases - they'll save you hundreds of keystrokes per day!
 
-**Most used**: `/ci`, `/si`, `/vi`, `/done`, `/ls`
+**Most used**: `/pi`, `/si`, `/vi`, `/done`, `/ls`
+
+**PI** = Product Increment (standard Agile/Scrum terminology)

package/src/commands/{ci.md → pi.md}

@@ -1,11 +1,13 @@
 ---
-description: 🔥 Shorthand for /create-increment - Create new increment (Alias)
+description: 🔥 Shorthand for /create-increment - Plan Product Increment (Alias)
 ---
 
-# Create Increment (Short Alias)
+# Plan Product Increment (Short Alias)
 
 **⚡ Quick Alias**: This is a shorthand command for `/create-increment`.
 
+**PI = Product Increment** - Standard Agile terminology for a planned unit of work.
+
 Use this when you want to quickly create a new SpecWeave increment without typing the full command name.
 
 ---
@@ -21,14 +23,14 @@ This alias provides the exact same functionality as the full command.
 ## Usage
 
 ```bash
-/ci "Feature name"
+/pi "Feature name"
 ```
 
 **Example**:
 ```bash
-/ci "User authentication"
-/ci "Payment processing"
-/ci "Admin dashboard"
+/pi "User authentication"
+/pi "Payment processing"
+/pi "Admin dashboard"
 ```
 
 ---
@@ -60,4 +62,4 @@ This alias provides the exact same functionality as the full command.
 
 ---
 
-**💡 Tip**: Use `/ci` for speed, `/create-increment` for clarity in scripts.
+**💡 Tip**: Use `/pi` for speed (PI = Product Increment in Agile), `/create-increment` for clarity in scripts.

package/src/skills/specweave-detector/SKILL.md

@@ -1,525 +1,393 @@
 ---
 name: specweave-detector
-description: MANDATORY entry point for SpecWeave framework. Activates when .specweave/ exists OR when user mentions "SpecWeave", "increment", "feature", "/create-increment". All 10 agents and 35+ skills are PRE-INSTALLED during init - no auto-installation needed. Routes requests to increment-planner, skill-router, or appropriate agents. Keywords SpecWeave, spec-driven, increment, feature, spec, plan, task, create feature, build feature, new increment.
-proactive: true
+description: Documentation skill that explains SpecWeave slash commands. SpecWeave uses EXPLICIT slash commands only - no auto-activation! Use /pi (Plan Product Increment) or /create-increment to start. Other commands /si (start), /at (add tasks), /vi (validate), /done (close), /ls (list). All commands listed in .claude/commands/. Keywords slash commands, /pi, /create-increment, /si, /vi, /done, /ls, /init, specweave commands.
 ---
 
-# SpecWeave Detector & Entry Point
+# SpecWeave - Slash Command Reference
 
-This skill is the **MANDATORY entry point** for all SpecWeave operations. When Claude Code detects a `.specweave/config.yaml` file OR user mentions SpecWeave-related keywords, this skill MUST activate and orchestrate the framework.
+**CRITICAL**: SpecWeave uses **EXPLICIT SLASH COMMANDS ONLY** - no auto-activation, no proactive detection, no intent-based routing.
 
-## Purpose
+## How SpecWeave Works
 
-Act as the "factory of agents" that:
-1. **Detects SpecWeave projects automatically** (when .specweave/ exists)
-2. **Parses user requests** and determines intent
-3. **Routes to appropriate skills/agents** (all pre-installed!)
-4. **Orchestrates nested skill calls** for complex operations
-5. **Manages context loading** via context-loader skill
+SpecWeave follows the **spec-kit approach**: You MUST use slash commands explicitly.
 
-## Detection Logic (0.1.5 - Pre-Installation)
+**To use SpecWeave**: Type a slash command (e.g., `/pi "Feature description"`)
 
-```javascript
-// Pseudo-code for detection
-if (fileExists('.specweave/config.yaml')) {
-  // ACTIVATE SPECWEAVE MODE
-  activateSpecWeaveMode();
-  loadConfiguration();
+## Available Slash Commands
 
-  // ALL COMPONENTS ALREADY INSTALLED!
-  // ✅ 10 agents in .claude/agents/
-  // ✅ 35+ skills in .claude/skills/
-  // ✅ 10 commands in .claude/commands/
+### Quick Reference Table
 
-  // NO AUTO-INSTALLATION NEEDED (pre-installed in 0.1.5)
+| Alias | Full Command | Purpose | Example |
+|-------|--------------|---------|---------|
+| `/init` | `/create-project` | Initialize SpecWeave project | `/init my-saas` |
+| `/pi` | `/create-increment` | **Plan Product Increment** | `/pi "User auth"` |
+| `/ci` | `/create-increment` | Alternative to `/pi` | `/ci "Payment"` |
+| `/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` |
 
-  parseUserIntent();
-  routeToSkills();
-}
-```
+### Command Details
 
-## Pre-Installed Components (0.1.5+)
+#### `/pi` or `/create-increment` - Plan Product Increment
 
-**IMPORTANT**: SpecWeave 0.1.5+ uses **pre-installation** instead of auto-installation.
+**Most important command!** Creates a new increment with specifications.
 
-After `specweave init`, ALL components are ready:
-- ✅ **10 agents**: PM, Architect, Security, QA Lead, DevOps, Tech Lead, SRE, Docs Writer, Performance, Diagrams Architect
-- ✅ **35+ skills**: Technology stacks, integrations, utilities
-- ✅ **10 slash commands**: /create-increment, /validate-increment, etc.
+```bash
+# Short form (recommended)
+/pi "User authentication with JWT and RBAC"
 
-**No installation wait time** - components activate immediately!
+# Full form
+/create-increment "User authentication with JWT and RBAC"
+```
 
-### How It Works (0.1.5+)
+**What happens**:
+1. Creates `.specweave/increments/000X-feature-name/` folder
+2. PM agent generates `spec.md` (requirements, user stories)
+3. Architect agent generates `plan.md` (architecture, design)
+4. QA Lead generates `tests.md` (test strategy)
+5. Creates `tasks.md` (implementation checklist)
 
-1. **User makes a request** (e.g., "Create Next.js authentication")
-2. **SpecWeave detector activates** (all components already installed!)
-3. **Analyze user intent**:
-   - "Create" → Route to increment-planner skill
-   - "Next.js" → Will use nextjs skill (already installed)
-   - "authentication" → Will involve security agent (already installed)
-4. **Route to increment-planner**:
-   - Creates increment folder
-   - Generates spec.md, plan.md, tasks.md, tests.md
-   - Coordinates with PM agent → Architect agent
-5. **Implementation ready** - All skills/agents available immediately
+#### `/si` or `/start-increment` - Start Working
 
-### Example User Experience (0.1.5+)
+Marks an increment as "in-progress".
 
-**Example 1: Next.js Authentication**
+```bash
+/si 0001
 ```
-User: "Create Next.js authentication with OAuth"
-
-🔷 SpecWeave Active
 
-🚀 Creating increment 0001-nextjs-authentication...
-   📝 Using nextjs skill (already installed!)
-   🤖 PM agent creating requirements...
-   🏗️  Architect agent designing system...
+#### `/at` or `/add-tasks` - Add Tasks
 
-✅ Increment created: .specweave/increments/0001-nextjs-authentication/
-✅ Files: spec.md, plan.md, tasks.md, tests.md
-```
+Add additional tasks to an increment.
 
-**Example 2: Real Estate Platform**
+```bash
+/at 0001 "Add password reset functionality"
+/at 0001 "Add email verification"
 ```
-User: "Build a real estate listing platform with Node.js/Express"
 
-🔷 SpecWeave Active
+#### `/vi` or `/validate-increment` - Validate Quality
 
-🚀 Creating increment 0001-real-estate-platform...
-   📝 Using nodejs-backend skill (already installed!)
-   🤖 PM agent creating requirements...
-   🏗️  Architect agent designing system...
-   🛡️  Security agent reviewing authentication...
+Run validation checks on an increment.
 
-✅ Increment created with complete specifications
-```
+```bash
+# Rule-based validation only
+/vi 0001
 
-**Example 3: Python FastAPI**
+# With AI quality assessment
+/vi 0001 --quality
 ```
-User: "Create FastAPI backend with PostgreSQL"
 
-🔷 SpecWeave Active
+#### `/done` or `/close-increment` - Close Increment
 
-🚀 Creating increment 0001-fastapi-backend...
-   📝 Using python-backend skill (already installed!)
-   🤖 PM agent creating requirements...
-   🏗️  Architect agent designing system...
+Mark increment as completed.
 
-✅ Increment created: .specweave/increments/0001-fastapi-backend/
+```bash
+/done 0001
 ```
 
-### Benefits of Pre-Installation (0.1.5+)
+#### `/ls` or `/list-increments` - List All
 
-- ✅ **Zero wait time** - all components ready immediately
-- ✅ **No installation confusion** - everything works out of the box
-- ✅ **Predictable** - same components every time
-- ✅ **Simple mental model** - init once, use forever
-- ✅ **Offline-friendly** - all components local after init
+Show all increments with status.
 
-## Auto-Activation
+```bash
+/ls
+```
 
-**Key Feature**: This skill uses Claude Code's `proactive: true` feature to load automatically.
+### Why Slash Commands?
 
-When a user opens a project with `.specweave/` directory:
-1. Claude Code detects the directory
-2. This skill loads proactively (no user action needed)
-3. SpecWeave mode activates silently
-4. User requests are automatically routed to appropriate skills
+**Problem**: Auto-activation doesn't work reliably in Claude Code.
 
-**User Experience**:
-```
-# User doesn't know SpecWeave is active
-User: "I want to add payment processing"
-
-# Behind the scenes:
-# 1. specweave-detector intercepts request
-# 2. Parses request: "add feature" + "payment processing"
-# 3. Routes to: increment-planner skill
-# 4. increment-planner creates Increment 0002
-# 5. Returns result to user
-
-# User sees:
-✅ Increment created: .specweave/increments/0002-payment-processing/
-```
+**Solution**: Explicit slash commands (like spec-kit) ensure SpecWeave ALWAYS activates when you want it.
 
-## Request Parsing & Routing
+**Benefits**:
+- ✅ **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)
 
-### Simple Request (Single Skill)
+## Typical Workflow
 
-| User Says | Request Type | Route To |
-|-----------|--------|----------|
-| "Plan a feature for..." | feature_planning | `increment-planner` |
-| "Load context for..." | context_loading | `context-loader` |
-| "Document this code..." | documentation | `docs-updater` |
-| "Create a spec for..." | specification | `spec-author` |
-| "Design architecture for..." | architecture | `architect` |
-| "Implement feature 001" | development | `developer` |
-| "Test this feature" | testing | `qa-engineer` |
+### 1. Initialize Project
 
-### Complex Request (Multiple Skills)
+```bash
+npx specweave init my-saas
+cd my-saas
+```
 
-**Example**: "Create and implement a new payment feature"
+**Creates**:
+- `.specweave/` - Framework configuration
+- `.claude/agents/` - 10 pre-installed agents
+- `.claude/skills/` - 35+ pre-installed skills
+- `.claude/commands/` - 10 slash commands
+- `CLAUDE.md` - Development guide
 
-**Request Breakdown**:
-1. Create increment → `increment-planner`
-2. Load context → `context-loader`
-3. Implement code → Coordinate with appropriate agents/skills
-4. Generate tests → Use QA Lead agent
-5. Update docs → Use Docs Writer agent
+### 2. Plan Your First Increment
 
-**Execution Flow**:
-```
-User: "Create and implement a new payment feature"
-    ↓
-specweave-detector parses: CREATE + IMPLEMENT + FEATURE + PAYMENT
-    ↓
-Orchestrate nested skills:
-    ↓
-increment-planner: Create .specweave/increments/0003-payment-processing/
-    ↓
-context-loader: Load .specweave/docs/internal/strategy/payments/**
-    ↓
-Implementation: Use nodejs-backend skill + security agent
-    ↓
-Testing: Use QA Lead agent (generate E2E tests)
-    ↓
-Documentation: Update .specweave/docs/internal/architecture/
-    ↓
-Result: "✅ Increment 0003 implemented and documented"
+```bash
+# Use short alias (recommended)
+/pi "User authentication with JWT and RBAC"
 ```
 
-### Ambiguous Request
-
-When request is unclear:
+**Creates**:
 ```
-User: "Help me with the authentication"
-    ↓
-specweave-detector: Ambiguous (help = ?)
-    ↓
-Route to skill-router for clarification
-    ↓
-skill-router asks:
-"What would you like to do with authentication?
-1. Create a specification
-2. Plan implementation
-3. Implement code
-4. Document existing code"
+.specweave/increments/0001-user-authentication/
+├── spec.md           # Requirements (PM agent)
+├── plan.md           # Architecture (Architect agent)
+├── tasks.md          # Implementation steps
+├── tests.md          # Test strategy (QA Lead agent)
+└── context-manifest.yaml  # Context loading config
 ```
 
-## Context Management
+### 3. Validate & Start
 
-### Automatic Context Loading
+```bash
+# Validate quality
+/vi 0001 --quality
 
-When a user is working on an increment:
+# Start working
+/si 0001
+```
 
-```javascript
-// Detect active increment
-const activeIncrement = detectActiveIncrement(); // .specweave/increments/####-xxx/
+### 4. Add More Tasks (As Needed)
 
-if (activeIncrement) {
-  const manifest = loadManifest(`${activeIncrement}/context-manifest.yaml`);
-  const context = await contextLoader.load(manifest);
-  // Context now available for all skills
-}
+```bash
+# As you discover new work
+/at 0001 "Add password reset flow"
+/at 0001 "Add 2FA support"
 ```
 
-### Context Prioritization
+### 5. Close When Done
 
-When multiple contexts are relevant:
+```bash
+/done 0001
+```
 
-1. **Active increment** (in `.specweave/increments/####-xxx/`)
-2. **Current branch** (git branch name features/###-xxx)
-3. **User-specified** context
-4. **Global** context (.specweave/docs/internal/strategy/overview.md, principles.md)
+## Example Sessions
 
-## Skill Orchestration
+### Example 1: Real Estate Platform
 
-### Parallel Execution
+```bash
+# Initialize
+$ npx specweave init real-estate-app
+$ cd real-estate-app
 
-Some skills can run in parallel:
+# Plan increment with slash command
+$ /pi "Real estate listing platform with search, images, admin dashboard. Node.js/Express, PostgreSQL, JWT auth"
 
-```
-User: "Create tests and update documentation"
-    ↓
-Parallel execution:
-├─ qa-engineer: Generate tests
-└─ docs-updater: Update docs
-
-Wait for both to complete
-    ↓
-Result: "✅ Tests generated (15 test cases) and docs updated"
-```
+🔷 SpecWeave Active (/create-increment)
 
-### Sequential Execution
+📝 Using increment-planner skill...
+🤖 PM agent creating requirements...
+🏗️  Architect agent designing system...
+🛡️  Security agent reviewing authentication...
 
-Some skills must run sequentially:
+✅ Increment created: .specweave/increments/0001-real-estate-platform/
+   - spec.md (Requirements & user stories)
+   - plan.md (Architecture & design)
+   - tasks.md (Implementation checklist)
+   - tests.md (Test strategy)
 
-```
-User: "Plan and implement feature 001"
-    ↓
-Sequential execution:
-1. increment-planner: Create plan (MUST complete first)
-2. context-loader: Load relevant specs (uses plan output)
-3. developer: Implement (uses loaded context)
-
-Each step waits for previous to complete
-```
+# Validate
+$ /vi 0001 --quality
+✅ Quality score: 87/100 (GOOD)
 
-### Error Handling
+# Start working
+$ /si 0001
+✅ Increment 0001 status → in-progress
 
-If a skill fails:
+# Implement (regular Claude conversation, no slash commands needed here)
+User: "Let's implement the backend API for listings"
+Claude: [implements based on plan.md and tasks.md]
 
-```
-User: "Implement increment 0005"
-    ↓
-specweave-detector: Route to implementation
-    ↓
-ERROR: Increment 0005 not found
-    ↓
-specweave-detector: Catch error, suggest:
-"Increment 0005 doesn't exist. Would you like to:
-1. Create it first (/create-increment)
-2. List existing increments (/list-increments)
-3. Implement a different increment"
+# Close when done
+$ /done 0001
+✅ Increment 0001 closed successfully
 ```
 
-## Configuration Awareness
+### Example 2: Next.js Authentication
 
-Load and respect `.specweave/config.yaml`:
-
-```yaml
-# .specweave/config.yaml
-principles:
-  auto_role_routing: true        # Enable auto-routing
-  context_precision: true         # Use context manifests
-  routing_accuracy_target: 0.90   # Accuracy threshold
+```bash
+# Short alias for speed
+$ /pi "Next.js authentication with JWT, OAuth, RBAC"
 
-# All components pre-installed in 0.1.5+ (no auto_install setting needed)
-# Agents and skills are in .claude/ folder, ready to use
+🔷 SpecWeave Active (/create-increment)
 
-integrations:
-  github:
-    enabled: true
-    sync_issues: true             # Sync increments ↔ GitHub issues
-  jira:
-    enabled: false
-  ado:
-    enabled: false
-```
+📝 Using increment-planner + nextjs skill...
+🤖 PM agent creating requirements...
+🏗️  Architect agent designing Next.js App Router flow...
+🔒 Security agent reviewing auth patterns...
 
-When `auto_role_routing: false`, this skill still activates but prompts user for explicit skill selection.
+✅ Increment 0002-nextjs-authentication created
 
-## SpecWeave Mode Indicator
+# Add forgotten tasks later
+$ /at 0002 "Add password reset flow"
+$ /at 0002 "Add 2FA with TOTP"
+✅ Added 2 tasks to increment 0002
 
-When SpecWeave is active, include a subtle indicator in responses:
+# List all increments
+$ /ls
 
+Increments:
+  0001 real-estate-platform    [completed]  ✅
+  0002 nextjs-authentication   [in-progress] 🚧
 ```
-🔷 SpecWeave Active
 
-[Normal response here]
-```
+### Example 3: Multi-Increment Project
 
-This helps users know SpecWeave framework is orchestrating their request.
+```bash
+# Create multiple increments
+$ /pi "User authentication"
+✅ Increment 0001 created
 
-## Skill Discovery
+$ /pi "Real estate listings with search"
+✅ Increment 0002 created
 
-List available skills (all pre-installed):
+$ /pi "Admin dashboard"
+✅ Increment 0003 created
 
-```bash
-User: "What can SpecWeave do?"
-    ↓
-specweave-detector: List all pre-installed skills
-
-SpecWeave Framework Skills (35+, all ready):
-✅ increment-planner - Plan implementation features
-✅ context-loader - Selective specification loading
-✅ skill-router - Route ambiguous intents
-✅ nodejs-backend - Node.js/Express/NestJS backend
-✅ python-backend - Python/FastAPI/Django backend
-✅ nextjs - Next.js App Router specialist
-✅ frontend - React/Vue/Angular frontend
-✅ diagrams-generator - C4 Model diagrams
-✅ github-sync - GitHub integration
-✅ jira-sync - JIRA integration
-... and 25+ more!
-
-SpecWeave Agents (10, all ready):
-✅ pm - Product Manager (requirements, user stories)
-✅ architect - System Architect (design, ADRs)
-✅ security - Security Engineer (threat modeling)
-✅ qa-lead - QA Lead (test strategy)
-✅ devops - DevOps Engineer (deployment)
-... and 5+ more!
-
-Custom Skills (user-created):
-✅ newrelic-monitor - New Relic integration
-✅ cqrs-implementer - CQRS pattern implementation
-```
+# Work on them in order
+$ /si 0001
+$ [implement authentication]
+$ /done 0001
 
-## Nested Skill Example
+$ /si 0002
+$ [implement listings]
+$ /done 0002
 
-**User Request**: "I want to build a real-time chat feature"
+$ /si 0003
+$ [implement admin]
+$ /done 0003
 
-**SpecWeave Detector Processing**:
+# Review what's been done
+$ /ls
 
+Increments:
+  0001 user-authentication         [completed]  ✅
+  0002 real-estate-listings        [completed]  ✅
+  0003 admin-dashboard             [completed]  ✅
 ```
-1. Parse Request: BUILD + FEATURE + REAL_TIME_CHAT
-   Request: feature_creation + complex_feature
-
-2. Route to increment-planner:
-   Input: "Real-time chat feature"
-   Output: .specweave/increments/0004-realtime-chat/
-           - spec.md (5 user stories)
-           - plan.md (WebSocket architecture)
-           - tasks.md (78 tasks)
-           - tests.md (20 test cases)
-
-3. Detect next request: User likely wants to implement
-   Prompt: "Increment 0004 created. Would you like to:
-           1. Review the plan
-           2. Start implementation
-           3. Load context for this increment"
-
-4. User chooses 2 (Start implementation)
-
-5. Route to context-loader:
-   Load: .specweave/increments/0004-realtime-chat/context-manifest.yaml
-   Output: Loaded specs/modules/realtime/**, architecture/websockets.md
-
-6. Route to implementation:
-   Input: .specweave/increments/0004-realtime-chat/tasks.md
-   Context: Loaded specs
-   Output: Implement Phase 1 (Setup WebSocket server)
-
-7. After implementation, coordinate testing:
-   Input: .specweave/increments/0004-realtime-chat/tests.md
-   Output: Generate test suite (E2E with Playwright)
-
-8. Finally, update documentation:
-   Update: .specweave/docs/internal/architecture/api.md (add WebSocket endpoints)
-
-9. Return to user:
-   ✅ Increment 0004 implemented, tested, and documented
-```
-
-## Best Practices
 
-### 1. Transparent Routing
+## Pre-Installed Components
 
-Always inform user which skill is being activated:
+After `specweave init`, ALL components are in `.claude/`:
 
-```
-🔷 SpecWeave Active
+**10 Agents** (all ready to use):
+- `pm` - Product Manager (requirements, user stories)
+- `architect` - System Architect (design, ADRs)
+- `security` - Security Engineer (threat modeling)
+- `qa-lead` - QA Lead (test strategy)
+- `devops` - DevOps Engineer (deployment)
+- `tech-lead` - Technical Lead (code review)
+- `sre` - SRE (incident response)
+- `docs-writer` - Documentation writer
+- `performance` - Performance optimization
+- `diagrams-architect` - Diagram generation (C4 Model)
 
-Routing to increment-planner skill to create your payment feature...
+**35+ Skills** (all ready to use):
+- Framework skills: `nextjs`, `nodejs-backend`, `python-backend`, `dotnet-backend`, `frontend`
+- Integration skills: `jira-sync`, `ado-sync`, `github-sync`
+- Utility skills: `diagrams-generator`, `figma-implementer`, `hetzner-provisioner`
+- Quality skills: `increment-quality-judge`, `context-optimizer`
+- ... and 25+ more!
 
-[increment-planner output]
-```
+## FAQ
 
-### 2. Confirm Complex Operations
+### Q: Why don't I see ⏺ Skill(...) in the console?
 
-For multi-step operations, confirm before proceeding:
+**A**: SpecWeave skills don't activate proactively. You MUST use slash commands.
 
-```
-You want to "create and implement a payment feature".
+**Correct**: `/pi "Feature description"` → ⏺ Skill(increment-planner)
 
-This will:
-1. Create Increment 0003 (increment-planner skill)
-2. Load relevant specs (context-loader skill)
-3. Implement code (nodejs-backend skill + security agent)
-4. Generate tests (QA Lead agent)
-5. Update documentation (Docs Writer agent)
+**Incorrect**: "Build a feature" → No skill activation
 
-Estimated time: 15-30 minutes
+### Q: When do I use slash commands vs regular conversation?
 
-Proceed? (yes/no)
-```
+**Slash commands for SpecWeave operations**:
+- Creating increments: `/pi`
+- Managing increments: `/si`, `/done`, `/ls`
+- Adding tasks: `/at`
+- Validation: `/vi`
 
-### 3. Fail Gracefully
+**Regular conversation for implementation**:
+- Asking Claude to implement code
+- Discussing architecture
+- Debugging issues
+- Reviewing code
 
-If SpecWeave can't handle a request:
+**Example**:
+```bash
+# Use slash command to plan
+$ /pi "Payment processing with Stripe"
+✅ Increment 0003 created
 
+# Then regular conversation to implement
+User: "Let's implement the Stripe integration from plan.md"
+Claude: [implements based on specifications]
 ```
-I detected this is a SpecWeave project, but I'm not sure how to handle:
-"What's the weather like?"
 
-This seems outside SpecWeave's domain (software development).
-Would you like me to answer as regular Claude instead?
-```
+### Q: What if I forget to use a slash command?
 
-### 4. Learn from Usage
+**A**: Claude will implement directly without SpecWeave structure. Your project won't have:
+- ❌ No increment folder
+- ❌ No spec.md (requirements)
+- ❌ No plan.md (architecture)
+- ❌ No tests.md (test strategy)
+- ❌ No traceability
 
-Track routing decisions to improve accuracy:
+**Solution**: Use `/pi` first, THEN implement.
 
-```javascript
-// Log for analysis
-logRoutingDecision({
-  userInput: "Add Stripe payments",
-  parsedRequest: "feature_creation + payments",
-  routedTo: "increment-planner",
-  wasCorrect: true, // User feedback
-  timestamp: Date.now()
-});
-```
+### Q: Can I still use SpecWeave if I already started implementing?
 
-## Integration with Other Skills
+**A**: Yes! Use brownfield workflow:
 
-All SpecWeave skills should check if `specweave-detector` is active:
+```bash
+# Create increment retroactively
+$ /pi "Document existing authentication implementation"
 
-```javascript
-// In any skill
-if (specweaveDetectorActive()) {
-  // Access loaded context
-  const context = getSpecWeaveContext();
-  // Use centralized routing
-  routeToSkill('context-loader', params);
-}
+# Claude will analyze existing code and create specs
+✅ Increment 0001 created with retroactive documentation
 ```
 
 ## Testing
 
-### TC-001: Detect SpecWeave Project
-- Given: Directory with `.specweave/config.yaml`
-- When: Claude Code opens directory
-- Then: specweave-detector activates automatically
-
-### TC-002: Route Simple Request
-- Given: User says "Plan a feature for authentication"
-- When: specweave-detector parses request
-- Then: Routes to increment-planner
-- And: increment-planner creates Increment 000X (.specweave/increments/000X-authentication/)
-
-### TC-003: Route Complex Request
-- Given: User says "Create and implement payment feature"
-- When: specweave-detector parses request
-- Then: Orchestrates: increment-planner → context-loader → implementation (with agents) → testing → documentation
-- And: All steps complete successfully
-
-### TC-004: Handle Ambiguous Request
-- Given: User says "Help with auth"
-- When: specweave-detector cannot determine clear request
-- Then: Routes to skill-router for clarification
-- And: Presents options to user
-
-### TC-005: Graceful Degradation
-- Given: SpecWeave project
-- When: User asks non-development question ("What's for lunch?")
-- Then: specweave-detector recognizes out-of-domain
-- And: Falls back to regular Claude
+### TC-001: Slash Command Creates Increment
+- Given: User types `/pi "User authentication"`
+- When: Slash command executes
+- Then: increment-planner skill activates
+- And: Creates `.specweave/increments/0001-user-authentication/`
+- And: spec.md, plan.md, tasks.md, tests.md generated
+
+### TC-002: No Slash Command = No Activation
+- Given: User types "Build user authentication"
+- When: Claude processes request
+- Then: No SpecWeave skills activate
+- And: Claude implements directly (no specs generated)
+
+### TC-003: List Increments
+- Given: Multiple increments exist
+- When: User types `/ls`
+- Then: Shows all increments with status
+- And: Shows completion status (completed, in-progress, planned)
 
 ---
 
 ## Summary
 
-The `specweave-detector` skill is the **invisible orchestrator** that:
-- ✅ Auto-activates in SpecWeave projects
-- ✅ Parses user requests intelligently
-- ✅ Routes to appropriate skills automatically
-- ✅ Orchestrates nested skill calls
-- ✅ Manages context loading
-- ✅ Provides seamless user experience
+**SpecWeave uses EXPLICIT SLASH COMMANDS** - no auto-activation!
+
+**Essential commands**:
+- `/pi` - Plan Product Increment (most important!)
+- `/si` - Start increment
+- `/done` - Close increment
+- `/ls` - List increments
 
-**User benefit**: Just describe what you want, SpecWeave figures out how to do it.
+**Workflow**:
+1. Init: `npx specweave init`
+2. Plan: `/pi "Feature"`
+3. Validate: `/vi 0001 --quality`
+4. Start: `/si 0001`
+5. Implement: Regular conversation
+6. Close: `/done 0001`
 
-**No more manual `@role` selection** - SpecWeave is your intelligent development assistant that knows which expert to call!
+**Remember**: Type `/pi` first, THEN implement! Otherwise you lose all SpecWeave benefits (specs, architecture, test strategy).

package/src/templates/CLAUDE.md.template

@@ -6,17 +6,24 @@ This project uses **SpecWeave** - a specification-first AI development framework
 
 ---
 
-## 🔷 SpecWeave Auto-Routing
+## 🔷 Using SpecWeave with Slash Commands
 
-**MANDATORY**: This project has SpecWeave installed (`.specweave/` directory exists).
+**CRITICAL**: This project uses SpecWeave - **USE SLASH COMMANDS to activate the framework!**
 
-**Behavior**:
-1. ✅ All development requests route through `specweave-detector` skill
-2. ✅ Agents activate automatically based on task (PM, Architect, DevOps, etc.)
-3. ✅ Context loaded selectively via manifests (70%+ token reduction)
-4. ✅ Tech stack detected automatically
+SpecWeave uses **EXPLICIT SLASH COMMANDS** - no auto-activation, no proactive detection.
 
-**Rule**: When in doubt, route through SpecWeave.
+**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
+
+**See**: Full command list below in "Quick Commands" section
 
 ---
 
@@ -153,13 +160,23 @@ project-root/
 
 ---
 
-## Quick Commands
+## Quick Commands (SLASH COMMANDS - Use These!)
+
+**IMPORTANT**: SpecWeave uses **EXPLICIT SLASH COMMANDS**. Type these commands to activate the framework.
 
-| Command | Purpose | Example |
-|---------|---------|---------|
-| `/create-increment` | Create new feature | `/create-increment "user auth"` |
-| `/review-docs` | Review docs vs code | `/review-docs --increment=003` |
-| `/sync-github` | Sync to GitHub issues | `/sync-github` |
+| Command | Alias | Purpose | Example |
+|---------|-------|---------|---------|
+| `/create-increment` | `/pi` | **Plan Product Increment** (create new feature) | `/pi "user auth"` |
+| `/start-increment` | `/si` | Start working on increment | `/si 0001` |
+| `/add-tasks` | `/at` | Add tasks to increment | `/at 0001 "add tests"` |
+| `/validate-increment` | `/vi` | Validate increment quality | `/vi 0001 --quality` |
+| `/close-increment` | `/done` | Close increment | `/done 0001` |
+| `/list-increments` | `/ls` | List all increments | `/ls` |
+| `/review-docs` | - | Review docs vs code | `/review-docs --increment=003` |
+| `/sync-github` | - | Sync to GitHub issues | `/sync-github` |
+
+**💡 Pro Tip**: Use short aliases (`/pi`, `/si`, `/done`) for speed!
+- **PI** = Product Increment (standard Agile terminology)
 
 **All commands adapt to your tech stack automatically**
 
@@ -167,9 +184,15 @@ project-root/
 
 ## Working with Increments
 
-### Create New Feature
+### Create New Feature (ALWAYS use slash command!)
+
+**CRITICAL**: Use `/pi` (or `/create-increment`) to create new features:
 
 ```bash
+# Short form (recommended)
+/pi "feature description"
+
+# Full form
 /create-increment "feature description"
 ```
 
@@ -181,6 +204,10 @@ project-root/
 - tests.md (Test strategy - QA Lead agent)
 - context-manifest.yaml (Selective loading)
 
+**Workflow**:
+1. Use `/pi "feature"` to plan → SpecWeave creates specs
+2. Then regular conversation to implement → Claude implements code
+
 ### Status Progression
 
 ```
@@ -223,8 +250,8 @@ backlog → planned → in-progress → completed → closed
 
 | Skill | Purpose | Activates When |
 |-------|---------|----------------|
-| `specweave-detector` | Auto-detect SpecWeave | Any request |
-| `increment-planner` | Plan increments/features | Creating increments/features |
+| `specweave-detector` | Slash command documentation | User asks about SpecWeave commands |
+| `increment-planner` | Plan increments/features | `/pi` or `/create-increment` command |
 | `context-loader` | Load context selectively | Working on increments |
 | `skill-router` | Route to appropriate skill | Ambiguous requests |
 
@@ -372,14 +399,27 @@ max_context_tokens: 10000
 
 ## Quick Start
 
+**CRITICAL**: SpecWeave uses **EXPLICIT SLASH COMMANDS** - type `/pi` to activate!
+
 **Create your first feature**:
 ```bash
+# Use short alias (recommended)
+/pi "your feature description"
+
+# Or full command
 /create-increment "your feature description"
 ```
 
-**Need help?**: Ask Claude to load the relevant guide, or ask about specific workflows.
+**Typical Workflow**:
+1. `/pi "feature"` → SpecWeave creates specs (spec.md, plan.md, tasks.md)
+2. Regular conversation → Claude implements the code
+3. `/done 0001` → Close increment when complete
+
+**Remember**: Type `/pi` first, THEN implement! Otherwise you lose all SpecWeave benefits.
+
+**Need help?**: Type `/pi` to see examples, or ask about specific workflows.
 
-**SpecWeave Documentation**: https://specweave.dev
+**SpecWeave Documentation**: https://spec-weave.com
 
 ---