specweave 1.0.171 → 1.0.172

package/CLAUDE.md

@@ -1,4 +1,4 @@
-<!-- SW:META template="claude" version="1.0.171" sections="hook-priority,header,start,autodetect,metarule,rules,workflow,reflect,context,structure,taskformat,secrets,syncing,testing,tdd,api,limits,troubleshooting,lazyloading,principles,linking,mcp,auto,docs" -->
+<!-- SW:META template="claude" version="1.0.171" sections="header,start,autodetect,metarule,rules,workflow,reflect,context,structure,taskformat,secrets,syncing,testing,tdd,api,limits,troubleshooting,lazyloading,principles,linking,mcp,auto,docs" -->
 
 <!-- SW:SECTION:hook-priority version="1.0.171" -->
 ## ⛔ ABSOLUTE PRIORITY: Hook Instructions Are Mandatory
@@ -25,19 +25,20 @@ If hook says **"PLUGINS INSTALLED - RESTART REQUIRED"**:
 
 **DO NOT:** "Just help anyway", "Start while they restart", "Do a quick thing first"
 
-### 🎯 SKILL INVOCATION REQUIRED = Call Skill First
+### 🎯 SKILL FIRST = Call Skill Before Implementation
 
-If hook says **"invoke Skill tool NOW"** or **"BLOCKING RULE: Your FIRST action MUST be..."**:
+If hook says **"SKILL FIRST"** or shows a Skill tool call to make:
 
-**YOU ARE BLOCKED FROM:**
-- ❌ Write tool - BLOCKED until skill completes
-- ❌ Edit tool - BLOCKED until skill completes
-- ❌ Bash implementation commands - BLOCKED until skill completes
-- ❌ Analyzing the request first - BLOCKED
-- ❌ "Let me explore the codebase" - BLOCKED
+**ORDER MATTERS:**
+1. ✅ Call the Skill tool FIRST (exactly as shown in hook)
+2. ✅ THEN proceed with implementation normally
+
+**DO NOT start with:**
+- ❌ "Let me first explore the codebase..."
+- ❌ Writing files before calling Skill
+- ❌ Extensive analysis before calling Skill
 
-**YOUR ONLY ALLOWED ACTION:**
-Call the Skill tool EXACTLY as specified in the hook. Nothing else first.
+**The skill handles planning. Call it first, then you're free to implement.**
 
 ### Why This Matters
 
@@ -49,22 +50,7 @@ Hooks exist to enforce workflow discipline. If you ignore them:
 **This is non-negotiable. No exceptions. No "just this once".**
 <!-- SW:END:hook-priority -->
 
-<!-- SW:SECTION:preflight version="1.0.171" -->
-## Pre-Flight Checklist (Before ANY Implementation)
-
-**STOP before using Write/Edit/Bash. Verify:**
-
-| Check | Action If True |
-|-------|----------------|
-| Hook says "restart required"? | ⛔ FULL STOP - display warning, provide prompt, wait |
-| Hook says "invoke Skill"? | 🎯 Call Skill tool FIRST - nothing else before |
-| Feature request (multi-file)? | 📋 Use `/sw:increment` before coding |
-| TDD mode in hook output? | 🧪 Write failing test FIRST |
-
-**Implementation is BLOCKED until relevant checks pass.**
-<!-- SW:END:preflight -->
-
-<!-- SW:SECTION:header version="1.0.170" -->
+<!-- SW:SECTION:header version="1.0.171" -->
 **Framework**: SpecWeave | **Truth**: `spec.md` + `tasks.md`
 <!-- SW:END:header -->
 
@@ -122,7 +108,7 @@ plugins/specweave/
 **Old "commands" are just skills with `disable-model-invocation: true`** - they only respond to explicit `/name` invocation, not keyword detection.
 <!-- SW:END:claude-code-concepts -->
 
-<!-- SW:SECTION:start version="1.0.170" -->
+<!-- SW:SECTION:start version="1.0.171" -->
 ## Getting Started
 
 **Initial increment**: `0001-project-setup` (auto-created by `specweave init`)
@@ -132,7 +118,7 @@ plugins/specweave/
 2. **Customize**: Edit spec.md and use for setup tasks
 <!-- SW:END:start -->
 
-<!-- SW:SECTION:autodetect version="1.0.170" -->
+<!-- SW:SECTION:autodetect version="1.0.171" -->
 ## Auto-Detection
 
 SpecWeave auto-detects product descriptions and routes to `/sw:increment`:
