specweave 0.18.1 → 0.20.1

package/src/templates/CLAUDE.md.template

@@ -22,8 +22,7 @@ This project uses **SpecWeave** - a specification-first AI development framework
 .specweave/increments/0001-user-auth/
 ├── spec.md                            # Core spec files
 ├── plan.md
-├── tasks.md
-├── tests.md
+├── tasks.md                           # Tasks with embedded tests (BDD format)
 ├── reports/                           # ✅ PUT REPORTS HERE!
 │   ├── SESSION-SUMMARY.md
 │   └── ANALYSIS-REPORT.md
@@ -47,6 +46,48 @@ This project uses **SpecWeave** - a specification-first AI development framework
 
 ---
 
+## 📋 Quick Reference Cards
+
+### Daily Workflow
+```
+┌────────────────────────────────────────────────────────────┐
+│ TASK                    → COMMAND                          │
+├────────────────────────────────────────────────────────────┤
+│ Plan new feature        → /specweave:increment "feature"   │
+│ Execute tasks           → /specweave:do                    │
+│ Check progress          → /specweave:progress              │
+│ Validate quality        → /specweave:validate 0001         │
+│ Close increment         → /specweave:done 0001             │
+│ Sync to GitHub          → /specweave:github:sync           │
+│ Sync to Jira            → /specweave:jira:sync             │
+└────────────────────────────────────────────────────────────┘
+```
+
+### When to Use Which Command
+| User Says...              | Use Command                        |
+|---------------------------|------------------------------------|
+| "Let's build X"           | `/specweave:increment "X"`         |
+| "Start implementing"      | `/specweave:do`                    |
+| "What's the status?"      | `/specweave:progress`              |
+| "Is this ready?"          | `/specweave:validate 0001`         |
+| "We're done"              | `/specweave:done 0001`             |
+| "Sync to GitHub"          | `/specweave:github:sync`           |
+| "Sync to Jira"            | `/specweave:jira:sync`             |
+
+### File Organization Rules
+```
+┌────────────────────────────────────────────────────────────┐
+│ NEVER in Root           ↔ ALWAYS in Increment Folder      │
+├────────────────────────────────────────────────────────────┤
+│ ❌ analysis.md          ↔ ✅ .../0001/reports/analysis.md  │
+│ ❌ migration.py         ↔ ✅ .../0001/scripts/migration.py │
+│ ❌ execution.log        ↔ ✅ .../0001/logs/execution.log   │
+│ ❌ session-notes.md     ↔ ✅ .../0001/reports/session.md   │
+└────────────────────────────────────────────────────────────┘
+```
+
+---
+
 ## SpecWeave Workflow (Use These Commands!)
 
 **How SpecWeave works**:
