specweave 1.0.99 → 1.0.101

package/CLAUDE.md

@@ -1,10 +1,10 @@
-<!-- SW:META template="claude" version="1.0.98" sections="header,start,autodetect,metarule,rules,workflow,reflect,context,lsp,structure,taskformat,secrets,syncing,mapping,testing,api,limits,troubleshooting,principles,linking,mcp,autoexecute,auto,docs" -->
+<!-- SW:META template="claude" version="1.0.99" sections="header,start,autodetect,metarule,rules,workflow,reflect,context,lsp,structure,taskformat,secrets,syncing,mapping,testing,api,limits,troubleshooting,principles,linking,mcp,autoexecute,auto,docs" -->
 
-<!-- SW:SECTION:header version="1.0.98" -->
+<!-- SW:SECTION:header version="1.0.99" -->
 **Framework**: SpecWeave | **Truth**: `spec.md` + `tasks.md`
 <!-- SW:END:header -->
 
-<!-- SW:SECTION:start version="1.0.98" -->
+<!-- SW:SECTION:start version="1.0.99" -->
 ## Getting Started
 
 **Initial increment**: `0001-project-setup` (auto-created by `specweave init`)
@@ -14,7 +14,7 @@
 2. **Customize**: Edit spec.md and use for setup tasks
 <!-- SW:END:start -->
 
-<!-- SW:SECTION:autodetect version="1.0.98" -->
+<!-- SW:SECTION:autodetect version="1.0.99" -->
 ## Auto-Detection
 
 SpecWeave auto-detects product descriptions and routes to `/sw:increment`:
@@ -24,7 +24,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.98" -->
+<!-- SW:SECTION:metarule version="1.0.99" -->
 ## Meta-Rule: Think-Before-Act
 
 **Satisfy dependencies BEFORE dependent operations.**
@@ -35,7 +35,7 @@ SpecWeave auto-detects product descriptions and routes to `/sw:increment`:
 ```
 <!-- SW:END:metarule -->
 
-<!-- SW:SECTION:rules version="1.0.98" -->
+<!-- SW:SECTION:rules version="1.0.99" -->
 ## Rules
 
 1. **Files** → `.specweave/increments/####-name/` (spec.md, plan.md, tasks.md at root; reports/, scripts/, logs/ subfolders)
@@ -45,9 +45,10 @@ SpecWeave auto-detects product descriptions and routes to `/sw:increment`:
 5. **Root clean**: NEVER create .md/reports/scripts in project root → use increment folders
 6. **⛔ Increment cleanliness**: ONLY 4 files at increment root (metadata.json, spec.md, plan.md, tasks.md). ALL other .md files → `reports/`, logs → `logs/`, scripts → `scripts/`
 7. **⛔ Initialization guard**: `.specweave/` folders MUST ONLY exist where `specweave init` was run. NEVER create `.specweave/` in parent, nested, or unrelated directories. Check `config.json` exists before creating ANY `.specweave/` subfolders.
+8. **⛔ Marketplace refresh**: ALWAYS use `specweave refresh-marketplace` CLI command. NEVER suggest `scripts/refresh-marketplace.sh` - end users don't have the scripts folder (npm global install).
 <!-- SW:END:rules -->
 
-<!-- SW:SECTION:workflow version="1.0.98" -->
+<!-- SW:SECTION:workflow version="1.0.99" -->
 ## Workflow
 
 `/sw:increment "X"` → `/sw:do` → `/sw:progress` → `/sw:done 0001`
@@ -67,7 +68,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.98" -->
+<!-- SW:SECTION:reflect version="1.0.99" -->
 ## Self-Improving Skills (Reflect)
 
 **Learn once, never repeat.** Claude learns from corrections and patterns across sessions.
