specweave 0.26.14 → 0.28.0

package/README.md

@@ -1,553 +1,348 @@
 # SpecWeave
 
-> **1 Senior Developer = Full Engineering Team**
-
-The framework that turns solo builders into unicorn-level engineering teams.
+**The AI Development Framework That Doesn't Lose Your Work**
 
+[![NPM Version](https://img.shields.io/npm/v/specweave?color=blue)](https://www.npmjs.com/package/specweave)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
-[![Build](https://img.shields.io/github/actions/workflow/status/anton-abyzov/specweave/test.yml?branch=develop&label=Tests)](https://github.com/anton-abyzov/specweave/actions/workflows/test.yml)
-[![E2E](https://img.shields.io/github/actions/workflow/status/anton-abyzov/specweave/e2e-smoke-test.yml?branch=develop&label=E2E)](https://github.com/anton-abyzov/specweave/actions/workflows/e2e-smoke-test.yml)
-[![Discord](https://img.shields.io/badge/Discord-Join_Server-5865F2?logo=discord&logoColor=white)](https://discord.gg/UYg4BGJ65V)
-[![YouTube](https://img.shields.io/badge/YouTube-Subscribe-red?logo=youtube&logoColor=white)](https://www.youtube.com/@antonabyzov)
-
----
-
-## 📊 Engineering Metrics (DORA)
-
-[![Deploy Frequency](https://img.shields.io/badge/dynamic/json?url=https://raw.githubusercontent.com/anton-abyzov/specweave/develop/.specweave/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/.specweave/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/.specweave/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/.specweave/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)
-
-**SpecWeave builds SpecWeave using SpecWeave.** These are real metrics from our own development.
-
-**[→ Live Dashboard](https://spec-weave.com/docs/metrics)** | **[→ Detailed Report](https://github.com/anton-abyzov/specweave/blob/develop/.specweave/metrics/dora-report.md)**
-
----
-
-## 🦄 The Solo Builder Revolution
-
-**The Truth Nobody Talks About:**
-- **Stripe:** Started with 2 engineers
-- **Instagram:** 1 engineer (Kevin Systrom) until 100M users
-- **WhatsApp:** 32 engineers serving 450M users (14M users per engineer!)
-- **Plaid:** 3 founding engineers built a $13B company
-
-**What they had that you don't:**
-- Enterprise-grade documentation processes
-- Architecture decision records (ADRs)
-- Living runbooks and operational docs
-- Spec-driven development discipline
-
-**With SpecWeave:**
-- ✅ **You get ALL of that** - automatically
-- ✅ **You ARE the full team** - PM + Architect + QA + DevOps + Tech Writer
-- ✅ **You CAN build unicorns** - solo, with enterprise-grade quality
-
-### What This Replaces:
-
-| Role | Annual Cost | SpecWeave Replacement |
-|------|-------------|----------------------|
-| Product Manager | $150K | Auto-generated PRDs + User Stories |
-| System Architect | $180K | Auto-generated ADRs + HLD |
-| Tech Writer | $100K | Living docs auto-sync |
-| QA Lead | $130K | BDD tests embedded |
-| DevOps Engineer | $150K | Production runbooks included |
-| **Total Team Cost** | **$710K/year** | **$0** (free framework) |
-
-**ROI:** ♾️ (infinite)
-
-**You're not hiring a team. You're automating one.** 🚀
+[![Discord](https://img.shields.io/badge/Discord-Join-5865F2?logo=discord&logoColor=white)](https://discord.gg/UYg4BGJ65V)
+[![YouTube](https://img.shields.io/badge/YouTube-Tutorials-red?logo=youtube&logoColor=white)](https://www.youtube.com/@antonabyzov)
 
 ---
 
-## If You Get Hit By A Bus
-
-Your startup dies with you.
-
-Every architecture decision. Every API choice. Every "weird workaround because..."
-
-All in your head. Zero documentation.
-
-**AI made you 10x faster at digging your own grave.**
-
----
+## What Makes SpecWeave Different
 
-## Want to Scale? Get Enterprise-Ready.
+Every AI coding tool promises productivity. But after the chat ends:
 
-You can't land Fortune 500 clients with tribal knowledge.
-You can't pass SOC2 audit with "ask Dave."
-You can't sell your startup when the codebase is a mystery.
+- **Your specs disappear** into chat history
+- **Your architecture decisions are forgotten**
+- **Your tests are never written**
+- **Your GitHub/JIRA stays outdated**
+- **New team members start from zero**
 
-**The companies making REAL money?**
-- They have **PRDs** (Product Requirements)
-- They have **ADRs** (Architecture Decision Records)
-- They have **HLDs** (High-Level Design docs)
-- They have **runbooks** (How to actually run this)
+**SpecWeave is the only framework where AI decisions become permanent, searchable documentation.**
 
-This isn't bureaucracy. **This is how you get paid.**
-
-But for solo devs and small teams? Impossible to maintain manually.
-
----
-
-## SpecWeave: Enterprise Standards, Solo Builder Capability
-
-**The Power Formula:**
 ```
-1 Senior + SpecWeave + Claude Code = Full Engineering Team
+Your Idea → Spec (permanent) → Plan (permanent) → Tasks (permanent) → Code → Living Docs (auto-synced)
 ```
 
-Living documentation that updates automatically after every task.
-The same processes Fortune 500 uses. Without the team. Without the manual work.
-
-### For Juniors:
-- ✅ **Code like seniors** - Enterprise patterns from day one
-- ✅ **Think like architects** - ADRs teach you system design
-- ✅ **Test like QA leads** - BDD embedded in every task
-
-### For Seniors:
-- ✅ **Build like unicorns** - Solo founder → Unicorn-level product
-- ✅ **Ship enterprise-grade** - Pass SOC2, land Fortune 500 deals
-- ✅ **Replace entire teams** - PM + Architect + QA + DevOps + Tech Writer
-
-### For CTOs:
-- ✅ **Manage without meetings** - Docs are source of truth
-- ✅ **Scale without chaos** - Standards enforced automatically
-- ✅ **Audit-ready always** - ISO, SOC2, compliance built-in
-
-**AI speed + Enterprise reliability + Solo capability = Infinite leverage** 🚀
-
 ---
 
-## 🤖 AI Manages Your Enterprise Tools (Not Just Your Code!)
-
-**Here's what makes SpecWeave revolutionary:**
-
-Other AI tools write code. **SpecWeave's AI runs your entire engineering operation.**
-
-### The Problem with Traditional AI Coding
-
-```
-You → AI → Code ✅
-You → Manual → Update JIRA ❌ (3 hours/week wasted)
-You → Manual → Update GitHub ❌ (2 hours/week wasted)
-You → Manual → Write docs ❌ (4 hours/week wasted)
-```
-
-**Total waste**: 9 hours/week = $35K/year per developer
-
-### The SpecWeave Solution: AI with Three-Permission Sync
-
-**Control EXACTLY what Claude updates with three simple questions**:
+## The Workflow
 
 ```mermaid
-graph TB
-    A[👤 You + Claude] -->|"Plan feature:\n/specweave:increment"| B{Q1: Can Claude CREATE\nand UPDATE work items\nit created?}
-    B -->|"✅ Yes"| C[📝 Create GitHub Issue #142]
-    B -->|"❌ No"| D[💻 Local Mode Only]
-
-    E[✅ Task Complete] -->|"Update content?"| F{Q2: Can Claude UPDATE\nwork items created\nexternally?}
-    F -->|"✅ Yes"| G[📤 Update PM-Created Issues]
-    F -->|"❌ No"| H[📋 Living Docs Only]
-
-    I[🔔 Issue Closed] -->|"Sync status?"| J{Q3: Can Claude UPDATE\nstatus of work items?}
-    J -->|"✅ Yes"| K[✅ Sync Status]
-    J -->|"❌ No"| L[👤 Manual Management]
-
-    style B fill:#339af0,stroke:#1971c2,stroke-width:3px,color:#fff
-    style F fill:#51cf66,stroke:#2f9e44,stroke-width:3px,color:#fff
-    style J fill:#ff8c42,stroke:#e8590c,stroke-width:3px,color:#fff
-```
-
-**Answer 3 questions during `specweave init`, Claude handles everything else**:
-
+flowchart TB
+    subgraph INPUT["1. YOU TYPE ONE COMMAND"]
+        A["<b>/specweave:increment</b><br/>'Add user authentication with OAuth'"]
+    end
+
+    subgraph AGENTS["2. AI AGENTS CREATE YOUR FOUNDATION"]
+        direction TB
+        PM["<b>PM Agent</b><br/>User stories, acceptance criteria,<br/>market research"]
+        ARCH["<b>Architect Agent</b><br/>System design, ADRs,<br/>tech stack decisions"]
+        PLAN["<b>Planner Agent</b><br/>Tasks with embedded tests,<br/>coverage targets"]
+        PM --> ARCH --> PLAN
+    end
+
+    subgraph OUTPUT["3. THREE PERMANENT FILES"]
+        direction LR
+        SPEC["<b>spec.md</b><br/>WHAT & WHY<br/>(User Stories + ACs)"]
+        PLANF["<b>plan.md</b><br/>HOW<br/>(Architecture + ADRs)"]
+        TASKS["<b>tasks.md</b><br/>DO<br/>(Tasks + Tests)"]
+    end
+
+    subgraph EXECUTE["4. ONE COMMAND TO BUILD"]
+        B["<b>/specweave:do</b><br/>Autonomous execution through all tasks"]
+    end
+
+    subgraph SYNC["5. AUTO-SYNC EVERYWHERE"]
+        direction LR
+        GH["<b>GitHub Issues</b><br/>Checkboxes update"]
+        JIRA["<b>JIRA</b><br/>Epic/Story hierarchy"]
+        ADO["<b>Azure DevOps</b><br/>Work items"]
+        DOCS["<b>Living Docs</b><br/>Always current"]
+    end
+
+    INPUT --> AGENTS
+    AGENTS --> OUTPUT
+    OUTPUT --> EXECUTE
+    EXECUTE --> SYNC
+
+    style INPUT fill:#e8f5e9,stroke:#4caf50,stroke-width:2px
+    style AGENTS fill:#e3f2fd,stroke:#2196f3,stroke-width:2px
+    style OUTPUT fill:#fff3e0,stroke:#ff9800,stroke-width:2px
+    style EXECUTE fill:#fce4ec,stroke:#e91e63,stroke-width:2px
+    style SYNC fill:#f3e5f5,stroke:#9c27b0,stroke-width:2px
 ```
-You → Claude → EVERYTHING (automatic!)
 
-/specweave:increment "User authentication"
-
-Claude creates:
-✅ Spec.md (user stories, acceptance criteria)
-✅ JIRA Epic + 5 Stories (auto-created if Q1=Yes)
-✅ GitHub Issue #142 (auto-created if Q1=Yes)
-✅ Tasks with embedded tests (BDD format)
+---
 
-/specweave:do
+## Quick Start
 
-Claude implements Task 1:
-✅ Code (AuthService.ts, tests, 92% coverage)
-✅ JIRA Story → "Done" (if Q2=Yes, updated automatically!)
-✅ GitHub checkbox → ✓ (if Q2=Yes, updated automatically!)
-✅ Docs synced (ADRs, architecture, runbooks)
+```bash
+npm install -g specweave
+cd your-project
+specweave init .
 ```
 
-**Your team/client/manager sees updates in real-time. Zero manual work.**
-
-### What This Means in Practice
-
-**For Solo Founders**:
-- ✅ Appear like a full engineering team to investors
-- ✅ Professional JIRA/ADO tracking (without the overhead)
-- ✅ 80% of time coding, 20% everything else (not 50/50!)
-
-**For Agencies/Consultants**:
-- ✅ Client A (JIRA) + Client B (ADO) + Client C (GitHub) = Zero context-switching
-- ✅ Clients see real-time updates (without you doing PM work)
-- ✅ Reclaim 20+ hours/month = $3K-$5K more billable time
-
-**For Small Teams (2-10 people)**:
-- ✅ No dedicated PM needed (Claude orchestrates everything)
-- ✅ Save $130K/year OR free up senior dev to build
-- ✅ Management self-service (no "What's the status?" meetings)
+Then in Claude Code:
+```bash
+/specweave:increment "User authentication with OAuth"  # AI creates spec + plan + tasks
+/specweave:do                                          # Autonomous implementation
+/specweave:done 0001                                   # Quality-validated completion
+```
 
-**For Enterprises**:
-- ✅ SOC2/ISO audit trails (automatic compliance documentation)
-- ✅ Real-time visibility (management dashboards fed by AI)
-- ✅ Multi-project tracking (unlimited repos, one SpecWeave instance)
+**[Full Quickstart Guide](https://spec-weave.com/docs/guides/getting-started/quickstart)**
 
-### Supported Enterprise Platforms
+---
 
-| Platform | Status | Capabilities |
-|----------|--------|--------------|
-| **GitHub Issues** | ✅ Production | Three-permission sync, task tracking, auto-close, multi-repo |
-| **JIRA** | ✅ Production | Three-permission sync, Epic/Story sync, status updates, comments |
-| **Azure DevOps** | ✅ Production | Three-permission sync, Work items, hierarchy, area paths |
-| **Linear** | 🔄 Coming Q1 2026 | Full integration planned |
-| **Asana** | 🔄 Coming Q2 2026 | Full integration planned |
+## Why SpecWeave Over Alternatives?
 
-### Real ROI Example
+### vs. BMAD Method (18K GitHub Stars)
 
-**5-person engineering team**:
-- **Before SpecWeave**: 3 hours/week/person on JIRA/PM = 780 hours/year = **$58,500 wasted**
-- **After SpecWeave**: 0 hours (Claude does it) = **$58,500 saved**
+| Aspect | BMAD | SpecWeave |
+|--------|------|-----------|
+| **Focus** | Greenfield microservices | **Brownfield + Greenfield** |
+| **Context Efficiency** | Context crashes documented | **70%+ token reduction** |
+| **Multi-Repo** | Single repo focus | **Multi-project mode** |
+| **External Sync** | None | **GitHub/JIRA/ADO bidirectional** |
+| **Quality Gates** | Optional | **3-gate PM validation** |
+| **Learning Curve** | Steep (YAML/agents) | Medium (CLI commands) |
 
-**Plus intangibles**:
-- ✅ 30% more features shipped (time reclaimed)
-- ✅ Audit-ready always (compliance automatic)
-- ✅ Real-time visibility (stakeholders self-service)
-- ✅ Professional appearance (even as solo founder)
+### vs. GitHub Spec Kit
 
-**[→ Multi-Project Sync Guide](https://spec-weave.com/docs/integrations/multi-project-sync)** | **[→ 5-Minute Setup](https://spec-weave.com/docs/guides/getting-started/quickstart)**
+| Aspect | Spec Kit | SpecWeave |
+|--------|----------|-----------|
+| **Maturity** | Experimental | **Production-ready** |
+| **Brownfield** | Not supported | **Core strength** |
+| **Implementation Quality** | "Poor" (user reports) | **Quality gates enforce standards** |
+| **Human Oversight** | Batch execution | **Milestone validation** |
+| **Enterprise Features** | None | **Compliance, multi-team, DORA** |
 
 ---
 
-## Works for Both
+## External Tool Integration
 
-**🌱 Greenfield** (New Projects)
-- Start with best practices from day one
-- Spec-driven development from the beginning
-- Clean, documented, maintainable
+SpecWeave keeps your project management tools in sync **automatically**:
 
-**🏭 Brownfield** (Existing Projects)
-- Import docs from Notion, Confluence, Wiki
-- AI-powered classification (85%+ accuracy)
-- Gradual migration without disruption
+```mermaid
+flowchart LR
+    subgraph SPECWEAVE["SpecWeave"]
+        TASK["Task Completed"]
+        US["User Story Updated"]
+        INC["Increment Progress"]
+    end
+
+    subgraph EXTERNAL["Your Tools (Bidirectional)"]
+        GH["<b>GitHub Issues</b><br/>Checkboxes, comments,<br/>labels auto-update"]
+        JIRA["<b>JIRA</b><br/>Epic/Story hierarchy,<br/>status transitions"]
+        ADO["<b>Azure DevOps</b><br/>Work items,<br/>area paths"]
+    end
+
+    TASK -->|"hooks auto-fire"| GH
+    TASK -->|"hooks auto-fire"| JIRA
+    TASK -->|"hooks auto-fire"| ADO
+
+    GH -->|"import existing"| INC
+    JIRA -->|"import existing"| INC
+    ADO -->|"import existing"| INC
+
+    style SPECWEAVE fill:#e3f2fd,stroke:#2196f3,stroke-width:2px
+    style EXTERNAL fill:#f3e5f5,stroke:#9c27b0,stroke-width:2px
+```
 
-**[→ Brownfield Import Guide](https://spec-weave.com/docs/workflows/brownfield)**
+| Platform | Capabilities |
+|----------|--------------|
+| **GitHub Issues** | Create, update, close, bidirectional sync, checkbox tracking |
+| **JIRA** | Epic/Story hierarchy, bidirectional sync, custom fields |
+| **Azure DevOps** | Work items, area paths, bidirectional sync |
+| **Linear** | Coming Q1 2026 |
 
 ---
 
-## Quick Start
-
-### Greenfield (New Project)
-```bash
-# Install SpecWeave
-npm install -g specweave
+## What You Get
 
-# Initialize with Strategic Init (AI-powered research)
-specweave init my-project
+| Before | After SpecWeave |
+|--------|-----------------|
+| Specs in chat history | **Permanent, searchable specs** |
+| Manual JIRA/GitHub updates | **Auto-sync on every task** |
+| Tests? Maybe later... | **Tests embedded in tasks (60%+ enforced)** |
+| Architecture in your head | **ADRs captured automatically** |
+| "Ask John, he knows" | **Living docs, always current** |
+| Onboarding: 2 weeks | **Onboarding: 1 day** |
 
-# Strategic Init guides you through 6 phases:
-# Phase 1: Vision & Market Research
-# Phase 2: Scaling & Performance Goals
-# Phase 3: Data & Compliance Detection
-# Phase 4: Budget & Cloud Credits
-# Phase 5: Methodology & Organization
-# Phase 6: Repository Selection (optional)
+---
 
-# Result: Architecture recommendation, team plan, cost estimates
-cd my-project
+## DORA Metrics Integration
 
-# Start building
-/specweave:increment "User authentication"  # Plan increment
-/specweave:do                               # Implement tasks
-/specweave:done 0001                        # Complete increment
-```
+SpecWeave automatically calculates your team's [DORA metrics](https://dora.dev/) from GitHub data:
 
-### Multi-Project Setup
 ```bash
-# Initialize with multiple projects
-specweave init --projects backend,frontend,mobile
-
-# Tasks automatically split by project keyword detection
-# Each project gets its own user stories and GitHub issues
+npm run metrics:dora
 ```
 
-### Brownfield (Existing Project)
-```bash
-# Initialize SpecWeave in existing project
-cd my-existing-project
-specweave init .
-
-# Import existing docs
-/specweave:import-docs ~/Downloads/notion-export --source=notion
-
-# Continue normally
-/specweave:increment "Add dark mode"
-```
+| Metric | What It Measures | Elite Performance |
+|--------|------------------|-------------------|
+| **Deployment Frequency** | How often you release | Multiple per day |
+| **Lead Time for Changes** | Commit to production | Less than 1 day |
+| **Change Failure Rate** | % of releases causing issues | 0-15% |
+| **Mean Time to Recovery** | Time to restore service | Less than 1 hour |
 
-**[→ Complete Quickstart Guide](https://spec-weave.com/docs/guides/getting-started/quickstart)** | **[→ Strategic Init Guide](https://spec-weave.com/docs/guides/strategic-init)**
+**Connect your spec-driven workflow directly to industry-standard metrics.**
 
 ---
 
-## Real-World Example
+## The Three-File Foundation
 
-**Scenario**: Building authentication for SaaS app
+Every feature generates three permanent files:
 
-```bash
-# 1. Plan increment (PM Agent creates spec with user stories)
-/specweave:increment "User authentication with OAuth"
-
-# Result:
-# ✅ spec.md - User stories, acceptance criteria
-# ✅ plan.md - Architecture, implementation steps
-# ✅ tasks.md - Tasks with embedded tests (BDD format)
-
-# 2. Implement (auto-pauses if blocked, resumes when ready)
-/specweave:do
-
-# 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)
-
-# 3. Complete (Quality Judge validates)
-/specweave:done 0001
-
-# 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!)
+```
+.specweave/increments/0001-user-authentication/
+├── spec.md    ← WHAT: User stories, acceptance criteria, requirements
+├── plan.md    ← HOW: Architecture, tech decisions, ADRs
+└── tasks.md   ← DO: Implementation tasks with embedded tests
 ```
 
----
-
-## Key Features
-
-### Strategic Init - AI-Powered Architecture Planning (NEW!)
-
-- 🎯 **Research-Driven Discovery** - Answer 6 phases of questions about your product
-- 🏗️ **Architecture Recommendations** - Tech stack, scaling strategy, cost projections
-- 🔒 **Compliance Detection** - Auto-detects 30+ standards (HIPAA, GDPR, SOC2, etc.)
-- 👥 **Smart Team Planning** - Current and future team structure, hiring roadmap
-- ☁️ **Cloud Credits Discovery** - AWS Activate, Azure Startup, GCP eligibility
-- 📦 **Repository Selection** - Batch select 1-100+ repos with intelligent routing
-
-### Multi-Platform Git Support (NEW!)
+### spec.md (WHAT)
+```markdown
+## User Stories
 
-- 🌐 **Platform Choice** - GitHub (fully supported), GitLab & Bitbucket (coming soon)
-- 🔑 **SSH & HTTPS URLs** - Choose your preferred Git authentication method
-- 🏢 **Self-Hosted Support** - GitHub Enterprise, GitLab self-hosted, custom domains
-- 🔄 **Platform-Agnostic Architecture** - Zero hardcoded platform references
-- ✅ **Smart Validation** - Owner/repo/token validation before repository creation
-- 📝 **Actionable Errors** - Platform-specific troubleshooting steps when things go wrong
+### US-001: User Login
+As a user, I want to log in with OAuth so that I don't need to remember passwords.
 
-**During `specweave init`:**
-```bash
-? Select Git hosting platform:
-  > GitHub (Modern, cloud-native development platform)
-    GitLab (Coming soon! Q1 2026)
-    Bitbucket (Coming soon! Q2 2026)
-
-? Choose Git URL format:
-  > SSH (Recommended - More secure, no password prompts)
-    HTTPS (Uses personal access token for authentication)
+**Acceptance Criteria:**
+- [x] AC-US1-01: Google OAuth integration works
+- [x] AC-US1-02: Session persists across browser refresh
+- [ ] AC-US1-03: Logout clears all tokens
 ```
 
-**Result:**
-```bash
-# SSH URLs (recommended)
-git@github.com:owner/repo.git
-git@gitlab.com:namespace/project.git
-git@bitbucket.org:workspace/repo.git
-
-# HTTPS URLs
-https://github.com/owner/repo.git
-https://gitlab.com/namespace/project.git
-https://bitbucket.org/workspace/repo.git
+### tasks.md (DO)
+```markdown
+### T-001: Implement OAuth Service
+**User Story**: US-001
+**Satisfies ACs**: AC-US1-01, AC-US1-02
+**Status**: [x] completed
+
+**Embedded Tests** (AC-US1-01):
+- test_google_oauth_redirects_correctly
+- test_callback_exchanges_code_for_token
+- test_user_profile_is_fetched
 ```
 
-### Production Features
-
-- 🤖 **AI-Native Enterprise Sync** - Claude updates JIRA/GitHub/ADO automatically (three-permission control)
-- 📚 **Living Documentation** - Auto-updates after every task (no manual sync!)
-- 🧪 **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
-- 🔄 **Smart Reopen** - Report "broken" → Auto-detects what to reopen, respects WIP limits
-- 👥 **Multi-Project Tracking** - Unlimited JIRA/ADO/GitHub repos, intelligent routing
-- 🤖 **AI Agents** - PM, Architect, Quality Judge guide your work
-- 🔧 **CI/CD Auto-Fix** - Workflow failures auto-fixed by Claude (just mention `@claude`)
-- 🌍 **Multilingual** - Work in 11 languages (FREE translation)
-- 🏢 **Multi-Project Organization** - Organize by team/repo/microservice
-
-**[→ Complete Feature List](https://spec-weave.com/docs/overview/features)**
-
 ---
 
-## 🔧 CI/CD Auto-Fix
-
-**Workflow fails? Claude fixes it automatically.**
-
-When any GitHub Actions workflow fails, SpecWeave automatically:
-1. Creates an issue mentioning `@claude`
-2. Claude analyzes the failure logs
-3. Claude creates a PR with the fix
-4. You review and merge
-5. Workflow re-runs and passes ✅
+## Key Features
 
-**Manual Trigger**:
-```markdown
-@claude This workflow failed: https://github.com/your-org/repo/actions/runs/12345
+### Autonomous Multi-Agent Orchestration
 
-Please analyze the logs and create a fix PR.
+```mermaid
+flowchart LR
+    subgraph AGENTS["15+ Specialized Agents"]
+        PM["PM Agent"]
+        ARCH["Architect"]
+        TECH["Tech Lead"]
+        QA["QA Lead"]
+        SEC["Security"]
+        DEVOPS["DevOps"]
+    end
+
+    PM -->|"spec.md"| ARCH
+    ARCH -->|"plan.md"| TECH
+    TECH -->|"code"| QA
+    QA -->|"tests"| SEC
+    SEC -->|"security review"| DEVOPS
+
+    style AGENTS fill:#e8f5e9,stroke:#4caf50,stroke-width:2px
 ```
 
-**Automatic** (via GitHub Actions):
-- Detects failures automatically
-- No manual intervention needed
-- Works 24/7 in the cloud
-- Zero cost (uses GitHub Actions free tier)
+- **PM Agent**: User stories, acceptance criteria, market analysis
+- **Architect Agent**: System design, ADRs, tech stack decisions
+- **Tech Lead Agent**: Implementation, code review, best practices
+- **QA Lead Agent**: Test strategy, E2E tests, coverage validation
+- **Security Agent**: Threat modeling, OWASP, vulnerability assessment
+- **DevOps Agent**: IaC, Kubernetes, CI/CD pipelines
 
-**Common fixes**:
-- TypeScript compilation errors
-- Test failures
-- Linting violations
-- Missing imports
-- Type mismatches
-- Configuration issues
+### Living Documentation
 
-**[→ Setup Guide](https://spec-weave.com/docs/features/cicd-autofix)**
+Documentation updates **after every task** via hooks:
+- Strategic specs sync to `.specweave/docs/`
+- ADRs captured automatically
+- Runbooks and SLOs generated
+- No manual doc updates ever
 
----
+### Quality Gates
 
-## 🔄 Smart Reopen (v0.19.0)
+Three gates before any increment closes:
+1. **Tasks**: All tasks marked complete
+2. **Tests**: 60%+ coverage minimum (configurable)
+3. **Documentation**: Living docs updated
 
-**Production bug? Just say "it's broken" - AI figures out what to reopen.**
+### Token Efficiency
 
-### Auto-Detection Feature
+70%+ context reduction through:
+- Progressive plugin loading (load only what you need)
+- Skills auto-activate based on keywords
+- Context optimizer removes irrelevant specs
+- Sub-agent parallelization isolates context
 
-Report issues naturally:
-```
-"The GitHub sync isn't working"
-```
+---
 
-SpecWeave automatically:
-1. 🔍 Scans recent work (active + 7 days completed)
-2. 🎯 Finds related items (relevance scoring)
-3. 💡 Suggests exact reopen command
-4. ⚠️  Validates WIP limits
+## Commands Reference
 
-```bash
-# Suggested by AI:
-/specweave:reopen 0031 --reason "GitHub sync failing"
-
-# Result:
-✅ Increment 0031 reopened
-⚠️  WIP LIMIT: 3/2 active (EXCEEDED)
-📋 Reopened 5 tasks
-💡 Continue work: /specweave:do 0031
-```
+| Command | Purpose |
+|---------|---------|
+| `/specweave:increment "feature"` | Plan new increment (PM → Architect → Tasks) |
+| `/specweave:do` | Execute all tasks autonomously |
+| `/specweave:done 0001` | Complete with quality gate validation |
+| `/specweave:progress` | Show real-time status |
+| `/specweave:validate 0001` | Run quality checks |
+| `/specweave:sync-progress` | Sync to GitHub/JIRA/ADO |
+| `/specweave:tdd-cycle` | Full red-green-refactor workflow |
 
-### Three Reopen Levels
+**[Full Command Reference](https://spec-weave.com/docs/commands/overview)**
 
-**Task-Level** (Surgical Fix):
-```bash
-/specweave:reopen 0031 --task T-003 --reason "API rate limiting"
-```
+---
 
-**User Story-Level** (Feature Fix):
-```bash
-/specweave:reopen 0031 --user-story US-001 --reason "AC not met"
-```
+## Brownfield & Greenfield
 
-**Increment-Level** (Systemic Fix):
-```bash
-/specweave:reopen 0031 --reason "Multiple production issues"
-```
+**New Projects**: Start spec-driven from day one.
 
-### Complete Audit Trail
-
-Every reopen is tracked:
-```json
-{
-  "reopened": {
-    "count": 1,
-    "history": [
-      {
-        "date": "2025-11-14T15:30:00Z",
-        "reason": "GitHub sync failing",
-        "previousStatus": "completed"
-      }
-    ]
-  }
-}
+**Existing Projects**:
+```bash
+specweave init .
+/specweave:import-docs ~/exports/notion --source=notion
 ```
 
-**WIP Limits Respected** - No more "I'll just squeeze in one more fix" chaos!
+Import from Notion, Confluence, GitHub Wiki. AI classifies docs automatically and creates retroactive specifications.
 
 ---
 
-## 📖 Documentation
-
-**Complete guides, tutorials, and API reference:**
-
-### **[spec-weave.com](https://spec-weave.com)**
+## Requirements
 
-**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
+- Node.js 20+
+- Claude Code (recommended) or compatible AI assistant
+- Git repository
 
 ---
 
 ## Community
 
-- 💬 **[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
+- **[Documentation](https://spec-weave.com)** - Full guides and tutorials
+- **[Discord](https://discord.gg/UYg4BGJ65V)** - Get help, share tips
+- **[YouTube](https://www.youtube.com/@antonabyzov)** - Video tutorials
+- **[GitHub Issues](https://github.com/anton-abyzov/specweave/issues)** - Bug reports and features
 
 ---
 
 ## Contributing
 
 ```bash
-# Setup
 git clone https://github.com/anton-abyzov/specweave.git
 cd specweave
 npm install && npm run build
-
-# Test
 npm test
 ```
 
-**[→ Contributor Guide](https://spec-weave.com/docs/guides/contributing)**
-
----
-
-## Best with Claude Code
-
-SpecWeave works best with **[Claude Code](https://claude.com/claude-code)** (native plugins, auto-activating skills, lifecycle hooks).
-
-Also works with: Cursor, GitHub Copilot, ChatGPT (manual workflow).
-
-**[→ Tool Comparison](https://spec-weave.com/docs/overview/features#claude-code-native)**
+**[Contributor Guide](https://spec-weave.com/docs/guides/contributing)**
 
 ---
 
@@ -557,4 +352,8 @@ MIT - [github.com/anton-abyzov/specweave](https://github.com/anton-abyzov/specwe
 
 ---
 
-**Get started**: `npm install -g specweave` → **[Read the Docs](https://spec-weave.com)**
+**Stop losing your AI work. Start building permanent knowledge.**
+
+```bash
+npm install -g specweave
+```