@@ -56,7 +97,7 @@ This project uses **SpecWeave** - a specification-first AI development framework
 ```
 
 **1. Plan Feature** → `/specweave:increment "user authentication"`
-   - Creates spec.md (WHAT/WHY), plan.md (HOW), tasks.md, tests.md
+   - Creates spec.md (WHAT/WHY), plan.md (HOW), tasks.md (with embedded tests)
    - PM-led process with architect/security/QA review
    - **Use when**: Starting any new feature or increment
 
@@ -69,9 +110,9 @@ This project uses **SpecWeave** - a specification-first AI development framework
    - Shows task completion %, next action
    - **Use when**: Want to see status
 
-**4. Validate Quality** → `/specweave:validate 0001` or `/specweave:validate 0001 --quality`
-   - Rule-based validation (120 checks)
-   - Optional AI quality assessment
+**4. Validate Quality** → `/specweave:validate 0001` or `/specweave:qa 0001`
+   - Rule-based validation (120 checks) or AI quality assessment with risk scoring
+   - Validates tasks, tests (embedded in tasks.md), and documentation
    - **Use when**: Verify increment quality before completion
 
 **5. Close Increment** → `/specweave:done 0001`
@@ -128,6 +169,26 @@ ls -1 .specweave/increments/ | grep -E "^[0-9]{4}-" | sort | tail -5
    - Azure DevOps - Work item updates automatically
    - **Configurable**: Set `external_tracker_sync: true` in `.specweave/config.json`
 
+### 🏷️ GitHub Sync Mapping (Universal Hierarchy)
+
+**SpecWeave follows strict hierarchy for GitHub sync:**
+
+| SpecWeave Entity | GitHub Mapping | Example |
+|------------------|----------------|---------|
+| **Feature** (FS-XXX) | **Milestone** | `FS-031: External Tool Status Sync` |
+| **User Story** (US-XXX) | **Issue** | `[FS-031][US-002] Task-Level Mapping` |
+| **Task** (T-XXX) | **Checkbox** | `- [ ] T-001: Implement validator` |
+
+**Key Principles**:
+- ✅ **Features → Milestones** (container for all User Stories)
+- ✅ **User Stories → Issues** (each US-* file = separate GitHub issue)
+- ✅ **Tasks → Checkboxes** (listed in User Story issue body)
+- ❌ **NEVER create Feature-level issues** (Features are Milestones!)
+
+**⛔ DEPRECATED**:
+- ❌ `[INC-XXXX]` - Old increment format (pre-v0.18.0)
+- ❌ `[FS-XXX] Feature Title` as issue - Feature-level issues (pre-v0.19.0, wrong!)
+
 3. **Sound Notifications**:
    - Plays sound when tasks complete (helps you know when to review)
    - Platform-specific: Glass.aiff (macOS), system sounds (Linux/Windows)
@@ -235,7 +296,7 @@ Both approaches work perfectly - use whichever feels more natural!
 .specweave/increments/0001-user-auth/   # ⚠️ ID must be unique!
 ├── spec.md                      # WHAT & WHY
 ├── plan.md                      # HOW
-├── tasks.md                     # Implementation steps with embedded tests
+├── tasks.md                     # Tasks with embedded test plans (BDD format)
 ├── context-manifest.yaml        # Selective context loading
 ├── logs/                        # ✅ Execution logs, errors, AI sessions
 ├── scripts/                     # ✅ Helper scripts, migrations, setup
@@ -309,6 +370,26 @@ project-root/
 - ✅ **Automatic**: No manual linking needed
 - ✅ **Multi-project aware**: Works with backend, frontend, mobile, etc.
 - ✅ **Always in sync**: Links created during `/specweave:done`
+- ✅ **NEW (v0.18.3+)**: User stories include project-specific checkable task lists
+
+### Project-Specific Tasks (v0.18.3+)
+
+**NEW**: User stories now have their OWN checkable task lists, not just links!
+
+```markdown
+## Tasks
+
+- [ ] **T-001**: Setup API endpoint
+- [x] **T-003**: Add DB migration (completed)
+
+> **Note**: Tasks are project-specific. See increment tasks.md for full list
+```
+
+**Benefits**:
+- **Project Isolation**: Backend tasks ≠ Frontend tasks
+- **GitHub UX**: Checkable task lists in GitHub issues
+- **Traceability**: Each user story explicitly lists its tasks
+- **Completion Tracking**: Status synced from increment tasks.md
 
 **For complete details**: Ask me about "bidirectional linking" or check `.specweave/docs/internal/specs/default/README.md`
 
@@ -421,86 +502,37 @@ Config: Auto-detected from project files
 
 ---
 
-## Plugin Architecture
-
-**SpecWeave uses Claude Code's native plugin system** for optional capabilities.
+## Plugins
 
-### Core vs. Plugins
+SpecWeave uses Claude Code's native plugin system. All plugins auto-install during `specweave init`.
 
-**Core Framework** (always loaded):
-- 9 core skills (increment-planner, tdd-workflow, context-loader, etc.)
-- 3 core agents (PM, Architect, Tech Lead)
-- 7 core commands (`/specweave:increment`, `/specweave:do`, etc.)
-- ~12K tokens (lightweight!)
-
-**Plugins** (opt-in based on your stack):
-- Tech stacks: `specweave-frontend`, `specweave-backend`, `specweave-kubernetes`
-- Integrations: `specweave-github`, `specweave-jira`
-- Domains: `specweave-ml`, `specweave-payments`, `specweave-testing`
-
-### Using Plugin Commands
-
-**Core commands** (always available):
-```bash
-/specweave:increment "feature"
-/specweave:do
-/specweave:progress
-```
-
-**Plugin commands** (when plugin installed):
-```bash
-# GitHub plugin:
-/specweave:github:sync          # Sync increments to GitHub issues
-/specweave:github:create-issue  # Create new issue
-/specweave:github:status        # Check sync status
-
-# Jira plugin:
-/specweave:jira:sync           # Sync to Jira
-/specweave:jira:create-ticket  # Create Jira ticket
-```
-
-**Plugin agents and skills activate automatically** based on your tech stack and context.
-
-### Installing Plugins
+**Enabled plugins**: {ENABLED_PLUGINS}
 
-Plugins are detected and suggested during `specweave init` based on:
-- Git remote (GitHub detected → suggest github plugin)
-- Tech stack (React detected → suggest frontend plugin)
-- Project files (K8s yamls → suggest kubernetes plugin)
+**Plugin commands** (examples):
+- `/specweave:github:sync` - Sync to GitHub
+- `/specweave:jira:sync` - Sync to Jira
 
-**Enabled plugins**: {ENABLED_PLUGINS}
+Skills/agents activate automatically based on context.
 
 ---
 
-## Documentation Philosophy
+## Documentation Approach
 
 **You chose**: {DOCUMENTATION_APPROACH}
 
 {#IF_COMPREHENSIVE}
-### Comprehensive Upfront Approach
-- Create complete specifications before coding (scope-appropriate detail)
-- All ADRs documented in advance
-- Best for: Enterprise, regulated industries, large teams, complex systems
-- Spec size scales with project complexity (10-500+ pages depending on scope)
+**Comprehensive** - Detailed specs upfront, best for enterprise/regulated industries.
 {#ENDIF}
 
 {#IF_INCREMENTAL}
-### Incremental/Evolutionary Approach
-- Start with overview (10-20 pages)
-- Build documentation as you go
-- Best for: Startups, MVPs, small teams
+**Incremental** - Build docs as you go, best for startups/MVPs.
 {#ENDIF}
 
 ---
 
-## Frequently Asked Questions
+## Quick Reference
 
-**New to SpecWeave?** Check out the [FAQ](https://spec-weave.com/docs/faq) for answers to common questions:
-
-### Quick Answers
-- **Why specs in two locations?** Living Docs (permanent, complete feature) vs Increment Specs (temporary, current work)
-- **When do I need living docs spec?** Major features (3+ increments), brownfield integration, or external PM tools
-- **Can I delete increment specs?** YES, after completion. Living docs specs are NEVER deleted (permanent)
+**Need help?** [SpecWeave Docs](https://spec-weave.com/docs)
 - **Which spec is source of truth?** Living docs spec (when it exists), otherwise increment spec
 
 ### Key Topics Covered
@@ -519,11 +551,13 @@ Plugins are detected and suggested during `specweave init` based on:
 ## Testing
 
 **Four Levels**:
-1. **Specification** (`.specweave/docs/internal/strategy/`) - Acceptance criteria
-2. **Feature** (`.specweave/increments/####/tests.md`) - Test coverage per increment
+1. **Specification** (`.specweave/docs/internal/strategy/`) - Acceptance criteria (AC-IDs)
+2. **Feature** (`.specweave/increments/####/tasks.md`) - Test plans embedded in tasks (BDD format)
 3. **Integration** (`tests/integration/` or `tests/specs/`) - Component/module tests
 4. **Code** (`tests/`) - Automated tests (Unit, Integration, E2E)
 