@@ -142,7 +128,7 @@ SpecWeave auto-detects product descriptions and routes to `/sw:increment`:
 **Opt-out phrases**: "Just brainstorm first" | "Don't plan yet" | "Quick discussion" | "Let's explore ideas"
 <!-- SW:END:autodetect -->
 
-<!-- SW:SECTION:metarule version="1.0.170" -->
+<!-- SW:SECTION:metarule version="1.0.171" -->
 ## Meta-Rule: Think-Before-Act
 
 **Satisfy dependencies BEFORE dependent operations.**
@@ -153,7 +139,7 @@ SpecWeave auto-detects product descriptions and routes to `/sw:increment`:
 ```
 <!-- SW:END:metarule -->
 
-<!-- SW:SECTION:rules version="1.0.170" -->
+<!-- SW:SECTION:rules version="1.0.171" -->
 ## Rules
 
 1. **Files** → `.specweave/increments/####-name/` (see Structure section for details)
@@ -164,7 +150,7 @@ SpecWeave auto-detects product descriptions and routes to `/sw:increment`:
 6. **⛔ Marketplace refresh**: Use `specweave refresh-marketplace` CLI (not `scripts/refresh-marketplace.sh`)
 <!-- SW:END:rules -->
 
-<!-- SW:SECTION:workflow version="1.0.170" -->
+<!-- SW:SECTION:workflow version="1.0.171" -->
 ## Workflow
 
 `/sw:increment "X"` → `/sw:do` → `/sw:progress` → `/sw:done 0001`
@@ -184,7 +170,7 @@ SpecWeave auto-detects product descriptions and routes to `/sw:increment`:
 **Natural language**: "Let's build X" → `/sw:increment` | "What's status?" → `/sw:progress` | "We're done" → `/sw:done` | "Ship while sleeping" → `/sw:auto`
 <!-- SW:END:workflow -->
 
-<!-- SW:SECTION:reflect version="1.0.170" -->
+<!-- SW:SECTION:reflect version="1.0.171" -->
 ## Skill Memories
 
 SpecWeave learns from corrections. Learnings saved here automatically. Edit or delete as needed.
@@ -197,7 +183,7 @@ SpecWeave learns from corrections. Learnings saved here automatically. Edit or d
 <!-- Auto-captured by SpecWeave reflect. Edit or delete as needed. -->
 <!-- Learnings are organized by skill name. User edits override SpecWeave defaults. -->
 
-<!-- SW:SECTION:context version="1.0.170" -->
+<!-- SW:SECTION:context version="1.0.171" -->
 ## Context
 
 **Before implementing**: Check ADRs at `.specweave/docs/internal/architecture/adr/`
@@ -205,7 +191,7 @@ SpecWeave learns from corrections. Learnings saved here automatically. Edit or d
 **Load context**: `/sw:context <topic>` loads relevant living docs into conversation
 <!-- SW:END:context -->
 
-<!-- SW:SECTION:structure version="1.0.170" -->
+<!-- SW:SECTION:structure version="1.0.171" -->
 ## Structure
 
 ```
@@ -220,7 +206,7 @@ SpecWeave learns from corrections. Learnings saved here automatically. Edit or d
 **Everything else → subfolders**: `reports/` | `logs/` | `scripts/` | `backups/`
 <!-- SW:END:structure -->
 
-<!-- SW:SECTION:taskformat version="1.0.170" -->
+<!-- SW:SECTION:taskformat version="1.0.171" -->
 ## Task Format
 
 ```markdown
@@ -230,7 +216,7 @@ SpecWeave learns from corrections. Learnings saved here automatically. Edit or d
 ```
 <!-- SW:END:taskformat -->
 
-<!-- SW:SECTION:secrets version="1.0.170" -->
+<!-- SW:SECTION:secrets version="1.0.171" -->
 ## Secrets Check
 
 **BEFORE CLI tools**: Check existing config first!
@@ -244,7 +230,7 @@ gh auth status
 **SECURITY**: NEVER use `grep TOKEN .env` without `-q` flag - it exposes credentials in terminal!
 <!-- SW:END:secrets -->
 
-<!-- SW:SECTION:syncing version="1.0.170" -->
+<!-- SW:SECTION:syncing version="1.0.171" -->
 ## External Sync (GitHub/JIRA/ADO)
 
 **Commands**: `/sw-github:sync {id}` (issues) | `/sw:sync-specs` (living docs only)
@@ -254,7 +240,7 @@ gh auth status
 **Config**: Set `sync.github.enabled: true` + `canUpdateExternalItems: true` in config.json
 <!-- SW:END:syncing -->
 
-<!-- SW:SECTION:testing version="1.0.170" -->
+<!-- SW:SECTION:testing version="1.0.171" -->
 ## Testing
 
 BDD in tasks.md | Unit >80% | `.test.ts` (Vitest)
@@ -266,7 +252,7 @@ vi.mock('./module', () => ({ func: mockFn }));
 ```
 <!-- SW:END:testing -->
 
