specweave 0.11.0 → 0.12.1

package/.claude-plugin/marketplace.json

@@ -152,7 +152,7 @@
     },
     {
       "name": "specweave-docs-preview",
-      "description": "Documentation preview - Local Docusaurus server with auto-generated sidebar, hot reload, and beautiful UI. Auto-suggests after first increment. Keywords: docs, preview, documentation, browse docs",
+      "description": "Interactive documentation preview - Launch Docusaurus dev server with hot reload, auto-generated sidebar, Mermaid diagrams. Build static sites for deployment.",
       "source": "./plugins/specweave-docs-preview",
       "category": "productivity",
       "version": "1.0.0",

package/CLAUDE.md

@@ -964,49 +964,11 @@ After `specweave init`, ALL plugins are already installed. No additional steps n
 2. **All Capabilities Available**
    - GitHub integration: `/specweave-github:sync`
    - JIRA integration: `/specweave-jira:sync`
-   - Documentation preview: `/specweave:docs preview`
    - Frontend tools: React, Next.js, design systems
    - Backend tools: Node.js, Python, .NET
    - Infrastructure: Kubernetes, Helm, monitoring
    - ...and 19+ more plugins ready to use!
 
-#### Phase 3: First Increment Completion (Documentation Preview)
-
-After completing your first increment:
-
-1. **🎉 Post-First-Increment Hook** (NEW! v0.8.18+)
-   - Automatically triggers when first increment is marked complete
-   - Suggests docs-preview plugin for beautiful documentation UI
-   - Shows clear benefits and install command
-
-2. **Suggestion Format**:
-   ```
-   🎉 Congratulations! You completed your first increment!
-
-   📚 Preview your documentation in a beautiful UI?
-
-   The specweave-docs-preview plugin can generate a Docusaurus site from
-   your .specweave/docs/ folder with:
-
-      ✓ Auto-generated sidebar from folder structure
-      ✓ Hot reload (edit markdown, see changes instantly)
-      ✓ Mermaid diagram rendering
-      ✓ Priority sorting (Strategy → Specs → Architecture → ...)
-
-   📦 Install with:
-      /plugin install specweave-docs-preview
-
-   🚀 Then launch:
-      /specweave:docs preview
-   ```
-
-3. **Benefits**:
-   - Beautiful, searchable documentation site (Docusaurus 3.x)
-   - Live preview with hot reload (see changes in real-time)
-   - Auto-generated navigation from folder structure
-   - Mermaid diagrams rendered automatically
-   - Share docs with stakeholders (export static site)
-
 ### Plugin Management
 
 **All 19+ plugins are automatically installed during `specweave init`**. You rarely need to manage plugins manually, but Claude Code's native commands are available if needed:
@@ -2026,6 +1988,137 @@ ls -1 .specweave/increments/ | grep -E '^[0-9]{4}' | wc -l
 - ✅ **Compliance & auditing**: Complete audit trail of all product decisions
 - ✅ **Living documentation**: Specs stay up-to-date without manual intervention
 
+**Post-Increment-Planning Hook** (AUTOMATIC after `/specweave:increment`):
+
+**GitHub Issue Auto-Creation** (NEW in v0.8.20+):
+
+**The Critical Problem**: Without automatic GitHub issue creation, increments don't sync to GitHub automatically. This requires manual `/specweave-github:create-issue` calls, which are often forgotten.
+
+**The Solution**: The `post-increment-planning.sh` hook now auto-creates GitHub issues immediately after increment planning completes.
+
+**How It Works** (Automatic):
+1. **Hook Triggers**: After `/specweave:increment` completes planning (spec.md, plan.md, tasks.md created)
+2. **Auto-Create Check**: Checks if `config.sync.settings.autoCreateIssue` is enabled
+3. **GitHub CLI Available**: Verifies `gh` CLI is installed and authenticated
+4. **Issue Creation**:
+   - Extracts title from spec.md frontmatter (`title: "..."`)
+   - Extracts summary from "Quick Overview" section
+   - Generates task checklist from tasks.md (all tasks as GitHub checkboxes)
+   - Calls `gh issue create` with proper labels (`specweave`, `increment`)
+   - Parses output to get issue number
+5. **Metadata Update**: Creates/updates `.metadata.json` with GitHub issue number and URL
+6. **Result**: Increment is now linked to GitHub issue for bidirectional sync!
+
+**Configuration** (`.specweave/config.json`):
+```json
+{
+  "sync": {
+    "settings": {
+      "autoCreateIssue": true,  // ✅ Enable auto-creation!
+      "syncDirection": "bidirectional"
+    },
+    "activeProfile": "specweave-dev",
+    "profiles": {
+      "specweave-dev": {
+        "provider": "github",
+        "config": {
+          "owner": "anton-abyzov",
+          "repo": "specweave"
+        }
+      }
+    }
+  }
+}
+```
+
+**What Gets Created**:
+```markdown
+# [INC-0016] AI Self-Reflection System
+
+**Status**: Planning → Implementation
+**Priority**: P1
+**Increment**: 0016-self-reflection-system
+
+## Summary
+
+Add AI self-reflection capabilities inspired by Kimi model...
+
+## Tasks
+
+Progress: 0/30 tasks (0%)
+
+- [ ] T-001: Create Reflection Configuration Schema
+- [ ] T-002: Create Configuration Loader
+- [ ] T-003: Create Git Diff Analyzer
+... (all 30 tasks)
+
+## Links
+
+- **Spec**: `spec.md`
+- **Plan**: `plan.md`
+- **Tasks**: `tasks.md`
+
+---
+
+🤖 Auto-created by SpecWeave | Updates automatically on task completion
+```
+
+**Error Handling** (Robust):
+- ✅ **Missing files**: Graceful fallback if spec.md or tasks.md missing
+- ✅ **Title extraction**: Multiple fallbacks (frontmatter → heading → increment ID)
+- ✅ **Overview extraction**: Tries "Quick Overview", "Summary", or first paragraph
+- ✅ **Task count**: Extracts from frontmatter or counts tasks
+- ✅ **GitHub CLI failures**: Non-blocking (logs error, continues)
+- ✅ **Duplicate prevention**: Checks metadata.json for existing issue number
+- ✅ **Repository detection**: Auto-detects from git remote or config
+
+**Manual Override** (When Needed):
+```bash
+# Disable auto-create for one increment
+# Just don't set autoCreateIssue in config
+
+# Or create manually if auto-create failed
+/specweave-github:create-issue 0016
+
+# Check if issue was created
+cat .specweave/increments/0016-self-reflection-system/metadata.json
+# Should show: "github": {"issue": 30, "url": "..."}
+```
+
+**Why This Matters**:
+- ✅ **Zero manual work**: Issues auto-create on every increment
+- ✅ **Immediate tracking**: Increment linked to GitHub from start
+- ✅ **Bidirectional sync**: Task completion updates GitHub automatically
+- ✅ **Team visibility**: Stakeholders see progress in GitHub without asking
+- ✅ **Audit trail**: All increments tracked in one place
+- ✅ **DORA metrics**: Automatic deployment frequency tracking
+
+**Workflow Example**:
+```bash
+# 1. Create increment
+/specweave:increment "AI self-reflection system"
+
+# 2. Hook auto-fires:
+# 🔗 Checking GitHub issue auto-creation...
+#   📦 Auto-create enabled, checking for GitHub CLI...
+#   ✓ GitHub CLI found
+#   🚀 Creating GitHub issue for 0016-self-reflection-system...
+#   📝 Issue #30 created
+#   🔗 https://github.com/anton-abyzov/specweave/issues/30
+#   ✅ metadata.json updated
+
+# 3. Start work
+/specweave:do
+
+# 4. Complete tasks → GitHub updates automatically via post-task-completion hook!
+```
+
+**Requirements**:
+- GitHub CLI (`gh`) installed and authenticated (`gh auth login`)
+- Repository with GitHub remote configured
+- `autoCreateIssue: true` in config.json
+- Write permissions to repository
+
 ---
 
 ## Plugins
@@ -2596,112 +2689,6 @@ vim docs-site/docs/guides/getting-started.md
 cd docs-site && npm run build
 ```
 
-### Documentation Preview (specweave-docs-preview plugin)
-
-**Live preview of `.specweave/docs/` with Docusaurus** - Beautiful UI with hot reload, auto-generated sidebar, and Mermaid diagram support.
-
-**When to Use**:
-- ✅ After completing your first increment (auto-suggested)
-- ✅ Reviewing documentation in a beautiful UI instead of raw markdown
-- ✅ Sharing documentation with non-technical stakeholders
-- ✅ Preparing documentation for external publication
-
-**Installation** (auto-prompted after first increment):
-
-The `post-first-increment.sh` hook automatically prompts you after completing your first increment:
-
-```
-🎉 Congratulations! You completed your first increment!
-
-📚 Would you like to preview your documentation in a beautiful UI?
-
-Options:
-  1) Yes, install and launch now (recommended)
-  2) No thanks, I'll browse markdown files manually
-  3) Remind me later
-
-Your choice [1]:
-```
-
-**Manual Commands**:
-
-```bash
-# Launch preview (installs Docusaurus if needed)
-/specweave:docs preview
-
-# Specify port
-/specweave:docs preview --port 3001
-
-# Build static site for deployment
-/specweave:docs build
-
-# Output: .specweave/docs-site-internal/build/
-```
-
-**Features**:
-- ✅ **Auto-generated sidebar** from `.specweave/docs/internal/` folder structure
-- ✅ **Hot reload** - Edit markdown files and see changes instantly
-- ✅ **Mermaid diagrams** - Automatic rendering of diagrams
-- ✅ **Priority sorting** - Strategy → Specs → Architecture → Delivery → Operations → Governance
-- ✅ **Port auto-discovery** - Finds available port (3000-3010)
-- ✅ **Cross-platform** - Windows/macOS/Linux compatible
-
-**What Gets Indexed**:
-- `.specweave/docs/internal/strategy/` - Business rationale, PRDs
-- `.specweave/docs/internal/specs/` - Feature specifications
-- `.specweave/docs/internal/architecture/` - Technical design, ADRs
-- `.specweave/docs/internal/delivery/` - Build & release processes
-- `.specweave/docs/internal/operations/` - Runbooks, SLOs
-- `.specweave/docs/internal/governance/` - Policies, security
-
-**What Gets Excluded**:
-- ❌ `legacy/` folder (brownfield imports, temporary)
-- ❌ `node_modules/`, `.git/`
-- ❌ `.specweave/increments/` (implementation details, not strategic docs)
-
-**Configuration** (`.specweave/config.json`):
-
-```json
-{
-  "documentation": {
-    "preview": {
-      "enabled": true,
-      "autoInstall": true,
-      "port": 3000,
-      "openBrowser": true,
-      "theme": "default",
-      "excludeFolders": ["legacy", "node_modules"]
-    }
-  }
-}
-```
-
-**Requirements**:
-- Node.js 18+ (Docusaurus 3.0 requirement)
-- ~150 MB disk space for npm packages
-- ~30 seconds first-time install
-
-**Files Created** (gitignored):
-- `.specweave/docs-site-internal/` - Complete Docusaurus installation for internal docs
-  - `package.json` - Dependencies
-  - `docusaurus.config.js` - Configuration
-  - `sidebars.js` - Auto-generated sidebar
-  - `src/` - Landing page and custom CSS
-  - `node_modules/` - npm packages
-  - `build/` - Static site output (after build)
-
-**Note**: This is separate from `docs-site/` (public-facing docs at project root)
-
-**Implementation**:
-- Plugin: `plugins/specweave-docs-preview/`
-- TypeScript utilities: `src/utils/docs-preview/`
-- CLI commands: `src/cli/commands/docs-{preview,build,setup}.ts`
-- Hook: `plugins/specweave/hooks/post-first-increment.sh`
-
-**See Also**:
-- Plugin docs: `plugins/specweave-docs-preview/skills/docs-preview/SKILL.md`
-- Command docs: `plugins/specweave-docs-preview/commands/docs-preview.md`
-
 ### Translation Workflow (Multilingual Support)
 
 **SpecWeave supports multilingual development** via two-phase post-generation translation (Increment 0006).

package/README.md

@@ -10,26 +10,64 @@
 
 ---
 
-## The Problem
+## 📊 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://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)
+
+**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/metrics/dora-report.md)**
+
+---
+
+## 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.**
+
+---
+
+## Want to Scale? Get Enterprise-Ready.
+
+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.
 
-AI coding assistants made us **10x faster at shipping**, but **100x worse at maintaining**.
+**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)
 
-Your AI writes features in 30 minutes. You spend 3 days updating docs. By day 4, the code changed again.
+This isn't bureaucracy. **This is how you get paid.**
 
-**The docs? Already wrong.**
+But for solo devs and small teams? Impossible to maintain manually.
 
 ---
 
-## The Solution
+## SpecWeave: Enterprise Standards, Zero Overhead
+
+Living documentation that updates automatically after every task.
+
+The same processes Fortune 500 uses. Without the team. Without the manual work.
 
-**Fortune 500 discipline. Zero overhead. AI-native.**
+✅ **Architecture decisions documented** - Pass audits, land enterprise deals
 
-SpecWeave brings enterprise-grade processes (PRDs, HLDs, ADRs, runbooks) to developers of any size—without the bureaucracy.
+✅ **Onboarding automated** - New devs productive in 1 hour, not 1 week
 
-> *"Dad, AI writes your code but you update docs MANUALLY?"*
-> — My 14-year-old daughter (who was absolutely right)
+✅ **Knowledge preserved** - Sell your startup, someone can actually run it
 
-**Living docs that ACTUALLY stay synced** - Automatically updated after every task. No manual intervention.
+✅ **Standards enforced** - SOC2, ISO, compliance requirements met
+
+**AI speed + Enterprise reliability = You can finally scale.**
 
 ---
 
@@ -118,17 +156,6 @@ specweave init .
 
 ---
 
-## 📊 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://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)
-
-**[→ Live Dashboard](https://spec-weave.com/docs/metrics)** | **[→ Detailed Report](https://github.com/anton-abyzov/specweave/blob/develop/metrics/dora-report.md)**
-
----
-
 ## Key Features
 
 - 🧪 **Test-Aware Planning** - Embedded tests in BDD format (Given/When/Then)

package/dist/cli/commands/init.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"init.d.ts","sourceRoot":"","sources":["../../../src/cli/commands/init.ts"],"names":[],"mappings":"AAoBA,UAAU,WAAW;IACnB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,wBAAsB,WAAW,CAC/B,WAAW,CAAC,EAAE,MAAM,EACpB,OAAO,GAAE,WAAgB,GACxB,OAAO,CAAC,IAAI,CAAC,CA+tBf"}
+{"version":3,"file":"init.d.ts","sourceRoot":"","sources":["../../../src/cli/commands/init.ts"],"names":[],"mappings":"AAoBA,UAAU,WAAW;IACnB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,wBAAsB,WAAW,CAC/B,WAAW,CAAC,EAAE,MAAM,EACpB,OAAO,GAAE,WAAgB,GACxB,OAAO,CAAC,IAAI,CAAC,CA4qBf"}

package/dist/cli/commands/init.js

@@ -416,76 +416,8 @@ export async function initCommand(projectName, options = {}) {
                 });
             }
         }
-        // 13. Documentation preview prompt (Claude Code only)
-        let enableDocsPreview = true; // Default: enabled
-        if (toolName === 'claude') {
-            try {
-                spinner.stop();
-                console.log('');
-                console.log(chalk.cyan('📚 Documentation Preview'));
-                console.log('');
-                console.log(chalk.white('   View your living documentation in a beautiful UI:'));
-                console.log(chalk.gray('   • Auto-generated sidebar from folder structure'));
-                console.log(chalk.gray('   • Hot reload (edit markdown, see changes instantly)'));
-                console.log(chalk.gray('   • Mermaid diagram rendering'));
-                console.log(chalk.gray('   • Installs dependencies on first use'));
-                console.log('');
-                const response = await inquirer.prompt([
-                    {
-                        type: 'confirm',
-                        name: 'enableDocsPreview',
-                        message: 'Enable documentation preview?',
-                        default: true
-                    }
-                ]);
-                enableDocsPreview = response.enableDocsPreview;
-                if (enableDocsPreview) {
-                    console.log(chalk.green('   ✔ Documentation preview enabled'));
-                    // 🚨 CRITICAL FIX: Actually install the docs-preview plugin!
-                    // User said Yes → Install plugin immediately (like issue tracker setup)
-                    if (detectClaudeCli()) {
-                        console.log(chalk.gray('   → Installing specweave-docs-preview plugin...'));
-                        try {
-                            const result = execFileNoThrowSync('claude', [
-                                'plugin',
-                                'install',
-                                'specweave-docs-preview' // NO @marketplace suffix
-                            ]);
-                            if (result.success) {
-                                console.log(chalk.green('   ✔ specweave-docs-preview plugin installed'));
-                                console.log(chalk.gray('   → Preview with: /specweave:docs preview'));
-                            }
-                            else {
-                                console.log(chalk.yellow('   ⚠️  Plugin install failed (can install later)'));
-                                console.log(chalk.gray('   → Try manually: /plugin install specweave-docs-preview'));
-                            }
-                        }
-                        catch (error) {
-                            console.log(chalk.yellow('   ⚠️  Plugin install failed (can install later)'));
-                            console.log(chalk.gray('   → Try manually: /plugin install specweave-docs-preview'));
-                        }
-                    }
-                    else {
-                        console.log(chalk.gray('   → Preview with: /specweave:docs preview'));
-                        console.log(chalk.yellow('   ⚠️  Claude CLI not detected - install plugin manually:'));
-                        console.log(chalk.gray('   → /plugin install specweave-docs-preview'));
-                    }
-                }
-                else {
-                    console.log(chalk.gray('   → Skipped (can enable later in .specweave/config.json)'));
-                }
-                console.log('');
-                spinner.start();
-            }
-            catch (error) {
-                // Non-critical - continue with default (enabled)
-                if (process.env.DEBUG) {
-                    console.error(chalk.red(`\n❌ Docs preview prompt error: ${error.message}`));
-                }
-            }
-        }
-        // 14. Create config.json with language setting and docs preview
-        createConfigFile(targetDir, finalProjectName, toolName, language, enableDocsPreview);
+        // 13. Create config.json with language setting
+        createConfigFile(targetDir, finalProjectName, toolName, language, false);
         // 14. Setup Claude Code plugin auto-registration (if Claude detected)
         let autoInstallSucceeded = false;
         if (toolName === 'claude') {
@@ -672,6 +604,25 @@ export async function initCommand(projectName, options = {}) {
                     autoInstallSucceeded = false;
                 }
             }
+            // 10.5 Issue Tracker Integration (CRITICAL!)
+            // MUST happen AFTER plugin installation is complete
+            // Asks user: Which tracker? (GitHub/Jira/ADO/None)
+            // Collects credentials and runs smart validation
+            try {
+                const { setupIssueTracker } = await import('../helpers/issue-tracker/index.js');
+                await setupIssueTracker({
+                    projectPath: targetDir,
+                    language: language,
+                    maxRetries: 3
+                });
+            }
+            catch (error) {
+                // Non-critical error - log but continue
+                if (process.env.DEBUG) {
+                    console.error(chalk.red(`\n❌ Issue tracker setup error: ${error.message}`));
+                }
+                console.log(chalk.yellow('\n⚠️  Issue tracker setup skipped (can configure later)'));
+            }
         }
         showNextSteps(finalProjectName, toolName, language, usedDotNotation, toolName === 'claude' ? autoInstallSucceeded : undefined);
     }