@@ -111,7 +112,7 @@ ls ~/.specweave/memory/*.md 2>/dev/null
 **Enable auto-learning**: `/sw:reflect-on` → Stop hook analyzes sessions automatically
 <!-- SW:END:reflect -->
 
-<!-- SW:SECTION:context version="1.0.98" -->
+<!-- SW:SECTION:context version="1.0.99" -->
 ## Living Docs Context
 
 **Before implementing features**: Check existing docs for patterns and decisions.
@@ -131,7 +132,7 @@ grep -ril "keyword" .specweave/docs/internal/
 **Use `/sw:context <topic>`** to load relevant living docs into conversation.
 <!-- SW:END:context -->
 
-<!-- SW:SECTION:lsp version="1.0.98" -->
+<!-- SW:SECTION:lsp version="1.0.99" -->
 ## LSP-Enhanced Exploration
 
 **USE LSP ACTIVELY** for semantic code understanding (100x faster than grep).
@@ -148,7 +149,7 @@ go install golang.org/x/tools/gopls@latest  # Go
 **Best Practices**: ALWAYS use `findReferences` before refactoring | Use `goToDefinition` instead of grep | Combine with Explore agent
 <!-- SW:END:lsp -->
 
-<!-- SW:SECTION:structure version="1.0.98" -->
+<!-- SW:SECTION:structure version="1.0.99" -->
 ## Structure
 
 ```
@@ -218,7 +219,7 @@ my-project/
 ```
 <!-- SW:END:structure -->
 
-<!-- SW:SECTION:taskformat version="1.0.98" -->
+<!-- SW:SECTION:taskformat version="1.0.99" -->
 ## Task Format
 
 ```markdown
@@ -228,7 +229,7 @@ my-project/
 ```
 <!-- SW:END:taskformat -->
 
-<!-- SW:SECTION:secrets version="1.0.98" -->
+<!-- SW:SECTION:secrets version="1.0.99" -->
 ## Secrets Check
 
 **BEFORE CLI tools**: Check existing config first!
@@ -239,7 +240,7 @@ gh auth status
 ```
 <!-- SW:END:secrets -->
 
-<!-- SW:SECTION:syncing version="1.0.98" -->
+<!-- SW:SECTION:syncing version="1.0.99" -->
 ## External Sync (GitHub/JIRA/ADO)
 
 **After increment creation**: Run `/sw-github:sync {id}` to create issues!
@@ -267,7 +268,7 @@ Living docs sync ≠ External sync. They are separate:
 **Verify tokens**: `grep GITHUB_TOKEN .env` | `gh auth status`
 <!-- SW:END:syncing -->
 
-<!-- SW:SECTION:mapping version="1.0.98" -->
+<!-- SW:SECTION:mapping version="1.0.99" -->
 ## GitHub Mapping
 
 | SpecWeave | GitHub |
@@ -277,7 +278,7 @@ Living docs sync ≠ External sync. They are separate:
 | Task T-XXX | Checkbox |
 <!-- SW:END:mapping -->
 
-<!-- SW:SECTION:testing version="1.0.98" -->
+<!-- SW:SECTION:testing version="1.0.99" -->
 ## Testing
 
 BDD in tasks.md | Unit >80% | `.test.ts` (Vitest)
@@ -289,7 +290,7 @@ vi.mock('fs', () => ({ readFile: vi.fn() }));
 ```
 <!-- SW:END:testing -->
 
-<!-- SW:SECTION:api version="1.0.98" -->
+<!-- SW:SECTION:api version="1.0.99" -->
 ## API Development (OpenAPI-First)
 
 **For API projects only.** OpenAPI = source of truth → Postman derived from it.
@@ -308,18 +309,19 @@ vi.mock('fs', () => ({ readFile: vi.fn() }));
 **Import**: Postman → Import collection + env → Fill secrets → Select env
 <!-- SW:END:api -->
 
-<!-- SW:SECTION:limits version="1.0.98" -->
+<!-- SW:SECTION:limits version="1.0.99" -->
 ## Limits
 
 **Max 1500 lines/file** — extract before adding
 <!-- SW:END:limits -->
 
-<!-- SW:SECTION:troubleshooting version="1.0.98" -->
+<!-- SW:SECTION:troubleshooting version="1.0.99" -->
 ## Troubleshooting
 
 | Issue | Fix |
 |-------|-----|
 | Skills missing | Restart Claude Code |
+| Plugins outdated | `specweave refresh-marketplace` (NEVER use `scripts/refresh-marketplace.sh` - that's for contributors only!) |
 | Commands gone | `/plugin list --installed` |
 | Out of sync | `/sw:sync-tasks` |
 | Find increment | `/sw:status` |
@@ -333,7 +335,7 @@ vi.mock('fs', () => ({ readFile: vi.fn() }));
 | Path patterns not working | `//path` = absolute, `/path` = relative to settings file, `additionalDirectories` for explicit working dirs |
 <!-- SW:END:troubleshooting -->
 
-<!-- SW:SECTION:principles version="1.0.98" -->
+<!-- SW:SECTION:principles version="1.0.99" -->
 ## Principles
 
 1. **Spec-first**: `/sw:increment` before coding
@@ -343,7 +345,7 @@ vi.mock('fs', () => ({ readFile: vi.fn() }));
 5. **Clean**: All files in increment folders
 <!-- SW:END:principles -->
 
-<!-- SW:SECTION:linking version="1.0.98" -->
+<!-- SW:SECTION:linking version="1.0.99" -->
 ## Bidirectional Linking
 
 Tasks ↔ User Stories auto-linked via AC-IDs: `AC-US1-01` → `US-001`
@@ -351,7 +353,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.98" -->
+<!-- SW:SECTION:mcp version="1.0.99" -->
 ## External Service Connection
 
 **Priority**: MCP Server → REST API → CLI → Direct Connection
@@ -375,7 +377,7 @@ wrangler whoami 2>/dev/null
 ```
 <!-- SW:END:mcp -->
 
-<!-- SW:SECTION:autoexecute version="1.0.98" -->
+<!-- SW:SECTION:autoexecute version="1.0.99" -->
 ## Auto-Execute Rule
 
 **NEVER** output "Manual Step Required" when credentials exist. **EXECUTE DIRECTLY.**
@@ -389,7 +391,7 @@ wrangler whoami 2>/dev/null && gh auth status 2>/dev/null
 ```
 <!-- SW:END:autoexecute -->
 
-<!-- SW:SECTION:auto version="1.0.98" -->
+<!-- SW:SECTION:auto version="1.0.99" -->
 ## Auto Mode (Autonomous Execution)
 
 **Continuous execution until all tasks complete.**
@@ -466,7 +468,7 @@ wrangler whoami 2>/dev/null && gh auth status 2>/dev/null
 **Circuit Breaker**: External API fails 3x? Queue & continue
 <!-- SW:END:auto -->
 
-<!-- SW:SECTION:docs version="1.0.98" -->
+<!-- SW:SECTION:docs version="1.0.99" -->
 ## Docs
 
 [spec-weave.com](https://spec-weave.com) | `.specweave/docs/internal/`
@@ -667,65 +669,71 @@ project-root/
 
 ---
 
-## Proactive Agent Usage (USE THE EXPERTS!)
+## Skills vs Agents (Automatic vs Explicit)
 
-**SpecWeave has 40+ specialized agents. USE THEM instead of doing domain work directly!**
+**SpecWeave provides expertise through Skills (auto-activate) and Agents (explicit spawn).**
 
-When the user's request involves specialized domains, **spawn the appropriate agent** via Task tool:
+### Skills (Auto-Activate)
 
-### Agent Quick Reference
+Skills activate automatically based on keywords in user prompts. No action needed.
+
+| Domain | Skill | Auto-Activates For |
+|--------|-------|-------------------|
+| **Architecture** | `sw:architect` | system design, ADR, technical design, patterns |
+| **Tech Lead** | `sw:tech-lead` | code review, best practices, refactoring |
+| **QA Lead** | `sw:qa-lead` | test strategy, QA, quality gates |
+| **Security** | `sw:security` | security review, OWASP, auth, vulnerabilities |
+| **Docs** | `sw:docs-writer` | documentation, README, API docs |
+| **Infrastructure** | `sw:infrastructure` | Terraform IaC, serverless, cloud setup |
+| **Performance** | `sw:performance` | optimization, profiling, caching |
+| **TDD** | `sw:tdd-orchestrator` | TDD, red-green-refactor, test-first |
+| **PM** | `sw:pm` | product planning, roadmap, requirements |
+
+### Agents (Task Tool Spawn)
+
+For complex, isolated tasks requiring specialized plugins, spawn via Task tool:
 
 | Domain | Agent (`subagent_type`) | Triggers |
 |--------|-------------------------|----------|
-| **Architecture** | `specweave:architect:architect` | system design, ADR, technical design, patterns |
-| **Frontend** | `specweave-frontend:frontend-architect:frontend-architect` | React, Vue, Next.js, components, UI |
-| **Backend** | `specweave-backend:database-optimizer:database-optimizer` | API, database, microservices, SQL |
-| **Kubernetes** | `specweave-kubernetes:kubernetes-architect:kubernetes-architect` | K8s, EKS, AKS, GKE, pods, helm, GitOps |
-| **Infrastructure** | `specweave-infrastructure:devops:devops` | Terraform, Docker, CI/CD, AWS, Azure, GCP |
-| **Kafka** | `specweave-kafka:kafka-architect:kafka-architect` | Kafka, topics, event streaming, MSK |
-| **Confluent** | `specweave-confluent:confluent-architect:confluent-architect` | Confluent Cloud, Schema Registry, ksqlDB |
-| **Mobile** | `specweave-mobile:mobile-architect:mobile-architect` | React Native, iOS, Android |
-| **ML/AI** | `specweave-ml:ml-engineer:ml-engineer` | ML, model, training, MLOps |
-| **Data Science** | `specweave-ml:data-scientist:data-scientist` | data analysis, notebooks, pandas |
-| **Testing/QA** | `specweave-testing:qa-engineer:qa-engineer` | E2E, Playwright, Vitest, Jest, QA |
-| **Security** | `specweave:security:security` | security review, OWASP, auth, vulnerabilities |
-| **Performance** | `specweave-infrastructure:performance-engineer:performance-engineer` | optimization, profiling, caching |
-| **Observability** | `specweave-infrastructure:observability-engineer:observability-engineer` | monitoring, Prometheus, Grafana, SLOs |
-| **SRE** | `specweave-infrastructure:sre:sre` | incidents, outages, production debugging |
-| **Network** | `specweave-infrastructure:network-engineer:network-engineer` | networking, VPC, DNS, load balancing |
-| **Diagrams** | `specweave-diagrams:diagrams-architect:diagrams-architect` | Mermaid, C4, architecture diagrams |
-| **Payments** | `specweave-payments:payment-integration:payment-integration` | Stripe, PayPal, checkout, PCI |
-| **Docs** | `specweave:docs-writer:docs-writer` | documentation, README, API docs |
-| **Release** | `specweave-release:release-manager:release-manager` | release, version, changelog, npm publish |
-| **GitHub** | `specweave-github:github-manager:github-manager` | GitHub issues, PRs, sync |
-| **JIRA** | `specweave-jira:jira-manager:jira-manager` | JIRA, epics, stories, sync |
-| **ADO** | `specweave-ado:ado-manager:ado-manager` | Azure DevOps, work items |
+| **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 |
+| **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 |
 
 ### Usage Pattern
 
 ```typescript
-// ❌ WRONG: Doing K8s/infra/frontend work directly
-"Let me write the Kubernetes manifests..."
+// Skills auto-activate - just describe what you need:
+"Design the authentication system architecture"  // → sw:architect activates
+"Review my code for security issues"             // → sw:security activates
 
-// ✅ CORRECT: Spawn the expert agent
+// Agents spawn for isolated complex tasks:
 Task({
-  subagent_type: "specweave-kubernetes:kubernetes-architect:kubernetes-architect",
+  subagent_type: "sw-k8s:kubernetes-architect",
   prompt: "Create K8s manifests for a 3-tier web app with Ingress",
   description: "K8s manifests design"
 })
 ```
 
-### When to Use Agents
-
-- **ANY architecture decisions** → `specweave:architect:architect`
-- **Infrastructure/DevOps code** → `specweave-infrastructure:devops:devops`
-- **K8s manifests/GitOps** → `specweave-kubernetes:kubernetes-architect:kubernetes-architect`
-- **Frontend components** → `specweave-frontend:frontend-architect:frontend-architect`
-- **Test strategy/E2E** → `specweave-testing:qa-engineer:qa-engineer`
-- **Security review** → `specweave:security:security`
-- **Performance tuning** → `specweave-infrastructure:performance-engineer:performance-engineer`
+### When to Use What
 
-**Rule**: If a plugin/agent exists for the domain, USE IT. Don't reinvent expertise.
+- **Skills** (auto): Architecture decisions, code review, security review, documentation
+- **Agents** (Task tool): Complex K8s/infra, frontend architecture, ML pipelines, external syncs
 
 **Reference**: See `plugins/PLUGINS-INDEX.md` for full plugin catalog with triggers.
 

package/README.md

@@ -15,7 +15,7 @@
 npm install -g specweave
 ```
 
-> **New in v1.0.63**: Auto mode can now run for hours — tested and proven. Mobile app generation, multi-repo coordination, E2E tests running automatically.
+> **New in v1.0.100**: Auto mode now shows live labels in your terminal — see exactly what SpecWeave is doing: `[Planning]`, `[Implementing]`, `[Testing]`, `[Fixing]`. Hours of autonomous execution with full visibility.
 
 ---
 
@@ -39,8 +39,19 @@ Every AI coding tool promises productivity. But after the chat ends:
 
 ```bash
 /sw:increment "Add OAuth authentication"  # Creates spec + plan + tasks
-/sw:auto                                   # 🚀 Autonomous execution for HOURS
-# ↑ This can run for hours, executing tasks, running tests, fixing failures
+/sw:auto                                   # Autonomous execution for HOURS
+# ↑ Watch live: [Planning] → [Implementing] → [Testing] → [Fixing] → [Done]
+```
+
+**What happens during `/sw:auto`:**
+```
+[08:23:41] [Planning]      Analyzing T-003: Implement refresh token rotation
+[08:24:12] [Implementing]  Writing src/auth/token-manager.ts (127 lines)
+[08:25:33] [Testing]       Running npm test -- token-manager.test.ts
+[08:25:47] [Fixing]        Test failed: Expected 401, got 403. Adjusting...
+[08:26:15] [Testing]       Re-running tests... PASSED
+[08:26:18] [Syncing]       Updating tasks.md, pushing to GitHub
+[08:26:22] [Done]          T-003 complete. Moving to T-004...
 ```
 
 **Or step-by-step control:**
@@ -53,30 +64,32 @@ Every AI coding tool promises productivity. But after the chat ends:
 
 ```
 .specweave/increments/0001-oauth/
-├── spec.md    ← WHAT: User stories, acceptance criteria
-├── plan.md    ← HOW: Architecture decisions, tech choices
-└── tasks.md   ← DO: Implementation tasks with embedded tests
+├── spec.md    <- WHAT: User stories, acceptance criteria
+├── plan.md    <- HOW: Architecture decisions, tech choices
+└── tasks.md   <- DO: Implementation tasks with embedded tests
 ```
 
-**After 6 months**: Search "OAuth" → find exact decisions, who approved, why it was built that way.
+**After 6 months**: Search "OAuth" -> find exact decisions, who approved, why it was built that way.
 
 ---
 
 ## Why SpecWeave vs BMAD, SpecKit, Cursor Rules?
 
-| | [BMAD](https://github.com/bmad-code-org/BMAD-METHOD) | [SpecKit](https://github.com/github/spec-kit) | Cursor Rules | **SpecWeave** |
+| Capability | [BMAD](https://github.com/bmad-code-org/BMAD-METHOD) | [SpecKit](https://github.com/github/spec-kit) | Cursor Rules | **SpecWeave** |
 |---|---|---|---|---|
-| **Status** | Alpha (v6) | Stable | Built-in | **Production (v1.0.62)** |
-| **Autonomous** | ❌ Manual steps | ❌ One-shot | ❌ Per-request | **✅ Hours of autonomous work** |
-| **Multi-Repo** | ❌ Single repo | ❌ Single repo | ❌ Single repo | **✅ Coordinate multiple repos** |
-| **Mobile Apps** | ❌ No agents | ❌ No agents | ❌ No agents | **✅ React Native/Expo specialist** |
-| **External Sync** | ❌ None | ❌ None | ❌ None | **✅ GitHub/JIRA/ADO bidirectional** |
-| **Brownfield** | Limited | Greenfield only | Any | **✅ 10-year legacy? Fine.** |
-| **Quality Gates** | Not built-in | None | None | **✅ 3-gate (tasks/tests/docs)** |
-| **Living Docs** | Manual | Snapshot | None | **✅ Auto-update on every task** |
-| **Dogfooding** | Unknown | Unknown | N/A | **✅ 140+ self-built features** |
-
-**The math**: SpecKit output = ONE SpecWeave increment. SpecWeave = N increments + lifecycle + sync + hooks + **autonomous execution**.
+| **Maturity** | Alpha (v6) | Stable | Built-in | **Production (v1.0.100)** |
+| **Autonomous Work** | Manual steps required | One-shot generation | Per-request only | **Hours unattended** |
+| **Live Status** | None | None | None | **Terminal labels** |
+| **Multi-Repo** | Single repo | Single repo | Single repo | **Coordinate N repos** |
+| **Mobile Apps** | No agents | No agents | No agents | **React Native/Expo** |
+| **External Sync** | None | None | None | **GitHub/JIRA/ADO** |
+| **Brownfield** | Limited | Greenfield only | Any | **10-year legacy? Fine.** |
+| **Quality Gates** | Not built-in | None | None | **3-gate validation** |
+| **Living Docs** | Manual | Snapshot | None | **Auto-update** |
+| **Self-Learning** | None | None | None | **Reflects on mistakes** |
+| **Dogfooding** | Unknown | Unknown | N/A | **140+ self-built features** |
+
+**The math**: SpecKit output = ONE SpecWeave increment. SpecWeave = N increments + lifecycle + sync + hooks + **hours of autonomous execution**.
 
 ---
 
@@ -96,7 +109,7 @@ Every AI coding tool promises productivity. But after the chat ends:
 | DORA metrics | Live tracking |
 | Test coverage | 60%+ enforced |
 
-**[Browse our increments →](https://github.com/anton-abyzov/specweave/tree/develop/.specweave/increments)**
+**[Browse our increments ->](https://github.com/anton-abyzov/specweave/tree/develop/.specweave/increments)**
 
 ---
 
@@ -114,7 +127,7 @@ node --version
 nvm install 22 && nvm use 22 && nvm alias default 22
 ```
 
-> ⚠️ **Getting `SyntaxError: Unexpected token 'with'`?** Your Node.js is too old. See [upgrade instructions](https://spec-weave.com/docs/guides/troubleshooting/common-errors#node-version-error).
+> **Getting `SyntaxError: Unexpected token 'with'`?** Your Node.js is too old. See [upgrade instructions](https://spec-weave.com/docs/guides/troubleshooting/common-errors#node-version-error).
 
 ### Installation
 
@@ -127,7 +140,7 @@ specweave init .
 Then in Claude Code:
 ```bash
 /sw:increment "Add dark mode"  # AI creates spec + plan + tasks
-/sw:auto                       # 🚀 Ship while you sleep (hours of autonomous work)
+/sw:auto                       # Ship while you sleep (hours of autonomous work)
 ```
 
 **Or step-by-step:**
@@ -142,12 +155,30 @@ specweave refresh-marketplace   # Reinstall all plugins from GitHub
 specweave update-instructions   # Regenerate CLAUDE.md
 ```
 
-**[Full Quickstart Guide →](https://spec-weave.com/docs/guides/getting-started/quickstart)**
+**[Full Quickstart Guide ->](https://spec-weave.com/docs/guides/getting-started/quickstart)**
 
 ---
 
 ## Key Features
 
+### Autonomous Execution (v2.9)
+
+Run for hours without intervention. See exactly what's happening:
+
+```bash
+/sw:auto                  # Start autonomous mode
+/sw:auto-status           # Check progress anytime
+/sw:cancel-auto           # Emergency stop (rarely needed)
+```
+
+**What you see in terminal:**
+- `[Planning]` - Analyzing task requirements
+- `[Implementing]` - Writing code
+- `[Testing]` - Running test suites
+- `[Fixing]` - Auto-correcting failures
+- `[Syncing]` - Updating docs and external tools
+- `[Done]` - Task complete, moving to next
+
 ### External Tool Integration
 
 | Platform | Capabilities |
@@ -199,14 +230,14 @@ Three gates before any increment closes:
 | Command | Purpose |
 |---------|---------|
 | `/sw:increment "feature"` | Create spec + plan + tasks |
-| `/sw:auto` | 🚀 **Ship while you sleep** - hours of autonomous work |
+| `/sw:auto` | **Ship while you sleep** - hours of autonomous work |
+| `/sw:auto-status` | Check autonomous session progress |
 | `/sw:do` | Execute one task at a time |
 | `/sw:done 0001` | Close with quality validation |
 | `/sw:sync-progress` | Push to GitHub/JIRA/ADO |
-| `/sw:auto-status` | Check autonomous session progress |
 | `/sw:cancel-auto` | Stop autonomous session |
 
-**[53 total commands →](https://spec-weave.com/docs/commands/overview)**
+**[53 total commands ->](https://spec-weave.com/docs/commands/overview)**
 
 ---
 
@@ -214,9 +245,9 @@ Three gates before any increment closes:
 
 | Scenario | What You Do |
 |----------|-------------|
-| **10-year legacy codebase** | `specweave init .` → brownfield analysis detects doc gaps |
-| **Weekend MVP** | `specweave init .` → `/sw:increment "Build auth"` |
-| **50-team enterprise** | `specweave init .` → `/sw:enable-multiproject` → maps to JIRA/ADO |
+| **10-year legacy codebase** | `specweave init .` -> brownfield analysis detects doc gaps |
+| **Weekend MVP** | `specweave init .` -> `/sw:increment "Build auth"` |
+| **50-team enterprise** | `specweave init .` -> `/sw:enable-multiproject` -> maps to JIRA/ADO |
 
 ---
 
@@ -226,7 +257,7 @@ Three gates before any increment closes:
 - Any AI coding tool: Claude Code, Cursor, Windsurf, Cline, Aider, etc.
 - Git repository
 
-> 💡 **Why Node.js 20.12.0+?** SpecWeave uses modern JavaScript features (ES2022 Import Attributes) that require Node.js 20.12.0 or higher. If you see `SyntaxError: Unexpected token 'with'`, you need to upgrade Node.js.
+> **Why Node.js 20.12.0+?** SpecWeave uses modern JavaScript features (ES2022 Import Attributes) that require Node.js 20.12.0 or higher. If you see `SyntaxError: Unexpected token 'with'`, you need to upgrade Node.js.
 
 ---
 

package/dist/src/cli/commands/merge-skill-memories.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Merge Skill Memories - Preserves user learnings during marketplace refresh
+ *
+ * This module handles the merging of skill memories when the marketplace is updated.
+ * It ensures that user learnings (stored in MEMORY.md files) are preserved while
+ * allowing new default learnings from the updated marketplace to be added.
+ *
+ * Architecture:
+ * - Each skill can have a MEMORY.md file with learnings
+ * - User learnings are ALWAYS preserved
+ * - Default learnings from new versions are merged in (deduplicated)
+ * - This runs during `specweave refresh-marketplace`
+ */
+import { type MergeResult } from '../../core/reflection/skill-memory-merger.js';
+export interface SkillMemoryMergeResult {
+    skillsProcessed: number;
+    learningsPreserved: number;
+    learningsAdded: number;
+    learningsDeduped: number;
+    errors: string[];
+}
+/**
+ * Merge skill memories during marketplace refresh
+ *
+ * This is called from refresh-marketplace command to preserve user learnings
+ * while updating skills from the marketplace.
+ *
+ * @param marketplacePath - Path to the updated marketplace (source of new skills)
+ * @param verbose - Whether to log detailed info
+ */
+export declare function mergeSkillMemoriesOnRefresh(marketplacePath: string, verbose?: boolean): Promise<SkillMemoryMergeResult>;
+/**
+ * Merge memories for a single skill (can be called independently)
+ */
+export declare function mergeSkillMemory(skillName: string, sourcePath?: string, targetPath?: string): Promise<MergeResult>;
+//# sourceMappingURL=merge-skill-memories.d.ts.map

