specweave 0.3.8 → 0.3.9

package/dist/utils/model-selection.js

@@ -0,0 +1,204 @@
+/**
+ * Model Selection Utilities
+ *
+ * Intelligent model selection for SpecWeave tasks based on complexity,
+ * instruction detail, and task characteristics.
+ *
+ * Strategy:
+ * - Haiku: Detailed instructions, clear acceptance criteria, mechanical work
+ * - Sonnet: Complex decisions, architecture, creative problem-solving
+ * - Opus: Critical architecture, high-stakes decisions (rare)
+ */
+/**
+ * Keywords that suggest complex thinking is required (Sonnet territory)
+ */
+const COMPLEX_KEYWORDS = [
+    'design', 'architecture', 'architect', 'evaluate', 'choose', 'decide',
+    'compare', 'analyze', 'research', 'investigate', 'plan', 'strategy',
+    'refactor', 'optimize', 'tradeoff', 'consider', 'assess', 'review'
+];
+/**
+ * Keywords that suggest simple implementation (Haiku territory)
+ */
+const SIMPLE_KEYWORDS = [
+    'implement', 'create', 'add', 'update', 'fix', 'write', 'install',
+    'configure', 'setup', 'integrate', 'connect', 'deploy', 'build',
+    'test', 'validate', 'document', 'format', 'style', 'lint'
+];
+/**
+ * Keywords that suggest creative/critical work (Sonnet/Opus territory)
+ */
+const CREATIVE_KEYWORDS = [
+    'novel', 'innovative', 'unique', 'creative', 'original', 'new approach',
+    'alternative', 'improve', 'enhance', 'redesign', 'rethink'
+];
+/**
+ * Detects the optimal model for a given task
+ *
+ * @param task - The task to analyze
+ * @param options - Additional context (spec detail level, etc.)
+ * @returns Detection result with model recommendation and reasoning
+ */
+export function detectModelForTask(task, options = {}) {
+    const taskText = `${task.content} ${task.description || ''}`.toLowerCase();
+    // Score-based detection
+    let haikuScore = 0;
+    let sonnetScore = 0;
+    let opusScore = 0;
+    // 1. Keyword analysis
+    COMPLEX_KEYWORDS.forEach(keyword => {
+        if (taskText.includes(keyword)) {
+            sonnetScore += 2;
+        }
+    });
+    SIMPLE_KEYWORDS.forEach(keyword => {
+        if (taskText.includes(keyword)) {
+            haikuScore += 1;
+        }
+    });
+    CREATIVE_KEYWORDS.forEach(keyword => {
+        if (taskText.includes(keyword)) {
+            sonnetScore += 3;
+            opusScore += 1;
+        }
+    });
+    // 2. Spec/plan reference analysis
+    if (task.specReference && options.specDetailLevel && options.specDetailLevel > 0.7) {
+        haikuScore += 3; // Has detailed spec reference
+    }
+    if (options.hasDetailedPlan) {
+        haikuScore += 2; // Implementation approach already defined
+    }
+    if (options.isArchitectural) {
+        sonnetScore += 4; // Architectural decisions need thinking
+        opusScore += 2;
+    }
+    // 3. Acceptance criteria analysis
+    if (task.acceptanceCriteria && task.acceptanceCriteria.length >= 3) {
+        haikuScore += 2; // Clear, specific criteria = can use Haiku
+    }
+    // 4. Priority analysis (P1 might need more careful attention)
+    if (task.priority === 'P1' && !options.hasDetailedPlan) {
+        sonnetScore += 1; // Critical work without plan = need thinking
+    }
+    // 5. Task complexity indicators
+    const hasFileReference = /src\/[a-zA-Z0-9\/\-_.]+\.(ts|js|tsx|jsx|py|java|go)/.test(taskText);
+    if (hasFileReference) {
+        haikuScore += 2; // Specific file paths = concrete instructions
+    }
+    const hasMultipleSteps = taskText.split(/\n|;|,/).length > 3;
+    if (hasMultipleSteps && options.hasDetailedPlan) {
+        haikuScore += 1; // Multi-step with plan = can execute mechanically
+    }
+    // Calculate confidence and select model
+    const totalScore = haikuScore + sonnetScore + opusScore;
+    const haikuConfidence = totalScore > 0 ? haikuScore / totalScore : 0;
+    const sonnetConfidence = totalScore > 0 ? sonnetScore / totalScore : 0;
+    const opusConfidence = totalScore > 0 ? opusScore / totalScore : 0;
+    // Decision logic
+    let selectedModel;
+    let confidence;
+    let reasoning;
+    if (opusScore > 5 && opusConfidence > 0.3) {
+        selectedModel = 'opus';
+        confidence = opusConfidence;
+        reasoning = 'Critical architectural decision requiring deep reasoning';
+    }
+    else if (haikuScore > sonnetScore && haikuConfidence > 0.5) {
+        selectedModel = 'haiku';
+        confidence = haikuConfidence;
+        reasoning = 'Clear instructions with detailed spec/plan - suitable for fast execution';
+    }
+    else if (sonnetScore > haikuScore || sonnetConfidence > 0.4) {
+        selectedModel = 'sonnet';
+        confidence = sonnetConfidence;
+        reasoning = 'Requires decision-making or complex implementation';
+    }
+    else {
+        // Default to sonnet for safety
+        selectedModel = 'sonnet';
+        confidence = 0.5;
+        reasoning = 'Default to sonnet for balanced quality and speed';
+    }
+    return {
+        model: selectedModel,
+        confidence,
+        reasoning
+    };
+}
+/**
+ * Batch detect models for multiple tasks
+ * Useful when generating tasks.md from plan.md
+ */
+export function detectModelsForTasks(tasks, options = {}) {
+    const results = new Map();
+    tasks.forEach(task => {
+        const result = detectModelForTask(task, options);
+        results.set(task.id, result);
+    });
+    return results;
+}
+/**
+ * Format model hint for tasks.md
+ *
+ * @param model - The model tier
+ * @returns Formatted string for inclusion in tasks.md
+ */
+export function formatModelHint(model) {
+    const icons = {
+        haiku: '⚡', // Fast
+        sonnet: '🧠', // Thinking
+        opus: '💎' // Premium
+    };
+    return `${icons[model]} ${model}`;
+}
+/**
+ * Parse model hint from tasks.md line
+ *
+ * @param line - A line from tasks.md
+ * @returns Detected model or null
+ */
+export function parseModelHint(line) {
+    const haikuMatch = /⚡\s*haiku|model:\s*haiku/i.test(line);
+    const sonnetMatch = /🧠\s*sonnet|model:\s*sonnet/i.test(line);
+    const opusMatch = /💎\s*opus|model:\s*opus/i.test(line);
+    if (haikuMatch)
+        return 'haiku';
+    if (sonnetMatch)
+        return 'sonnet';
+    if (opusMatch)
+        return 'opus';
+    return null;
+}
+/**
+ * Cost estimation utilities
+ */
+export function estimateTaskCost(model, estimatedTokens = 2000) {
+    // Approximate costs per 1M tokens (input + output blended)
+    const costPer1M = {
+        haiku: 1.25, // $0.25 input + $1.25 output = ~$1.25 blended
+        sonnet: 15.00, // $3 input + $15 output = ~$15 blended
+        opus: 75.00 // $15 input + $75 output = ~$75 blended
+    };
+    return (estimatedTokens / 1000000) * costPer1M[model];
+}
+/**
+ * Calculate total cost savings when using smart model selection
+ */
+export function calculateCostSavings(tasksWithModels, averageTokensPerTask = 2000) {
+    let optimizedCost = 0;
+    let allSonnetCost = 0;
+    tasksWithModels.forEach((model) => {
+        optimizedCost += estimateTaskCost(model, averageTokensPerTask);
+        allSonnetCost += estimateTaskCost('sonnet', averageTokensPerTask);
+    });
+    const savings = allSonnetCost - optimizedCost;
+    const savingsPercent = (savings / allSonnetCost) * 100;
+    return {
+        optimizedCost,
+        allSonnetCost,
+        savings,
+        savingsPercent
+    };
+}
+//# sourceMappingURL=model-selection.js.map

