specweave 0.1.6 → 0.1.8

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).