+**Test-Aware Planning**: Tests are embedded in tasks.md using BDD format (Given/When/Then), with AC-ID traceability and realistic coverage targets (80-90%).
+
 **Requirements**:
 - E2E tests when UI exists
 - >80% coverage for critical paths
@@ -531,24 +565,6 @@ Plugins are detected and suggested during `specweave init` based on:
 
 ---
 
-## Quick Reference Card
-
-### When to Use Each Command
-
-| User Says | Use Command | What It Does |
-|-----------|-------------|--------------|
-| "Let's build [feature]" | `/specweave:increment "[feature]"` | Plan new increment |
-| "Start implementing" | `/specweave:do` | Execute tasks (smart resume) |
-| "What's the status?" | `/specweave:progress` | Show task completion % |
-| "Is this ready?" | `/specweave:validate 0001` | Validate increment quality |
-| "We're done" | `/specweave:done 0001` | Close increment |
-
-**Plugin Commands** (when installed):
-| "Sync to GitHub" | `/specweave:github:sync` | Export to GitHub issues |
-| "Sync to Jira" | `/specweave:jira:sync` | Export to Jira |
-
----
-
 ## Key SpecWeave Principles
 
 1. **Specification-First**: Always start with `/specweave:increment` to create specs before coding
@@ -569,6 +585,90 @@ Plugins are detected and suggested during `specweave init` based on:
 
 ---
 
