specweave 0.9.1 → 0.10.0

package/CLAUDE.md

@@ -1981,6 +1981,35 @@ Solution: Inactivity-based detection
 - `INACTIVITY_THRESHOLD=15` - Seconds of inactivity to assume session ending (adjustable)
 - `DEBOUNCE_SECONDS=2` - Prevents duplicate hook fires
 
+**Pre-Tool-Use Hook** (`.claude/hooks/pre-tool-use.sh`):
+
+**Purpose**: Detect when Claude asks questions BEFORE task completion
+
+**The Problem**: The post-task-completion hook only fires after TodoWrite events. If Claude asks a question via AskUserQuestion WITHOUT completing any tasks first, no sound plays and the user doesn't know Claude is waiting for input.
+
+**The Solution**: The pre-tool-use hook fires BEFORE every tool call, allowing us to detect AskUserQuestion immediately.
+
+**How It Works**:
+```
+Scenario 1: Question after task completion
+- 10:00:00 - Task completed (TodoWrite) → post-task-completion hook fires
+- 10:00:15 - Inactivity threshold reached → SOUND! ✅
+
+Scenario 2: Question WITHOUT task completion (NEW!)
+- 10:00:00 - Claude calls AskUserQuestion → pre-tool-use hook fires
+- 10:00:00 - Detects tool_name="AskUserQuestion" → SOUND! ✅
+- User is notified IMMEDIATELY, not after 15s
+```
+
+**Key Features**:
+- ✅ Fires BEFORE any tool call (PreToolUse event)
+- ✅ Filters for AskUserQuestion specifically
+- ✅ Plays distinctive sound (Tink.aiff on macOS, dialog-question.oga on Linux)
+- ✅ Non-blocking and fast (<10ms overhead)
+- ✅ Complements post-task-completion hook (both work together)
+
+**Result**: Users are ALWAYS notified when Claude needs input, regardless of whether tasks have been completed or not.
+
 **Manual Actions** (Claude MUST do after each task):
 - Update `CLAUDE.md` when structure changes
 - Update `README.md` for user-facing changes
@@ -2713,30 +2742,54 @@ Your choice [1]:
 
 ### Translation Workflow (Multilingual Support)
 
-**SpecWeave supports multilingual development** via post-generation translation (Increment 0006).
+**SpecWeave supports multilingual development** via two-phase post-generation translation (Increment 0006).
 
 **Key Concept**: Users work in their native language (great UX), system auto-translates to English (maintainable docs).
 
+**Two-Phase Translation Architecture**:
+
+| Phase | Hook | What Gets Translated | When | Coverage |
+|-------|------|---------------------|------|----------|
+| **Phase 1** | post-increment-planning | Increment files + Living docs specs | After `/specweave:increment` | 80% of docs |
+| **Phase 2** | post-task-completion | ADRs, HLDs, diagrams | After each task completion | 20% of docs |
+
 **Workflow**:
 
 ```bash
 # 1. User creates increment in Russian
 /specweave:increment "Добавить пользовательскую аутентификацию"
 
-# 2. PM agent generates spec.md in Russian (natural, user-friendly)
+# 2. PM agent generates spec.md, plan.md, tasks.md in Russian (natural, user-friendly)
 
-# 3. post-increment-planning hook fires automatically
-#    - Detects Russian content
-#    - Translates spec.md, plan.md, tasks.md to English (~$0.01 cost)
-#    - Files now in English (maintainable)
+# 3. post-increment-planning hook fires automatically (PHASE 1)
+#    Phase A: Translates increment files (spec.md, plan.md, tasks.md) to English
+#    Phase B: Translates living docs specs to English (NEW!)
+#             - .specweave/docs/internal/specs/spec-*.md
+#             - .specweave/docs/internal/strategy/**/*.md
+#    Cost: ~$0.02 total
 
 # User sees:
 # ✅ Increment created
-# 🌐 Detected Russian content. Translating to English...
+# 🌐 Detected Russian content. Translating increment files to English...
 #   📄 spec.md... ✅
 #   📄 plan.md... ✅
 #   📄 tasks.md... ✅
-# ✅ Translation complete! Cost: ~$0.01
+# 🌐 Checking living docs for translation...
+#   📄 Living docs detected: spec-0001-user-auth.md
+#   ✅ Translated 1 living docs file(s) to English
+# ✅ Translation complete!
+#    Increment files: 3/3
+#    Living docs: 1 file(s)
+#    Estimated cost: ~$0.01-0.02 (using Haiku)
+
+# 4. During implementation, architect creates ADRs in Russian
+
+# 5. post-task-completion hook fires after each task (PHASE 2)
+#    - Translates newly created ADRs to English
+#    - Translates HLDs/diagrams to English
+#    Cost: ~$0.01 per file
+
+# Result: ALL documentation in English (100% coverage)
 ```
 
 **Configuration** (`.specweave/config.json`):
