specweave 0.1.5 → 0.1.7

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

@@ -1,566 +1,393 @@
 ---
 name: specweave-detector
-description: Entry point for SpecWeave framework. Automatically activates when .specweave directory is detected in the project. Acts as a factory of agents, parsing user requests and routing to appropriate skills. Supports nested skill calls and context management. This skill should ALWAYS be loaded first in SpecWeave projects. Activates for ANY user request in a SpecWeave project (auto-detects .specweave/).
-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 **automatic entry point** for all SpecWeave operations. When Claude Code detects a `.specweave/config.yaml` file, this skill activates and orchestrates the SpecWeave 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
-2. Parses user requests
-3. Routes to appropriate skills
-4. Orchestrates nested skill calls
-5. Manages context loading
+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
-// Pseudo-code for detection
-if (fileExists('.specweave/config.yaml')) {
-  activateSpecWeaveMode();
-  loadConfiguration();
+## Available Slash Commands
 
-  // AUTO-INSTALL MISSING COMPONENTS (NEW!)
-  await autoInstallComponents(userPrompt);
+### Quick Reference Table
 
-  parseUserIntent();
-  routeToSkills();
-}
-```
-
-## Just-In-Time Component Installation (CRITICAL!)
-
-**SpecWeave uses intelligent auto-installation** - components are installed on-demand based on user intent.
-
-### How It Works
-
-1. **User makes a request** (e.g., "Create Next.js authentication")
-2. **Analyze user intent** - Extract keywords (Next.js, authentication)
-3. **Map to required components**:
-   - "Next.js" → nextjs skill, nodejs-backend skill
-   - "authentication" → security agent
-   - "Create" → pm agent, architect agent
-4. **Check if components installed** in `.claude/skills/` and `.claude/agents/`
-5. **Auto-install missing components** from npm package (`node_modules/specweave/src/`)
-6. **Proceed with routing** - now all needed components are available
-
-### Keyword → Component Mapping
-
-```typescript
-// From src/utils/auto-install.ts
-const COMPONENT_MAPPING = {
-  // Framework detection
-  'next.js': { skills: ['nextjs', 'nodejs-backend'], agents: [] },
-  'react': { skills: ['frontend'], agents: [] },
-  'fastapi': { skills: ['python-backend'], agents: [] },
-  'django': { skills: ['python-backend'], agents: [] },
-  '.net': { skills: ['dotnet-backend'], agents: [] },
-
-  // Feature detection
-  'authentication': { skills: ['nodejs-backend'], agents: ['security'] },
-  'auth': { skills: [], agents: ['security'] },
-  'oauth': { skills: [], agents: ['security'] },
-  'payment': { skills: ['stripe-integrator'], agents: ['security'] },
-  'stripe': { skills: ['stripe-integrator'], agents: ['security'] },
-
-  // Infrastructure detection
-  'deploy': { skills: [], agents: ['devops'] },
-  'hetzner': { skills: ['hetzner-provisioner'], agents: ['devops'] },
-  'aws': { skills: [], agents: ['devops'] },
-
-  // Testing detection
-  'test': { skills: [], agents: ['qa-lead'] },
-  'e2e': { skills: ['e2e-playwright'], agents: ['qa-lead'] },
-  'playwright': { skills: ['e2e-playwright'], agents: ['qa-lead'] },
-
-  // Design detection
-  'figma': { skills: ['figma-implementer', 'figma-designer'], agents: [] },
-  'design system': { skills: ['design-system-architect'], agents: [] },
-
-  // Integration detection
-  'jira': { skills: ['jira-sync'], agents: [] },
-  'github': { skills: ['github-sync'], agents: [] },
-};
-
-// Always include strategic agents for new features
-if (prompt.includes('create') || prompt.includes('build')) {
-  agents.push('pm', 'architect');
-}
-```
+| 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` |
 
-### Example User Experience
+### Command Details
 
-**Example 1: Next.js Authentication**
-```
-User: "Create Next.js authentication with OAuth"
+#### `/pi` or `/create-increment` - Plan Product Increment
 
-🔷 SpecWeave Active
+**Most important command!** Creates a new increment with specifications.
 
-📦 Installing required components...
-   ✅ Installed nextjs skill
-   ✅ Installed nodejs-backend skill
-   ✅ Installed security agent
-   ✅ Installed pm agent
-   ✅ Installed architect agent
+```bash
+# Short form (recommended)
+/pi "User authentication with JWT and RBAC"
 
-🚀 Creating increment 0001-nextjs-authentication...
+# Full form
+/create-increment "User authentication with JWT and RBAC"
 ```
 
-**Example 2: Already Installed**
-```
-User: "Add another Next.js feature"
+**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)
 
-🔷 SpecWeave Active
-   (Components already installed, proceeding...)
+#### `/si` or `/start-increment` - Start Working
 