+## 🆘 Troubleshooting
+
+### Skills Not Activating
+
+**Symptoms**: Expected skill didn't load automatically
+
+**Solutions**:
+1. Restart Claude Code (skills loaded at startup)
+2. Check keywords: Skills activate based on description keywords
+3. Verify plugin installed: Use `/plugin list --installed`
+4. Manual check: Look in `.claude/skills/SKILLS-INDEX.md` for available skills
+
+### Commands Not Found
+
+**Symptoms**: `/specweave:increment` doesn't work
+
+**Solutions**:
+1. Verify plugin installed: `/plugin list --installed`
+2. Check installed commands: `ls .claude/commands/`
+3. Restart Claude Code
+4. Re-run: `specweave init` if plugins missing
+
+### Root Folder Polluted
+
+**Symptoms**: `git status` shows `.md` files in project root
+
+**Solutions**:
+1. **Immediate fix**: Move files to increment folder
+   ```bash
+   mv SESSION-NOTES.md .specweave/increments/0001/reports/
+   mv analysis.md .specweave/increments/0001/reports/
+   ```
+2. Check `.gitignore` is up to date
+3. Commit cleaned structure:
+   ```bash
+   git add .
+   git commit -m "fix: move reports to increment folder"
+   ```
+
+### Increment Numbers Not Unique
+
+**Symptoms**: Multiple increments with same number (0001, 0001, etc.)
+
+**Solutions**:
+1. Check existing: `ls -1 .specweave/increments/ | grep -E "^[0-9]{4}-"`
+2. Use next available number
+3. If duplicates exist, run: `/specweave:fix-duplicates`
+
+### External Tracker Not Syncing
+
+**Symptoms**: GitHub/Jira not updating after task completion
+
+**Solutions (Claude Code)**:
+1. Check config: `.specweave/config.json` has `external_tracker_sync: true`
+2. Verify hook exists: `ls plugins/specweave-github/hooks/post-task-completion.sh`
+3. Check credentials: `gh auth status` or `jira config list`
+4. Manual sync: `/specweave:github:sync 0001`
+
+### Tasks.md Out of Sync
+
+**Symptoms**: Progress shows 0/24 but many tasks done
+
+**Solutions**:
+1. Auto-sync from reality: `/specweave:sync-tasks`
+2. Manual update: Edit tasks.md, change `[ ]` to `[x]`
+3. Recalculate progress counters
+
+### Can't Find Increment
+
+**Symptoms**: Don't know which increment is active
+
+**Solutions**:
+1. Check status: `/specweave:status` (shows all increments)
+2. Check progress: `/specweave:progress` (shows active increment)
+3. View active: `cat .specweave/state/active-increment.json`
+
+### More Help
+
+**Documentation**: https://spec-weave.com/docs/troubleshooting
+**GitHub Issues**: https://github.com/anton-abyzov/specweave/issues
+**Discussions**: https://github.com/anton-abyzov/specweave/discussions
+
+---
+
 ## Getting Started
 
 **Create your first feature**:

package/dist/locales/de/cli.json