-<!-- SW:SECTION:tdd version="1.0.170" -->
+<!-- SW:SECTION:tdd version="1.0.171" -->
 ## TDD Mode (Test-Driven Development)
 
 **When `testing.defaultTestMode: "TDD"` is configured**, follow RED-GREEN-REFACTOR discipline:
@@ -327,7 +313,7 @@ When TDD is enabled, tasks include phase markers:
 **Rule**: Complete dependencies BEFORE dependent tasks (RED before GREEN).
 <!-- SW:END:tdd -->
 
-<!-- SW:SECTION:api version="1.0.170" -->
+<!-- SW:SECTION:api version="1.0.171" -->
 ## API Development (OpenAPI-First)
 
 **For API projects only.** Commands: `/sw:api-docs --all` | `--openapi` | `--postman` | `--validate`
@@ -335,13 +321,13 @@ When TDD is enabled, tasks include phase markers:
 Enable in config: `{"apiDocs":{"enabled":true,"openApiPath":"openapi.yaml"}}`
 <!-- SW:END:api -->
 
-<!-- SW:SECTION:limits version="1.0.170" -->
+<!-- SW:SECTION:limits version="1.0.171" -->
 ## Limits
 
 **Max 1500 lines/file** — extract before adding
 <!-- SW:END:limits -->
 
-<!-- SW:SECTION:troubleshooting version="1.0.170" -->
+<!-- SW:SECTION:troubleshooting version="1.0.171" -->
 ## Troubleshooting
 
 | Issue | Fix |
@@ -357,7 +343,7 @@ Enable in config: `{"apiDocs":{"enabled":true,"openApiPath":"openapi.yaml"}}`
 | Marketplace shows 0 | Normal with auto-load; `/plugin list` shows actual |
 <!-- SW:END:troubleshooting -->
 
-<!-- SW:SECTION:lazyloading version="1.0.170" -->
+<!-- SW:SECTION:lazyloading version="1.0.171" -->
 ## Plugin Auto-Loading
 
 Plugins load automatically based on project type and keywords. Manual install if needed:
@@ -371,7 +357,7 @@ export SPECWEAVE_DISABLE_AUTO_LOAD=1         # Disable auto-load
 **Token savings**: Core ~3-5K tokens vs all plugins ~60K+
 <!-- SW:END:lazyloading -->
 
-<!-- SW:SECTION:principles version="1.0.170" -->
+<!-- SW:SECTION:principles version="1.0.171" -->
 ## Principles
 
 1. **Spec-first**: `/sw:increment` before coding
@@ -380,7 +366,7 @@ export SPECWEAVE_DISABLE_AUTO_LOAD=1         # Disable auto-load
 4. **Traceable**: All work → specs → ACs
 <!-- SW:END:principles -->
 
-<!-- SW:SECTION:linking version="1.0.170" -->
+<!-- SW:SECTION:linking version="1.0.171" -->
 ## Bidirectional Linking
 
 Tasks ↔ User Stories auto-linked via AC-IDs: `AC-US1-01` → `US-001`
@@ -388,7 +374,7 @@ Tasks ↔ User Stories auto-linked via AC-IDs: `AC-US1-01` → `US-001`
 Task format: `**AC**: AC-US1-01, AC-US1-02` (CRITICAL for linking)
 <!-- SW:END:linking -->
 
-<!-- SW:SECTION:mcp version="1.0.170" -->
+<!-- SW:SECTION:mcp version="1.0.171" -->
 ## External Services
 
 **Priority**: CLI tools first (simpler) → MCP for complex integrations
@@ -410,7 +396,7 @@ claude mcp add --transport stdio postgres -- npx -y @modelcontextprotocol/server
 MCP supports lazy-loading (auto mode) - tools load on-demand when >10% context.
 <!-- SW:END:mcp -->
 
-<!-- SW:SECTION:auto version="1.0.170" -->
+<!-- SW:SECTION:auto version="1.0.171" -->
 ## Auto Mode
 
 **Commands**: `/sw:auto` (start) | `/sw:auto-status` (check) | `/sw:cancel-auto` (emergency only)