-🚀 Creating increment 0002-next-feature...
-```
+Marks an increment as "in-progress".
 
-**Example 3: Python FastAPI**
+```bash
+/si 0001
 ```
-User: "Create FastAPI backend with PostgreSQL"
 
-🔷 SpecWeave Active
+#### `/at` or `/add-tasks` - Add Tasks
 
-📦 Installing required components...
-   ✅ Installed python-backend skill
-   ✅ Installed pm agent
-   ✅ Installed architect agent
+Add additional tasks to an increment.
 
-🚀 Creating increment 0001-fastapi-backend...
+```bash
+/at 0001 "Add password reset functionality"
+/at 0001 "Add email verification"
 ```
 
-### Configuration
+#### `/vi` or `/validate-increment` - Validate Quality
 
-Auto-install can be disabled in `.specweave/config.yaml`:
+Run validation checks on an increment.
 
-```yaml
-# .specweave/config.yaml
-auto_install: true  # Default: enabled
+```bash
+# Rule-based validation only
+/vi 0001
 
-# Tracked installed components (auto-updated)
-installed_components:
-  skills:
-    - nextjs
-    - nodejs-backend
-    - security
-  agents:
-    - pm
-    - architect
-    - security
+# With AI quality assessment
+/vi 0001 --quality
 ```
 
-Set `auto_install: false` to require manual installation (advanced users only).
+#### `/done` or `/close-increment` - Close Increment
 
-### Installation Process
+Mark increment as completed.
 
-When auto-installing:
-
-1. **Find npm package**: Locate `node_modules/specweave/`
-2. **Copy component**: `src/skills/nextjs/` → `.claude/skills/nextjs/`
-3. **Verify**: Check component has SKILL.md or AGENT.md
-4. **Update config**: Add to `installed_components` list
-5. **Continue routing**: Component now available for use
+```bash
+/done 0001
+```
 
-### Benefits
+#### `/ls` or `/list-increments` - List All
 
-- ✅ **Zero manual installation** - users never run `specweave install`
-- ✅ **Just-in-time** - only install what's actually needed
-- ✅ **Automatic** - completely transparent to users
-- ✅ **Intelligent** - understands intent from natural language
-- ✅ **Efficient** - unused components never installed
+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 Feature 002
-# 5. Returns result to user
-
-# User sees:
-✅ Feature created: 002-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 feature → `increment-planner`
-2. Implement code → Load context via `context-loader`
-3. Implement code → `developer`
-4. Generate tests → `qa-engineer`
-5. Update docs → `docs-updater`
+### 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 003-payment-processing/
-    ↓
-context-loader: Load specs/modules/payments/**
-    ↓
-developer: Implement based on tasks.md
-    ↓
-qa-engineer: Generate test cases
-    ↓
-docs-updater: Update README, docs/
-    ↓
-Result: "✅ Feature 003 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 a feature:
+# Start working
+/si 0001
+```
 
-```javascript
-// Detect active work
-const activeIssue = detectActiveIssue(); // work/issues/###-xxx/
+### 4. Add More Tasks (As Needed)
 
-if (activeIssue) {
-  const manifest = loadManifest(`${activeIssue}/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 work item** (in `work/issues/`)
-2. **Current feature** (referenced in git branch)
-3. **User-specified** context
-4. **Global** context (specs/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 feature 005"
-    ↓
-specweave-detector: Route to developer
-    ↓
-developer: ERROR - Feature 005 not found
-    ↓
-specweave-detector: Catch error, suggest:
-"Feature 005 doesn't exist. Would you like to:
-1. Create it first (increment-planner)
-2. List existing features
-3. Implement a different feature"
+# 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"
 
-skills:
-  install_location: "local"       # Where skills are installed
-  auto_install: true              # Auto-install missing skills
+🔷 SpecWeave Active (/create-increment)
 
-integrations:
-  github:
-    enabled: true
-    sync_issues: true             # Sync features ↔ GitHub issues
-```
+📝 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:
+$ /pi "Admin dashboard"
+✅ Increment 0003 created
 
-```bash
-User: "What can SpecWeave do?"
-    ↓
-specweave-detector: List installed skills
-
-SpecWeave Skills:
-✅ increment-planner - Plan implementation features
-✅ context-loader - Selective specification loading
-✅ skill-router - Route ambiguous intents
-📦 spec-author - Create specifications (install with: npx specweave install spec-author)
-📦 architect - System design (install with: npx specweave install architect)
-
-Custom Skills:
-✅ 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: features/004-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: "Feature 004 created. Would you like to:
-           1. Review the plan
-           2. Start implementation
-           3. Load context for this feature"
-
-4. User chooses 2 (Start implementation)
-
-5. Route to context-loader:
-   Load: features/004-realtime-chat/context-manifest.yaml
-   Output: Loaded specs/modules/realtime/**, architecture/websockets.md
-
-6. Route to developer:
-   Input: features/004-realtime-chat/tasks.md
-   Context: Loaded specs
-   Output: Implement Phase 1 (Setup WebSocket server)
-
-7. After implementation, route to qa-engineer:
-   Input: features/004-realtime-chat/tests.md
-   Output: Generate test suite
-
-8. Finally, route to docs-updater:
-   Update: docs/reference/api.md (add WebSocket endpoints)
-
-9. Return to user:
-   ✅ Feature 004 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 Feature 003 (increment-planner)
-2. Load relevant specs (context-loader)
-3. Implement code (developer)
-4. Generate tests (qa-engineer)
-5. Update documentation (docs-updater)
+**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 Feature 00X
-
-### TC-003: Route Complex Request
-- Given: User says "Create and implement payment feature"
-- When: specweave-detector parses request
-- Then: Orchestrates: increment-planner → context-loader → developer → qa-engineer → docs-updater
-- 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).