package/dist/utils/model-selection.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"model-selection.js","sourceRoot":"","sources":["../../src/utils/model-selection.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "specweave",
-  "version": "0.3.8",
+  "version": "0.3.9",
   "description": "Replace vibe coding with spec-driven development. Smart workflow: /specweave inc auto-closes previous, /specweave build auto-resumes, /specweave progress shows status. PM-led planning, 10 agents, 35+ skills. spec-weave.com",
   "type": "module",
   "main": "dist/index.js",
@@ -23,6 +23,7 @@
     "generate:tests:skill": "ts-node scripts/generate-tests.ts",
     "test:all:generated": "bash scripts/run-all-tests.sh",
     "test:all": "npm test && npm run test:smoke && npm run test:integration",
+    "generate:skills-index": "ts-node src/utils/generate-skills-index.ts",
     "prepublishOnly": "npm run build",
     "install:agents": "bash bin/install-agents.sh",
     "install:skills": "bash bin/install-skills.sh",

package/src/adapters/copilot/README.md

@@ -18,9 +18,36 @@ Unlike Claude Code (native skills/agents/commands) and Cursor (simulated via .cu
 - Workspace instructions (.github/copilot/instructions.md)
 - Better code suggestions based on project context
 - Copilot Chat for Q&A
+- **Progressive disclosure via SKILLS-INDEX.md** (NEW in v0.3.8) - Access all 35+ skills!
 
 ## What This Adapter Provides
 
+### 🔍 Progressive Disclosure (NEW)
+
+SpecWeave now includes **SKILLS-INDEX.md** - enabling GitHub Copilot to discover and use all 35+ skills!
+
+**How it works**:
+1. Read `.claude/skills/SKILLS-INDEX.md` (referenced in AGENTS.md)
+2. Match task to activation keywords
+3. Load specific SKILL.md when relevant
+4. Follow proven workflows
+
+**Benefits**:
+- ✅ **90% token savings** (5k vs 50k tokens)
+- ✅ **Full skill access** - All 35+ skills now available to Copilot!
+- ✅ **Consistent output** - Follow SpecWeave best practices
+
+**Example**:
+```markdown
+# From AGENTS.md, you learn about:
+.claude/skills/SKILLS-INDEX.md  # Single-file skill reference
+
+# When user asks: "Plan a new feature"
+# 1. Read SKILLS-INDEX.md → Find "increment-planner" skill
+# 2. Load .claude/skills/increment-planner/SKILL.md
+# 3. Follow the increment planning workflow
+```
+
 ### .github/copilot/instructions.md
 - **What**: Workspace guidance that Copilot reads automatically
 - **Contains**: Project structure, workflows, best practices

package/src/adapters/cursor/README.md

@@ -31,6 +31,35 @@ This is **meta-documentation** - teaching the AI how to behave!
 
 ## What This Adapter Provides
 
+### 🔍 Progressive Disclosure (NEW in v0.3.8)
+
+SpecWeave now includes **SKILLS-INDEX.md** - enabling Cursor to efficiently discover and use all 35+ skills!
+
+**How it works**:
+1. Read `.claude/skills/SKILLS-INDEX.md` (referenced in AGENTS.md)
+2. Match task to activation keywords (e.g., "feature planning" → increment-planner)
+3. Load specific SKILL.md when relevant
+4. Follow proven workflows
+
+**Benefits**:
+- ✅ **90% token savings** (5k vs 50k tokens - load only what you need)
+- ✅ **Full skill access** - All 35+ skills now efficiently accessible!
+- ✅ **Consistent output** - Follow SpecWeave best practices every time
+
+**Example**:
+```markdown
+# From AGENTS.md, Cursor learns about:
+.claude/skills/SKILLS-INDEX.md  # Single-file skill reference
+
+# When user asks: "Plan a new feature for auth"
+# 1. Read SKILLS-INDEX.md → Find "increment-planner" (matches "feature planning")
+# 2. Load .claude/skills/increment-planner/SKILL.md
+# 3. Follow the increment planning workflow
+# Result: Proper spec.md, plan.md, tasks.md creation
+```
+
+**Note**: While Claude Code activates skills automatically, Cursor simulates this by following the progressive disclosure pattern documented in AGENTS.md.
+
 ### .cursorrules (Workflow Instructions)
 - **What**: Complete workflow guide for SpecWeave
 - **How**: Teaches Cursor to act like skills/agents

package/src/agents/pm/AGENT.md

@@ -59,6 +59,8 @@ The PM Agent acts as your AI Product Manager, helping you:
 └── roadmap.md           # Product roadmap (if applicable)
 ```
 
+**Rationale**: Internal docs = strategic, team-only content (architecture decisions, business strategy)
+
 **Format Rules**:
 - ✅ **Technology-agnostic** (WHAT and WHY only)
 - ✅ **Complete** (all details, no summaries)
@@ -617,7 +619,7 @@ PM Agent:
 5. Provide recommendation
     ↓
 Output:
-- .specweave/docs/decisions/005-database-refactoring-business-case.md
+- .specweave/docs/internal/decisions/005-database-refactoring-business-case.md
 - Stakeholder presentation (Markdown or slides)
 ```
 

package/src/commands/specweave.do.md

@@ -17,6 +17,11 @@ You are helping the user implement a SpecWeave increment by executing tasks from
 
 # Or let it find active increment automatically
 /do
+
+# Override model selection for all tasks (advanced)
+/do <increment-id> --model haiku
+/do <increment-id> --model sonnet
+/do <increment-id> --model opus
 ```
 
 ## Arguments
@@ -25,6 +30,12 @@ You are helping the user implement a SpecWeave increment by executing tasks from
   - If omitted, finds the active in-progress increment automatically
   - **Smart resume**: Automatically starts from next incomplete task
 
+- `--model <tier>`: Optional. Override model selection for all tasks
+  - `haiku`: Fast, cheap execution (3x faster, 20x cheaper than Sonnet)
+  - `sonnet`: Balanced quality and speed (default for complex tasks)
+  - `opus`: Maximum quality (rare, use only for critical decisions)
+  - If omitted, uses model hints from tasks.md (recommended)
+
 ---
 
 ## Workflow
@@ -67,6 +78,7 @@ You are helping the user implement a SpecWeave increment by executing tasks from
 1. **Parse tasks.md**:
    - Scan all tasks in order
    - Check completion status (`[x]` = complete, `[ ]` = incomplete)
+   - **Extract model hints** (⚡ haiku, 🧠 sonnet, 💎 opus)
    - Find first incomplete task
 
 2. **Determine starting point**:
@@ -74,17 +86,18 @@ You are helping the user implement a SpecWeave increment by executing tasks from
    - If tasks incomplete → Resume from first incomplete task
    - If no tasks started → Start from T001
 
-3. **Show resume context**:
+3. **Show resume context with model optimization**:
    ```
    📊 Resume Context:
 
    Completed: 3/12 tasks (25%)
-   ├─ [✅] T001: Setup auth module (P1)
-   ├─ [✅] T002: Create user model (P1)
-   ├─ [✅] T003: Implement JWT tokens (P1)
-   └─ [⏳] T004: Add password hashing (P1) ← RESUMING HERE
+   ├─ [✅] T001: ⚡ haiku - Setup auth module (P1) [saved $0.04]
+   ├─ [✅] T002: ⚡ haiku - Create user model (P1) [saved $0.04]
+   ├─ [✅] T003: 🧠 sonnet - Implement JWT tokens (P1)
+   └─ [⏳] T004: ⚡ haiku - Add password hashing (P1) ← RESUMING HERE
 
    Remaining: 9 tasks (estimated 2 weeks)
+   Cost savings so far: $0.08 (67% cheaper than all-Sonnet)
    ```
 
 **Why smart resume?**
@@ -92,6 +105,7 @@ You are helping the user implement a SpecWeave increment by executing tasks from
 - ✅ Seamlessly continue after breaks
 - ✅ Prevents duplicate work
 - ✅ Shows progress at a glance
+- ✅ **Cost optimization through smart model selection**
 
 ### Step 3: Update Status to In-Progress (if needed)
 
@@ -113,16 +127,23 @@ If already "in-progress", keep existing metadata.
 
 1. **Read task details**:
    - Task ID (T001, T002, etc.)
+   - **Model hint** (⚡ haiku, 🧠 sonnet, 💎 opus)
    - Description
    - Acceptance criteria
    - File paths affected
    - Implementation notes
 
-2. **Execute task**:
+2. **Select execution model**:
+   - **Use model from task hint** (recommended, optimizes cost/speed)
+   - OR use `--model` override if specified by user
+   - Show selected model and reasoning
+
+3. **Execute task**:
    - Follow plan.md architecture
    - Implement using detected tech stack
    - Write clean, maintainable code
    - Add inline documentation
+   - **Track cost savings** when using Haiku
 
 3. **Mark task complete** in tasks.md:
    - Change `[ ]` → `[x]`
@@ -164,16 +185,18 @@ TASK T001: Create User model (PostgreSQL)
 
 📋 Task details:
    • File: src/models/User.ts
+   • Model: ⚡ haiku (clear instructions, specific file path)
    • Description: Create User model with Prisma
    • Acceptance: Model has id, email, passwordHash, createdAt fields
 
-🔨 Executing...
+⚡ Executing with Haiku (3x faster, ~$0.0025 vs $0.05 Sonnet)...
    ✓ Created src/models/User.ts
    ✓ Added Prisma schema definition
    ✓ Generated migration file
    ✓ Added inline documentation
 
 ✅ Task T001 completed
+💰 Cost savings: $0.0475 (95% cheaper than Sonnet)
 
 🔊 [Glass.aiff plays automatically via hook]
 🔔 Task completed! Remember to update documentation...
@@ -185,7 +208,7 @@ TASK T001: Create User model (PostgreSQL)
 
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 
-Progress: 1/42 tasks (2%) | Estimated remaining: 3.9 weeks
+Progress: 1/42 tasks (2%) | Cost savings so far: $0.05 | Estimated remaining: 3.9 weeks
 
 Moving to next task...
 ```