@@ -427,7 +413,7 @@ MCP supports lazy-loading (auto mode) - tools load on-demand when >10% context.
 **STOP & ASK** if: Spec conflicts | Task unnecessary | Requirement ambiguous
 <!-- SW:END:auto -->
 
-<!-- SW:SECTION:docs version="1.0.170" -->
+<!-- SW:SECTION:docs version="1.0.171" -->
 ## Docs
 
 [spec-weave.com](https://spec-weave.com)
@@ -619,129 +605,94 @@ output_approve_with_context() {
 
 ---
 
-## Skills vs Agents (Automatic vs Explicit)
+## Skills vs Agents (Official Claude Code Behavior)
+
+**Per [official Anthropic documentation](https://code.claude.com/docs/en/skills):**
 
-**SpecWeave provides expertise through Skills (auto-activate) and Agents (explicit spawn).**
+> "Claude uses skills when relevant, or you can invoke one directly with `/skill-name`."
 
-### Skills (Auto-Activate) - YOU DON'T CALL THESE
+### How Skills Work (Two Mechanisms)
 
-Skills activate **automatically** when Claude detects keywords in your prompt. **You never invoke skills directly** - they're loaded transparently when relevant.
+**1. Auto-Activation (Primary)**: Skills auto-activate when their description keywords match user's request.
+**2. Explicit Invocation (Fallback)**: Use Skill tool when auto-activation doesn't trigger.
 
-**How it works:**
 ```
-You: "Design the authentication system architecture"
+User: "Create a React dashboard with Stripe checkout"
       ↓
-Claude detects: "architecture" keyword
+Auto-activation checks skill descriptions for:
+  - "React", "dashboard" → sw-frontend:frontend-architect
+  - "Stripe", "checkout" → sw-payments:stripe-integration
       ↓
-Loads: plugins/specweave/skills/architect/SKILL.md
-      ↓
-Response includes architecture expertise automatically
+If skills load automatically → great!
+If NOT → invoke via Skill tool as fallback
 ```
 
-**Activation rate**: ~20-50% with basic descriptions. Use specific keywords for better activation.
-
-| Domain | Keywords That Activate | Example Prompts |
-|--------|----------------------|-----------------|
-| **Architecture** | architecture, system design, ADR, microservices, API design | "Design the auth system architecture" |
-| **Tech Lead** | code review, best practices, refactoring, clean code | "Review my code for best practices" |
-| **QA Lead** | test strategy, QA, quality gates, E2E testing | "Create a test strategy for this feature" |
-| **Security** | security, OWASP, vulnerabilities, auth security | "Review security of this implementation" |
-| **Docs** | documentation, README, API docs, technical writing | "Write documentation for this API" |
-| **Infrastructure** | Terraform, serverless, Lambda, cloud setup, IaC | "Generate Terraform for this deployment" |
-| **Performance** | optimization, profiling, caching, performance | "Optimize this database query" |
-| **TDD** | TDD, test-driven, red-green-refactor, test-first | "Let's use TDD for this feature" |
-| **PM** | product, requirements, user story, MVP, roadmap | "Help me plan this product feature" |
+### When to Use Skill Tool Explicitly
 
-**Pro tip**: If skills aren't activating, add explicit keywords: "Help me **design the architecture** for..." instead of just "Help me with the backend".
+**Use Skill tool when:**
+- Auto-activation didn't trigger (skill didn't load)
+- You need a specific skill immediately
+- Hook instructions say "SKILL FIRST"
+- Complex multi-domain requests (invoke multiple skills)
 
-### Agents (Task Tool Spawn)
+**Don't force Skill tool when:**
+- Skill already auto-activated (descriptions matched)
+- Simple requests that don't need specialized expertise
 
-For complex, isolated tasks requiring specialized plugins, spawn via Task tool:
+### Plugin Skills Reference
 
-| Domain | Agent (`subagent_type`) | Triggers |
-|--------|-------------------------|----------|
-| **Frontend** | `sw-frontend:frontend-architect` | React, Vue, Next.js, components, UI |
-| **Backend** | `sw-backend:database-optimizer` | API, database, microservices, SQL |
-| **Kubernetes** | `sw-k8s:kubernetes-architect` | K8s, EKS, AKS, GKE, pods, helm, GitOps |
-| **DevOps** | `sw-infra:devops` | Terraform, Docker, CI/CD, AWS, Azure, GCP |
-| **Kafka** | `sw-kafka:kafka-architect` | Kafka, topics, event streaming, MSK |
-| **Confluent** | `sw-confluent:confluent-architect` | Confluent Cloud, Schema Registry, ksqlDB |
+| Domain | Skill Name | Auto-Activates On |
+|--------|------------|-------------------|
+| **Frontend** | `sw-frontend:frontend-architect` | React, Vue, Next.js, dashboard, UI |
+| **Backend .NET** | `sw-backend:dotnet-backend` | .NET, C#, ASP.NET, EF Core, Web API |
+| **Database** | `sw-backend:database-optimizer` | SQL, database, query optimization |
+| **Payments** | `sw-payments:stripe-integration` | Stripe, checkout, payment, subscription |
+| **Kubernetes** | `sw-k8s:kubernetes-architect` | K8s, EKS, AKS, GKE, pods, helm |
+| **DevOps** | `sw-infra:devops` | Terraform, Docker, CI/CD, AWS, Azure |
 | **Mobile** | `sw-mobile:mobile-architect` | React Native, iOS, Android |
-| **ML/AI** | `sw-ml:ml-engineer` | ML, model, training, MLOps |
-| **Data Science** | `sw-ml:data-scientist` | data analysis, notebooks, pandas |
-| **Testing/QA** | `sw-testing:qa-engineer` | E2E, Playwright, Vitest, Jest, QA |
-| **Observability** | `sw-infra:observability-engineer` | monitoring, Prometheus, Grafana, SLOs |
-| **SRE** | `sw-infra:sre` | incidents, outages, production debugging |
-| **Network** | `sw-infra:network-engineer` | networking, VPC, DNS, load balancing |
-| **Diagrams** | `sw-diagrams:diagrams-architect` | Mermaid, C4, architecture diagrams |
-| **Payments** | `sw-payments:payment-integration` | Stripe, PayPal, checkout, PCI |
-| **Release** | `sw-release:release-manager` | release, version, changelog, npm publish |
-| **GitHub** | `sw-github:github-manager` | GitHub issues, PRs, sync |
-| **JIRA** | `sw-jira:jira-manager` | JIRA, epics, stories, sync |
-| **ADO** | `sw-ado:ado-manager` | Azure DevOps, work items |
+| **Testing** | `sw-testing:qa-engineer` | E2E, Playwright, Vitest, Jest |
+| **ML/AI** | `sw-ml:ml-engineer` | ML, model, training, PyTorch |
+| **Architecture** | `sw:architect` | architecture, system design, ADR |
+| **Security** | `sw:security` | security, OWASP, vulnerabilities |
+| **TDD** | `sw:tdd-orchestrator` | TDD, test-driven, red-green-refactor |
 
 ### Usage Pattern
 
 ```typescript
-// Skills auto-activate - just describe what you need (NO explicit call):
-"Design the authentication system architecture"  // → architect skill loads automatically
-"Review my code for security issues"             // → security skill loads automatically
-"Let's use TDD for this feature"                 // → tdd-orchestrator skill loads automatically
-
-// Agents spawn for isolated complex tasks (explicit Task call):
-Task({
-  subagent_type: "sw-k8s:kubernetes-architect:kubernetes-architect",
-  prompt: "Create K8s manifests for a 3-tier web app with Ingress",
-  description: "K8s manifests design"
-})
-```
-
-### ⚠️ Specialized Skills (v1.0.159)
-
-**Domain skills auto-activate on keywords OR can be explicitly invoked via Skill tool:**
-
-| Domain | Keywords That Activate | Explicit Invocation |
-|--------|------------------------|---------------------|
-| React, Vue, Next.js, frontend | "React", "frontend", "dashboard UI" | `/sw-frontend:frontend-architect` |
-| Stripe, payments, checkout | "Stripe", "payments", "checkout" | `/sw-payments:payment-integration` |
-| Kubernetes, Helm, K8s | "Kubernetes", "K8s", "Helm" | `/sw-k8s:kubernetes-architect` |
-| Terraform, AWS, Docker | "Terraform", "AWS", "infrastructure" | `/sw-infra:devops` |
-| Database optimization | "database", "SQL optimization" | `/sw-backend:database-optimizer` |
-| Playwright, E2E tests | "E2E", "Playwright", "QA" | `/sw-testing:qa-engineer` |
-| React Native, mobile | "React Native", "mobile app" | `/sw-mobile:mobile-architect` |
-| ML, PyTorch, TensorFlow | "ML", "machine learning" | `/sw-ml:ml-engineer` |
-
-**How Skills Work:**
-- Skills with `context: fork` run in isolated context (like subagents)
-- Auto-activate when Claude detects keywords in your prompt
-- OR explicitly invoke via Skill tool: `Skill({ skill: "sw-frontend:frontend-architect" })`
-
-**Example - Skills auto-activate:**
-```
-User: "Build React dashboard with Stripe checkout"
-       ↓
-Claude detects: "React", "dashboard" → loads sw-frontend:frontend-architect
-Claude detects: "Stripe", "checkout" → loads sw-payments:payment-integration
-       ↓
-Skills provide specialized expertise automatically
-```
-
-**Explicit invocation (when auto-activation doesn't trigger):**
-```typescript
-Skill({ skill: "sw-frontend:frontend-architect", args: "Build dashboard with sidebar" })
-Skill({ skill: "sw-payments:payment-integration", args: "Stripe checkout flow" })
+// Scenario 1: Auto-activation works (most cases)
+// User says: "Design the auth architecture"
+// → sw:architect auto-loads via keyword "architecture"
+// → Just respond with architectural guidance
+
+// Scenario 2: Auto-activation didn't trigger
+// User says: "Build .NET API" but skill didn't load
+// → Explicitly invoke:
+Skill({ skill: "sw-backend:dotnet-backend", args: "Build API..." })
+
+// Scenario 3: Multi-domain request (invoke both)
+// User says: "React dashboard with Stripe"
+Skill({ skill: "sw-frontend:frontend-architect", args: "dashboard" })
+Skill({ skill: "sw-payments:stripe-integration", args: "Stripe" })
 ```
 
+### Troubleshooting Auto-Activation
+
+If skills don't auto-activate:
+1. Check skill description includes keywords user would naturally say
+2. Verify skill appears in `/plugin list`
+3. Try rephrasing request to match description
+4. **Fallback**: Invoke directly with `Skill({ skill: "name" })`
+
 ### When to Use What
 
-| Scenario | Approach | How |
-|----------|----------|-----|
-| Architecture decisions | Skills (auto) | Keywords trigger automatically |
-| Code review, security | Skills (auto) | Keywords trigger automatically |
-| Implementation work | Skills (auto/explicit) | Auto-activates OR use Skill tool |
-| External syncs | Commands | Use `/sw-github:sync` etc. |
-| General exploration | Task tool | `subagent_type: "Explore"` |
-| Complex planning | Task tool | `subagent_type: "Plan"` |
+| Scenario | Approach |
+|----------|----------|
+| Domain work (React, .NET, Stripe) | Let auto-activate, Skill tool if not |
+| Architecture, security review | Usually auto-activates on keywords |
+| Hook says "SKILL FIRST" | **Always** use Skill tool explicitly |
+| External syncs | Commands: `/sw-github:sync` |
+| Codebase exploration | Task tool: `subagent_type: "Explore"` |
+| Complex planning | Task tool: `subagent_type: "Plan"` |
 
 **Reference**: See `plugins/PLUGINS-INDEX.md` for full plugin catalog with triggers.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "specweave",
-  "version": "1.0.171",
+  "version": "1.0.172",
   "description": "Spec-driven development framework for Claude Code. AI-native workflow with living documentation, intelligent agents, and multilingual support (9 languages). Enterprise-grade traceability with permanent specs and temporary increments.",
   "type": "module",
   "main": "dist/index.js",

package/plugins/PLUGINS-INDEX.md

@@ -2,7 +2,7 @@
 
 **Purpose**: Lightweight plugin manifest for progressive disclosure. Load plugin content only when triggers match.
 
-**Total Plugins**: 23 | **Last Updated**: 2026-01-19
+**Total Plugins**: 23 | **Last Updated**: 2026-01-26
 
 ---
 
@@ -19,7 +19,7 @@
 
 | Plugin | Triggers | Description |
 |--------|----------|-------------|
-| **specweave** | increment, feature, plan, spec, tasks, TDD, PM, architect | Core framework. Planning, specs, TDD, living docs. |
+| **specweave** | increment, feature, plan, spec, tasks, TDD, PM, architect, image, generate image, illustration, icon, logo, banner, mockup | Core framework. Planning, specs, TDD, living docs, image generation. |
 
 ## Integration Plugins
 
@@ -100,7 +100,7 @@
 
 | Plugin | Merged Into | Notes |
 |--------|-------------|-------|
-| ~~specweave-ui~~ | specweave-testing | Browser automation, UI inspection, visual regression now in testing |
+| ~~specweave-ui~~ | specweave-testing, specweave | Browser automation, UI inspection, visual regression now in testing. Image generation moved to core specweave. |
 | ~~specweave-release~~ | specweave (core) | `/sw:npm` now in core |
 | ~~specweave-diagrams~~ | specweave (core) | Mermaid, C4 diagrams now in core |
 | ~~specweave-docs~~ | specweave (core) | Documentation skills now in core |
@@ -121,6 +121,8 @@
 | "ML pipeline" | `specweave-ml` |
 | "Write E2E tests" | `specweave-testing` |
 | "Create release" | `specweave-release` |
+| "Generate an image" | `specweave` |
+| "Create hero image" | `specweave` |
 
 ---
 

package/plugins/SKILLS-VS-AGENTS.md

@@ -101,13 +101,20 @@ All run in isolated context without polluting the main conversation.
 
 **What happens:**
 1. Claude detects keywords: "React", "dashboard", "Stripe", "checkout"
-2. Skills auto-activate:
+2. Skills auto-activate (primary mechanism):
    - `sw-frontend:frontend-architect` (React, dashboard)
    - `sw-payments:payment-integration` (Stripe, checkout)
 3. Each skill runs in isolated context (`context: fork`)
 4. Results return to main conversation
 
-**No Task tool calls needed!** Skills activate automatically.
+**Two invocation methods** (per [official docs](https://code.claude.com/docs/en/skills)):
+1. **Auto-activation** (primary): Keywords in skill description trigger automatic loading
+2. **Explicit invocation** (fallback): Use Skill tool or `/skill-name` when auto-activation doesn't trigger
+
+```typescript
+// If auto-activation didn't work, explicitly invoke:
+Skill({ skill: "sw-frontend:frontend-architect", args: "dashboard" })
+```
 
 ## Migration Complete
 
@@ -144,7 +151,11 @@ plugins/specweave-frontend/
 **A:** Claude Code expects flat files (`agents/<name>.md`), but SpecWeave had subfolder structure (`agents/<name>/AGENT.md`). Skills don't have this limitation.
 
 ### Q: How do I invoke a skill explicitly?
-**A:** Use `/plugin:skill-name`, e.g., `/sw-frontend:frontend-architect`. But usually just describe what you need - skills auto-activate on keywords.
+**A:** Two ways:
+1. **User**: Type `/sw-frontend:frontend-architect` in chat
+2. **Claude**: Use `Skill({ skill: "sw-frontend:frontend-architect" })` when auto-activation didn't trigger
+
+Usually just describe what you need - skills auto-activate on keywords. Use explicit invocation as fallback.
 
 ### Q: What about parallel execution?
 **A:** Built-in subagents can run in parallel via multiple Task tool calls. Skills with `context: fork` also run in isolated contexts, so multiple can activate without conflict.

package/plugins/specweave/COMMANDS.md

@@ -131,7 +131,7 @@ SpecWeave plugins provide additional namespaced commands:
 | **Docs** | `/sw-docs:*` | init, generate, build, view, validate, organize |
 | **Frontend** | `/sw-frontend:*` | component-generate, design-system-init, frontend-scaffold |
 | **Backend** | `/sw-backend:*` | api-scaffold, crud-generate, migration-generate |
-| **Kubernetes** | `/sw-kubernetes:*` | cluster-setup, deployment-generate, helm-scaffold |
+| **Kubernetes** | `/sw-k8s:*` | cluster-setup, deployment-generate, helm-scaffold |
 | **Testing** | `/sw-testing:*` | e2e-setup, test-coverage, test-generate, test-init |
 | **Infrastructure** | `/sw-infra:*` | monitor-setup, slo-implement |
 | **Kafka** | `/sw-kafka:*` | deploy, dev-env, monitor-setup, mcp-configure |

package/plugins/specweave/hooks/user-prompt-submit.sh

@@ -496,41 +496,20 @@ Task({
                       ESCAPED_PROMPT=$(printf '%s' "$PROMPT" | sed 's/\\/\\\\/g; s/"/\\"/g; s/	/\\t/g' | tr '\n' ' ')
 
                       MSG="${AUTOLOAD_PREFIX}╔══════════════════════════════════════════════════════════════════════════════╗
-║  🎯 MANDATORY SKILL INVOCATION - INCREMENT REQUIRED BEFORE IMPLEMENTATION     ║
+║  🎯 SKILL FIRST - Call Skill tool BEFORE implementation                      ║
 ╚══════════════════════════════════════════════════════════════════════════════╝
 
-<system>
-<rules>
-BLOCKING RULE: Your FIRST action MUST be invoking the Skill tool. No exceptions.
-</rules>
-</system>
-
-┌──────────────────────────────────────────────────────────────────────────────┐
-│  ⛔ YOU ARE BLOCKED FROM THE FOLLOWING ACTIONS:                              │
-├──────────────────────────────────────────────────────────────────────────────┤
-│  ❌ Write tool      - BLOCKED (cannot create files)                          │
-│  ❌ Edit tool       - BLOCKED (cannot modify files)                          │
-│  ❌ Bash tool       - BLOCKED (no implementation commands)                   │
-│  ❌ Exploring code  - BLOCKED (no 'let me first understand')                 │
-│  ❌ Planning        - BLOCKED (skill does the planning)                      │
-└──────────────────────────────────────────────────────────────────────────────┘
-
-┌──────────────────────────────────────────────────────────────────────────────┐
-│  ✅ YOUR ONLY ALLOWED ACTION (do this NOW):                                  │
-├──────────────────────────────────────────────────────────────────────────────┤
-│  Call the Skill tool EXACTLY as shown below. Nothing else first.             │
-└──────────────────────────────────────────────────────────────────────────────┘
-
+**Your FIRST tool call must be:**
 \\\`\\\`\\\`
 Skill({ skill: \\\"sw:increment-planner\\\", args: \\\"${ESCAPED_PROMPT}\\\" })
 \\\`\\\`\\\`
 
-**Detection**: Feature request (confidence: ${INC_CONF})
-**Reason**: ${INC_REASON}
+**Order matters:**
+1. ✅ Call Skill tool FIRST (as shown above)
+2. ✅ THEN proceed with implementation normally
 
-════════════════════════════════════════════════════════════════════════════════
-**Claude: Your FIRST tool call MUST be Skill. Not Read. Not Glob. Not Bash. Skill.**
-════════════════════════════════════════════════════════════════════════════════${AGENT_DIRECTIVE}"
+**Detection**: Feature request (confidence: ${INC_CONF})
+**Reason**: ${INC_REASON}${AGENT_DIRECTIVE}"
                       output_approve_with_context "$MSG"
                       exit 0
                     else

package/plugins/specweave/skills/SKILLS-INDEX.md

@@ -2,7 +2,7 @@
 
 **Purpose**: Lightweight skill manifest for lazy loading. Load SKILL.md only when triggers match.
 
-**Total Skills**: 30 | **Last Updated**: 2026-01-13
+**Total Skills**: 31 | **Last Updated**: 2026-01-26
 
 ---
 
@@ -75,6 +75,12 @@
 | **compliance-architecture** | compliance, HIPAA, SOC2, SOC 2, GDPR, PCI-DSS, regulatory, healthcare data, payment card, audit, security standards | `skills/compliance-architecture/SKILL.md` |
 | **service-connect** | connect database, supabase connection, cloudflare workers, wrangler, postgres connection, mongodb atlas, redis cache, MCP setup, service integration, connection failed, IPv6, database setup | `skills/service-connect/SKILL.md` |
 
+### Creative & Media
+
+| Skill | Triggers | Location |
+|-------|----------|----------|
+| **image-generation** | image, images, generate image, create image, picture, illustration, icon, logo, hero image, banner, background, placeholder, mockup, avatar, thumbnail, splash screen, app icon, website image, landing page, UI image, design asset, Pollinations, AI image, text-to-image, FLUX, empty state illustration, feature graphic | `skills/image-generation/SKILL.md` |
+
 ---
 
 ## Quick Lookup Table
@@ -97,6 +103,8 @@
 | "TypeScript/Python code navigation" | `lsp-integration` |
 | "Connect to Supabase/DB" | `service-connect` |
 | "Connection failed" | `service-connect` |
+| "Generate an image" / "Create illustration" | `image-generation` |
+| "Hero image" / "App icon" / "Mockup" | `image-generation` |
 
 ---
 

package/plugins/specweave/skills/docs-writer/SKILL.md

@@ -199,7 +199,7 @@ dependencies:
 
 ## Image Generation
 
-When documentation needs visuals (diagrams, illustrations, icons), use the `/sw-ui:image` skill:
+When documentation needs visuals (diagrams, illustrations, icons), use the `/sw:image-generation` skill:
 
 ```
 "Generate a hero image for the authentication documentation"

package/plugins/specweave/skills/image-generation/MEMORY.md

@@ -0,0 +1,7 @@
+# Image Generation Skill Memory
+
+<!-- Auto-captured learnings. Edit or delete as needed. -->
+
+## Learnings
+
+<!-- No learnings captured yet -->