@@ -2747,7 +2800,7 @@ Your choice [1]:
   "translation": {
     "enabled": true,
     "autoTranslateInternalDocs": true,
-    "autoTranslateLivingDocs": false,
+    "autoTranslateLivingDocs": true,
     "keepFrameworkTerms": true,
     "keepTechnicalTerms": true,
     "translationModel": "haiku"
@@ -2757,8 +2810,8 @@ Your choice [1]:
 
 **Key Settings**:
 - `language`: Primary language (en, ru, es, zh, de, fr, ja, ko, pt)
-- `autoTranslateInternalDocs`: Auto-translate spec/plan/tasks to English (default: true)
-- `autoTranslateLivingDocs`: Auto-translate ADRs/HLDs after task completion (default: false)
+- `autoTranslateInternalDocs`: Auto-translate increment files + living docs specs to English (default: true)
+- `autoTranslateLivingDocs`: Auto-translate ADRs/HLDs after task completion (default: true)
 - `translationModel`: Model to use (haiku/sonnet/opus, default: haiku)
 
 **Supported Languages**:
@@ -2772,7 +2825,9 @@ Your choice [1]:
 - Korean (ko)
 - Portuguese (pt)
 
-**Cost**: ~$0.01 per increment (3 files, Haiku model)
+**Cost**: ~$0.02 per increment (5-7 files, Haiku model)
+
+**Coverage**: 100% (no gaps! All living docs translated)
 
 **Implementation Details**:
 - Language detection: Heuristic-based (<1ms, zero cost)
@@ -2792,10 +2847,42 @@ npm test -- tests/unit/i18n/translation.test.ts
 **Files**:
 - Utilities: `src/utils/translation.ts` (673 lines, 11 languages)
 - CLI Script: `src/hooks/lib/translate-file.ts` (398 lines)
-- Hook: `plugins/specweave/hooks/post-increment-planning.sh` (307 lines)
+- Hook (Phase 1): `plugins/specweave/hooks/post-increment-planning.sh` (~420 lines)
+- Hook (Phase 2): `src/hooks/lib/translate-living-docs.ts` (217 lines)
 - Tests: `tests/unit/i18n/translation.test.ts` (705 lines, 67 tests)
+- E2E Tests: `tests/e2e/i18n/living-docs-translation.spec.ts` (6 test cases)
 - Schema: `src/core/schemas/specweave-config.schema.json`
 
+**Migrating Existing Non-English Living Docs**:
+
+For projects with existing non-English living docs, use the one-time migration script:
+
+```bash
+# One-time migration (translates all living docs to English)
+bash scripts/migrate-living-docs-to-english.sh
+
+# What it does:
+# - Scans .specweave/docs/internal/ for non-English files
+# - Translates each file to English (preserves code blocks, links, framework terms)
+# - Skips files already in English
+# - Non-blocking (continues even if some files fail)
+
+# Estimated time: 1-2 minutes per 100 files
+# Estimated cost: ~$0.01 per file (using Haiku)
+```
+
+**After migration**:
+```bash
+# Review translated files
+git diff .specweave/docs/internal/
+
+# Commit changes
+git add . && git commit -m "docs: translate living docs to English"
+
+# Future increments will auto-translate
+/specweave:increment "Добавить новую функцию"  # Auto-translates!
+```
+
 ---
 
 ## Troubleshooting

package/README.md

@@ -10,347 +10,193 @@
 
 ---
 
-## The Problem Everyone Feels But Nobody Talks About
+## The Problem
 
-Your AI coding assistant writes features in 30 minutes.
+AI coding assistants made us **10x faster at shipping**, but **100x worse at maintaining**.
 
-You spend 3 days updating documentation.
-
-By day 4, the code has changed again.
+Your AI writes features in 30 minutes. You spend 3 days updating docs. By day 4, the code changed again.
 
 **The docs? Already wrong.**
 
 ---
 
-## The Dirty Secret of AI Coding
-
-AI coding assistants made us:
-- ✅ **10x faster at shipping**
-- ❌ **100x worse at maintaining**
-
-We're all "vibe coding" now. Fast. Fun. Chaotic.
-
-No structure. No boundaries. No memory of why we built it this way.
-
-New developers? Lost in 1 hour.
-
-**This is not sustainable.**
-
----
-
-## The Fortune 500 Gap
-
-Big companies don't have this problem.
-
-They have systems:
-- **PRDs** (Product Requirements) - What and why
-- **HLDs** (High-Level Design) - Architecture decisions
-- **ADRs** (Architecture Decision Records) - Why we chose X over Y
-- **Runbooks** (Operations) - How to actually run this
-- **Glossaries** (Terms) - What these acronyms mean
-
-Their docs stay updated because there's a team, a process, a **discipline**.
-
-But for solo developers and small teams?
-
-**Impossible to maintain manually.**
-
----
-
-## What is SpecWeave?
+## The Solution
 
 **Fortune 500 discipline. Zero overhead. AI-native.**
 
-SpecWeave is a spec-driven development framework that brings enterprise-grade processes to developers of any size—without the bureaucracy.
-
-It's not just a tool. **It's a movement.**
+SpecWeave brings enterprise-grade processes (PRDs, HLDs, ADRs, runbooks) to developers of any size—without the bureaucracy.
 
 > *"Dad, AI writes your code but you update docs MANUALLY?"*
 > — My 14-year-old daughter (who was absolutely right)
 
-**The new way:**
-- Living docs that ACTUALLY stay synced (automatically)
-- Complete knowledge system (PRDs, HLDs, ADRs, glossaries, runbooks)
-- Tests embedded in tasks (BDD format, full traceability)
-- Enterprise structure without enterprise overhead
-- **Vibe coding... but with boundaries**
+**Living docs that ACTUALLY stay synced** - Automatically updated after every task. No manual intervention.
 
 ---
 
-## What Changes
+## Works for Both
 
-**BEFORE (Vibe Coding):**
-- "I think we used JWT tokens?"
-- "Why did we choose PostgreSQL again?"
-- "What does this acronym mean?"
-- New developer: **Lost in 1 hour**
+**🌱 Greenfield** (New Projects)
+- Start with best practices from day one
+- Spec-driven development from the beginning
+- Clean, documented, maintainable
 
-**AFTER (SpecWeave):**
-- Check ADR-003: JWT vs Session Tokens (we chose JWT, here's why)
-- Check HLD: Database section (Postgres for ACID compliance)
-- Check Glossary: All technical terms defined
-- New developer: **Productive in 1 hour**
+**🏭 Brownfield** (Existing Projects)
+- Import docs from Notion, Confluence, Wiki
+- AI-powered classification (85%+ accuracy)
+- Gradual migration without disruption
 
----
-
-## 📊 Engineering Metrics (DORA)
-
-[![Deploy Frequency](https://img.shields.io/badge/dynamic/json?url=https://raw.githubusercontent.com/anton-abyzov/specweave/develop/metrics/dora-latest.json&query=$.metrics.deploymentFrequency.value&label=Deploy%20Frequency&suffix=/month&color=brightgreen)](https://spec-weave.com/docs/metrics)
-[![Lead Time](https://img.shields.io/badge/dynamic/json?url=https://raw.githubusercontent.com/anton-abyzov/specweave/develop/metrics/dora-latest.json&query=$.metrics.leadTime.value&label=Lead%20Time&suffix=h&color=brightgreen)](https://spec-weave.com/docs/metrics)
-[![Change Failure Rate](https://img.shields.io/badge/dynamic/json?url=https://raw.githubusercontent.com/anton-abyzov/specweave/develop/metrics/dora-latest.json&query=$.metrics.changeFailureRate.value&label=Change%20Failure%20Rate&suffix=%25&color=brightgreen)](https://spec-weave.com/docs/metrics)
-[![MTTR](https://img.shields.io/badge/dynamic/json?url=https://raw.githubusercontent.com/anton-abyzov/specweave/develop/metrics/dora-latest.json&query=$.metrics.mttr.value&label=MTTR&suffix=min&color=brightgreen)](https://spec-weave.com/docs/metrics)
-
-[View detailed metrics dashboard →](https://spec-weave.com/docs/metrics)
-
----
-
-## 📖 Full Documentation
-
-**For complete guides, tutorials, and API reference:**
-
-### **[spec-weave.com](https://spec-weave.com)**
+**[→ Brownfield Import Guide](https://spec-weave.com/docs/workflows/brownfield)**
 
 ---
 
 ## Quick Start
 
+### Greenfield (New Project)
 ```bash
-# Install SpecWeave CLI
+# Install SpecWeave
 npm install -g specweave
 
-# Initialize your project
+# Initialize new project
 specweave init my-project
 cd my-project
 
-# Start building - SpecWeave guides you through the entire workflow
+# Start building
 /specweave:increment "User authentication"  # Plan increment
-/specweave:do                               # Implement tasks (auto-pauses if blocked, auto-resumes when ready)
+/specweave:do                               # Implement tasks
 /specweave:done 0001                        # Complete increment
 ```
 
-**New to SpecWeave?** → **[Getting Started Guide](https://spec-weave.com/docs/guides/getting-started/quickstart)**
-
----
-
-## Key Features
-
-### 🧪 Test-Aware Planning
-Embedded test plans in every task with BDD format (Given/When/Then) for clarity
-
-### 🎯 Disciplined Progress
-Cannot start increment N+1 until N is DONE - enforces completion before moving forward
-
-### ⏸️ Intelligent Status Management
-Automatically detects when you're blocked (missing API keys, waiting for approval), pauses work with clear context, and resumes when ready - no manual intervention needed
-
-### 📚 Living Documentation
-Auto-updates after every task via Claude Code hooks - never outdated
-
-### 🤖 Intelligent Agents
-PM Agent, Architect, test-aware-planner, Quality Judge - specialized AI agents guide you
-
-
-### 🌍 Multilingual Support ($0 Cost!)
+### Brownfield (Existing Project)
+```bash
+# Initialize SpecWeave in existing project
+cd my-existing-project
+specweave init .
 
-Work in 11 languages with **FREE zero-cost translation**:
+# Import existing docs
+/specweave:import-docs ~/Downloads/notion-export --source=notion
 
-- **Primary Approach**: In-session translation (FREE, works with any model)
-- **Optional Approach**: Automated hooks (convenience, ~$0.003/increment)
-- **11 Languages**: English, Russian, Spanish, Chinese, German, French, Japanese, Korean, Portuguese, Arabic, Hebrew
-- **Any Model**: Claude, GPT-4, Gemini, DeepSeek, and more
-- **Any Tool**: Claude Code, Cursor, Copilot, ChatGPT
+# Continue normally
+/specweave:increment "Add dark mode"
+```
 
-**Zero API costs** - uses your current conversation context for translation!
+**[→ Complete Quickstart Guide](https://spec-weave.com/docs/guides/getting-started/quickstart)**
 
 ---
 
-## Enterprise Features
-
-### 🏢 Multi-Project Support (v0.8.0+)
-
-Organize documentation by team, repo, or microservice:
-
-- **Team-Based Organization**: Frontend, Backend, Mobile, Platform teams with separate documentation
-- **Microservices Architecture**: Each service gets its own specs, modules, and team playbooks
-- **Per-Project Sync**: Link projects to different GitHub repos, JIRA projects, or ADO boards
-- **Unified Architecture**: Single project = multi-project with 1 project (NO special cases!)
-
-**Five Documentation Types Per Project**:
-1. **specs/** - Living documentation specs (user stories, AC)
-2. **modules/** - Module/component documentation (architecture, APIs)
-3. **team/** - Team playbooks (onboarding, conventions, workflows)
-4. **architecture/** - Project-specific ADRs (optional)
-5. **legacy/** - Brownfield imports (temporary)
+## Real-World Example
 
-**[→ Multi-Project Setup Guide](https://spec-weave.com/docs/guides/multi-project-setup)**
+**Scenario**: Building authentication for SaaS app
 
-### 🔗 Issue Tracker Integration (v0.9.0+)
-
-**Strategy-based team mapping** adapts to your organization's structure:
-
-#### **GitHub - 3 Strategies**
-
-1. **Repository-per-team** (Most Common)
-   ```bash
-   GITHUB_STRATEGY=repository-per-team
-   GITHUB_REPOS=frontend-app,backend-api,mobile-app
-   ```
-   Best for: Microservices, independent deployments
-
-2. **Team-based** (Monorepo)
-   ```bash
-   GITHUB_STRATEGY=team-based
-   GITHUB_REPO=main-product
-   GITHUB_TEAMS=frontend-team,backend-team
-   ```
-   Best for: Monorepos (Nx, Turborepo, Lerna)
+```bash
+# 1. Plan increment (PM Agent creates spec with user stories)
+/specweave:increment "User authentication with OAuth"
 
-3. **Team-multi-repo** (Platform Teams)
-   ```bash
-   GITHUB_STRATEGY=team-multi-repo
-   GITHUB_TEAM_REPO_MAPPING='{"platform-team":["api-gateway","auth"]}'
-   ```
-   Best for: Platform teams owning multiple services
+# Result:
+# ✅ spec.md - User stories, acceptance criteria
+# ✅ plan.md - Architecture, implementation steps
+# ✅ tasks.md - Tasks with embedded tests (BDD format)
 
-#### **Jira - 3 Strategies**
+# 2. Implement (auto-pauses if blocked, resumes when ready)
+/specweave:do
 
-1. **Project-per-team** - Separate projects for each team
-2. **Component-based** - One project with components
-3. **Board-based** - One project with filtered boards
+# While you work:
+# - Living docs sync automatically after each task
+# - Tests embedded in tasks guide implementation
+# - ADRs document "why we chose X over Y"
+# - GitHub issues auto-sync (optional)
 
-#### **Azure DevOps - Team-Based**
+# 3. Complete (Quality Judge validates)
+/specweave:done 0001
 
-Fixed hierarchy: Organization → Project (ONE) → Teams (multiple)
-```bash
-AZURE_DEVOPS_PROJECT=MyProject
-AZURE_DEVOPS_TEAMS=Frontend,Backend,Mobile
+# Result:
+# ✅ Code implemented
+# ✅ Tests passing (90% coverage)
+# ✅ Docs synced (ADRs, HLDs, runbooks)
+# ✅ GitHub issues updated
+# ✅ New dev can onboard in 1 hour (not 1 week!)
 ```
 
-**[→ Complete Integration Guide](https://spec-weave.com/docs/integrations/issue-trackers)**
+---
+
+## 📊 Engineering Metrics (DORA)
 
-### 📦 Brownfield Import
+[![Deploy Frequency](https://img.shields.io/badge/dynamic/json?url=https://raw.githubusercontent.com/anton-abyzov/specweave/develop/metrics/dora-latest.json&query=$.metrics.deploymentFrequency.value&label=Deploy%20Frequency&suffix=/month&color=brightgreen)](https://github.com/anton-abyzov/specweave/blob/develop/.specweave/docs/internal/delivery/dora-metrics.md)
+[![Lead Time](https://img.shields.io/badge/dynamic/json?url=https://raw.githubusercontent.com/anton-abyzov/specweave/develop/metrics/dora-latest.json&query=$.metrics.leadTime.value&label=Lead%20Time&suffix=h&color=brightgreen)](https://github.com/anton-abyzov/specweave/blob/develop/.specweave/docs/internal/delivery/dora-metrics.md)
+[![Change Failure Rate](https://img.shields.io/badge/dynamic/json?url=https://raw.githubusercontent.com/anton-abyzov/specweave/develop/metrics/dora-latest.json&query=$.metrics.changeFailureRate.value&label=Change%20Failure%20Rate&suffix=%25&color=brightgreen)](https://github.com/anton-abyzov/specweave/blob/develop/.specweave/docs/internal/delivery/dora-metrics.md)
+[![MTTR](https://img.shields.io/badge/dynamic/json?url=https://raw.githubusercontent.com/anton-abyzov/specweave/develop/metrics/dora-latest.json&query=$.metrics.mttr.value&label=MTTR&suffix=min&color=brightgreen)](https://github.com/anton-abyzov/specweave/blob/develop/.specweave/docs/internal/delivery/dora-metrics.md)
 
-Import existing documentation from external sources:
+**[→ Live Dashboard](https://spec-weave.com/docs/metrics)** | **[→ Detailed Report](https://github.com/anton-abyzov/specweave/blob/develop/metrics/dora-report.md)**
 
-- **Automatic Classification**: AI-powered keyword detection (85%+ accuracy)
-- **Supported Sources**: Notion, Confluence, GitHub Wiki, custom markdown folders
-- **Smart Organization**: Classifies into specs, modules, team docs, or legacy
-- **Migration Reports**: Complete audit trail with confidence scores and manual review checklist
+---
 
-**Example**:
-```bash
-# Import Notion export to web-app project
-/specweave:import-docs ~/Downloads/notion-export --source=notion --project=web-app
+## Key Features
 
-# Result:
-# ✅ Classified 127 files
-#    - 37 specs → projects/web-app/specs/
-#    - 18 modules → projects/web-app/modules/
-#    - 12 team docs → projects/web-app/team/
-#    - 60 legacy → projects/web-app/legacy/notion/
-```
+- 🧪 **Test-Aware Planning** - Embedded tests in BDD format (Given/When/Then)
+- 🎯 **Disciplined Progress** - Can't start increment N+1 until N is DONE
+- ⏸️ **Intelligent Pausing** - Auto-detects blockers, pauses with context, resumes when ready
+- 📚 **Living Documentation** - Auto-updates after every task (no manual sync!)
+- 🤖 **AI Agents** - PM, Architect, Quality Judge guide your work
+- 🌍 **Multilingual** - Work in 11 languages (FREE translation)
+- 🏢 **Multi-Project** - Organize by team/repo/microservice
+- 🔗 **Issue Tracker Sync** - GitHub, Jira, Azure DevOps integration
 
-**[→ Brownfield Integration Guide](https://spec-weave.com/docs/workflows/brownfield)**
+**[→ Complete Feature List](https://spec-weave.com/docs/overview/features)**
 
 ---
 
-## Documentation Hub
+## 📖 Documentation
 
-**Learn SpecWeave:**
-- 📘 [What is SpecWeave?](https://spec-weave.com/docs/overview/introduction)
-- 🚀 [Quickstart Guide](https://spec-weave.com/docs/guides/getting-started/quickstart)
-- 🏗️ [Complete Workflow Journey](https://spec-weave.com/docs/workflows/overview)
-- ❓ [FAQ - Common Questions](https://spec-weave.com/docs/faq)
+**Complete guides, tutorials, and API reference:**
 
-**Commands & API:**
-- 📋 [Commands Reference](https://spec-weave.com/docs/commands/status-management)
-- 🔧 [API Documentation](https://spec-weave.com/docs/api)
+### **[spec-weave.com](https://spec-weave.com)**
 
-**Advanced Topics:**
-- 📊 [DORA Metrics Dashboard](https://spec-weave.com/docs/metrics)
-- 🏢 [Brownfield Integration](https://spec-weave.com/docs/workflows/brownfield)
-- 🌍 [Multilingual Support](https://spec-weave.com/docs/tutorial-extras/multilingual-support)
-- 🔗 [GitHub Actions Setup](https://spec-weave.com/docs/guides/github-action-setup)
+**Start here:**
+- 🚀 [Quickstart Guide](https://spec-weave.com/docs/guides/getting-started/quickstart) - 5-minute setup
+- 📘 [Complete Workflow](https://spec-weave.com/docs/workflows/overview) - End-to-end journey
+- 📋 [Commands Reference](https://spec-weave.com/docs/commands/status-management) - All commands
+- ❓ [FAQ](https://spec-weave.com/docs/faq) - Common questions
 
 ---
 
-## Community & Support
-
-**Join the Community:**
+## Community
 
-- 💬 **[Discord Server](https://discord.gg/UYg4BGJ65V)** - Get help, share tips, discuss features
-- 🎥 **[YouTube Channel](https://www.youtube.com/@antonabyzov)** - Tutorials, demos, deep dives
-- 📖 **[Documentation](https://spec-weave.com)** - Complete guides and API reference
-- 🐛 **[GitHub Issues](https://github.com/anton-abyzov/specweave/issues)** - Bug reports and feature requests
-- 💡 **[GitHub Discussions](https://github.com/anton-abyzov/specweave/discussions)** - Q&A and community discussions
-
-**Need Help?**
-1. Check the **[FAQ](https://spec-weave.com/docs/faq)** first
-2. Ask in **[Discord](https://discord.gg/UYg4BGJ65V)** for quick answers
-3. Create a **[GitHub Discussion](https://github.com/anton-abyzov/specweave/discussions)** for detailed questions
+- 💬 **[Discord](https://discord.gg/UYg4BGJ65V)** - Get help, share tips
+- 🎥 **[YouTube](https://www.youtube.com/@antonabyzov)** - Tutorials, demos
+- 🐛 **[GitHub Issues](https://github.com/anton-abyzov/specweave/issues)** - Report bugs
+- 💡 **[Discussions](https://github.com/anton-abyzov/specweave/discussions)** - Q&A, feature requests
 
 ---
 
 ## Contributing
 
-**Development Setup:**
-
 ```bash
-# Clone and setup
+# Setup
 git clone https://github.com/anton-abyzov/specweave.git
 cd specweave
-npm install
-npm run build
+npm install && npm run build
 
-# Run tests
+# Test
 npm test
 ```
 
-**To Contribute:**
-1. Fork repository
-2. Create feature branch: `git checkout -b features/002-new-feature`
-3. Follow SpecWeave conventions (see CLAUDE.md)
-4. Add tests (minimum 3 test cases)
-5. Create PR to `develop` branch
-
 **[→ Contributor Guide](https://spec-weave.com/docs/guides/contributing)**
 
 ---
 
-## Best Results with Claude Code
+## Best with Claude Code
 
-SpecWeave gives **best results with Claude Code** due to unique capabilities:
+SpecWeave works best with **[Claude Code](https://claude.com/claude-code)** (native plugins, auto-activating skills, lifecycle hooks).
 
-- ✅ **Native Plugin Marketplace** - Skills and agents auto-activate (no manual setup)
-- ✅ **Auto-Activating Skills** - Context-aware activation (no @ mentions)
-- ✅ **Isolated Agent Contexts** - True multi-agent role separation
-- ✅ **Pre/Post Lifecycle Hooks** - Automated living docs sync after every task
-- ✅ **MCP Protocol** - Industry standard for context management
-
-**Also works with**: Cursor, GitHub Copilot, ChatGPT (with manual workflow, reduced automation)
+Also works with: Cursor, GitHub Copilot, ChatGPT (manual workflow).
 
 **[→ Tool Comparison](https://spec-weave.com/docs/overview/features#claude-code-native)**
 
 ---
 
-## Status & License
+## License
 
-**Status**: Beta - Ready for testing and contributions
-**License**: MIT
-**Repository**: [github.com/anton-abyzov/specweave](https://github.com/anton-abyzov/specweave)
+MIT - [github.com/anton-abyzov/specweave](https://github.com/anton-abyzov/specweave)
 
 ---
 
-## Acknowledgments
-
-SpecWeave is inspired by:
-- [spec-kit](https://github.com/github/spec-kit) - GitHub's specification toolkit
-- [BMAD-METHOD](https://github.com/bmad-code-org/BMAD-METHOD) - Agentic agile framework
-- [Claude Code](https://claude.com/claude-code) - Anthropic's native plugin system
-- [C4 Model](https://c4model.com/) - Software architecture diagrams
-
----
-
-**SpecWeave** - AI made us fast. SpecWeave makes us sustainable.
-
-**Get started**: `npm install -g specweave` → `specweave init my-project` → **[Read the Docs](https://spec-weave.com)**
+**Get started**: `npm install -g specweave` → **[Read the Docs](https://spec-weave.com)**

package/bin/install-agents.sh

@@ -7,7 +7,7 @@
 
 set -e
 
-AGENTS_SRC="plugins/specweave-core/agents"
+AGENTS_SRC="plugins/specweave/agents"
 AGENTS_DEST=".claude/agents"
 
 # Parse arguments

package/bin/install-commands.sh

@@ -5,7 +5,7 @@
 
 set -e
 
-COMMANDS_SRC="plugins/specweave-core/commands"
+COMMANDS_SRC="plugins/specweave/commands"
 COMMANDS_DEST=".claude/commands"
 
 echo "════════════════════════════════════════════════════════"

package/bin/install-hooks.sh

@@ -7,7 +7,7 @@
 
 set -e
 
-HOOKS_SRC="plugins/specweave-core/hooks"
+HOOKS_SRC="plugins/specweave/hooks"
 HOOKS_DEST=".claude/hooks"
 
 # Parse arguments

package/bin/install-skills.sh

@@ -7,7 +7,7 @@
 
 set -e
 
-SKILLS_SRC="plugins/specweave-core/skills"
+SKILLS_SRC="plugins/specweave/skills"
 SKILLS_DEST=".claude/skills"
 
 # Parse arguments