@@ -1,108 +0,0 @@
-{
-  "init": {
-    "welcome": "🚀 SpecWeave Initialization",
-    "projectName": "Project name:",
-    "projectNamePrompt": "Project name (for templates):",
-    "projectNameDefault": "my-saas",
-    "detectingTool": "Detecting AI tool...",
-    "foundClaude": "✅ Found Claude Code",
-    "foundCursor": "✅ Found Cursor",
-    "foundCopilot": "✅ Found GitHub Copilot",
-    "noToolDetected": "No AI tool detected, using Generic adapter",
-    "complete": "✨ Initialization complete!",
-    "claudeNativeComplete": "✨ Claude Code native installation complete!",
-    "claudeNativeBenefits": "✅ Native skills, agents, hooks work out of the box",
-    "projectSuccess": "SpecWeave project created successfully!",
-    "readyToBuild": "🚀 Ready to build with SpecWeave!",
-    "errors": {
-      "invalidName": "Project name must contain only lowercase letters, numbers, and hyphens",
-      "alreadyExists": ".specweave directory already exists",
-      "cancelled": "❌ Initialization cancelled",
-      "invalidLanguage": "❌ Invalid language: {{language}}",
-      "supportedLanguages": "Supported languages: {{languages}}",
-      "nestedNotSupported": "❌ Nested .specweave/ folders are NOT supported!",
-      "parentFound": "Found parent .specweave/ at:",
-      "projectCreationFailed": "Failed to create project",
-      "commandsCopyFailed": "❌ Commands copy failed: {{error}}",
-      "agentsCopyFailed": "❌ Agents copy failed: {{error}}",
-      "skillsCopyFailed": "❌ Skills copy failed: {{error}}",
-      "hooksCopyFailed": "❌ Hooks copy failed: {{error}}"
-    },
-    "warnings": {
-      "invalidDirName": "⚠️  Current directory name '{{dirName}}' contains invalid characters.",
-      "directoryNotEmpty": "⚠️  Current directory contains {{count}} file{{plural}}.",
-      "skillsIndexWarning": "⚠️  Warning: Could not generate skills index: {{error}}",
-      "skillsIndexNote": "Skills will still work, but manual indexing may be needed."
-    },
-    "prompts": {
-      "confirmInitInCurrent": "Initialize SpecWeave in current directory?",
-      "overwriteSpecweave": ".specweave directory already exists. Overwrite?",
-      "overwriteDirectory": "Directory {{projectName}} already exists. Overwrite?",
-      "enablePlugins": "Enable suggested plugins now?"
-    },
-    "info": {
-      "nestedEnforcement": "SpecWeave enforces a single source of truth:",
-      "nestedBullet1": "• Use the parent folder for all increments",
-      "nestedBullet2": "• Increments can span multiple subdirectories",
-      "nestedBullet3": "• See CLAUDE.md section \"Root-Level .specweave/ Folder\"",
-      "nestedToFix": "To fix:",
-      "suggestedPlugins": "💡 Suggested Plugins:",
-      "copiedFiles": "✓ Copied {{count}} command files",
-      "copiedAgents": "✓ Copied {{count}} agent directories",
-      "copiedSkills": "✓ Copied {{count}} skill directories",
-      "copiedHooks": "✓ Copied {{count}} hook files"
-    },
-    "progress": {
-      "creatingProject": "Creating SpecWeave project...",
-      "detected": "Detected {{tool}}...",
-      "usingTool": "Using {{tool}}...",
-      "directoryCreated": "Directory structure created...",
-      "templatesCopied": "Base templates copied...",
-      "installingComponents": "Installing Claude Code components...",
-      "commandsInstalled": "Slash commands installed...",
-      "agentsInstalled": "Agents installed...",
-      "skillsInstalled": "Skills installed...",
-      "hooksInstalled": "Hooks installed...",
-      "generatingIndex": "Generating skills index...",
-      "indexGenerated": "Skills index generated...",
-      "installingAdapter": "Installing {{tool}} adapter...",
-      "projectSuccess": "SpecWeave project created successfully!",
-      "detectingPlugins": "Detecting plugins...",
-      "detectedPlugins": "Detected {{count}} suggested plugins",
-      "enablingPlugins": "Enabling plugins...",
-      "enabledPlugin": "Enabled {{plugin}}",
-      "pluginsEnabled": "Plugins enabled"
-    },
-    "nextSteps": {
-      "header": "🎯 Next steps:",
-      "cd": "cd {{projectName}}",
-      "footer": "🚀 Ready to build with SpecWeave!",
-      "docsLink": "Documentation: https://spec-weave.com",
-      "githubLink": "GitHub: https://github.com/anton-abyzov/specweave"
-    }
-  },
-  "increment": {
-    "creating": "📝 Creating increment: {name}",
-    "created": "✅ Increment {id} created successfully!",
-    "nextStepDo": "Next: Run /specweave.do to start implementation",
-    "errors": {
-      "incompleteFound": "Cannot create new increment! Previous increments incomplete"
-    }
-  },
-  "progress": {
-    "currentIncrement": "Current Increment: {id}",
-    "status": "Status: {status}",
-    "completion": "Completion: {percent}%"
-  },
-  "translate": {
-    "translating": "🌐 Translating content to {language}...",
-    "complete": "✅ Translation complete!"
-  },
-  "version": {
-    "current": "SpecWeave version: {version}"
-  },
-  "errors": {
-    "fileNotFound": "❌ File not found: {path}",
-    "invalidConfig": "❌ Invalid configuration: {error}"
-  }
-}