package/dist/src/cli/commands/merge-skill-memories.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"merge-skill-memories.d.ts","sourceRoot":"","sources":["../../../../src/cli/commands/merge-skill-memories.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAKH,OAAO,EAKL,KAAK,WAAW,EACjB,MAAM,8CAA8C,CAAC;AAGtD,MAAM,WAAW,sBAAsB;IACrC,eAAe,EAAE,MAAM,CAAC;IACxB,kBAAkB,EAAE,MAAM,CAAC;IAC3B,cAAc,EAAE,MAAM,CAAC;IACvB,gBAAgB,EAAE,MAAM,CAAC;IACzB,MAAM,EAAE,MAAM,EAAE,CAAC;CAClB;AAgED;;;;;;;;GAQG;AACH,wBAAsB,2BAA2B,CAC/C,eAAe,EAAE,MAAM,EACvB,OAAO,UAAQ,GACd,OAAO,CAAC,sBAAsB,CAAC,CAuFjC;AAED;;GAEG;AACH,wBAAsB,gBAAgB,CACpC,SAAS,EAAE,MAAM,EACjB,UAAU,CAAC,EAAE,MAAM,EACnB,UAAU,CAAC,EAAE,MAAM,GAClB,OAAO,CAAC,WAAW,CAAC,CA2CtB"}