specweave 0.18.1 → 0.20.0

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/plugins/specweave-ado/commands/specweave-ado-sync-spec.md

@@ -1,255 +0,0 @@
----
-name: specweave-ado-sync-spec
-description: Sync SpecWeave spec to Azure DevOps Feature (bidirectional). Use when syncing .specweave/docs/internal/specs/spec-*.md files with ADO Features for permanent feature tracking.
----
-
-# Sync Spec to Azure DevOps Feature
-
-**CORRECT ARCHITECTURE**: This command syncs `.specweave/docs/internal/specs/spec-*.md` files (PERMANENT living docs) to Azure DevOps Features, NOT increments to work items.
-
-## Usage
-
-```bash
-/specweave-ado:sync-spec <spec-id> [--direction <to-ado|from-ado|bidirectional>]
-```
-
-## What It Does
-
-**Architecture**:
-- **Spec → ADO Feature** (not increment → work item!)
-- **User Story → ADO User Story** (child of feature)
-- **Acceptance Criteria → Checklist** (in user story description)
-
-**Sync Process**:
-
-1. **Load spec** from `.specweave/docs/internal/specs/spec-{id}.md`
-2. **Load ADO configuration** from `.env` (organization, project, PAT)
-3. **Create or update ADO Feature**:
-   - Title: `[SPEC-001] Feature Title`
-   - Description: Spec overview + progress (HTML)
-   - State: Matches spec status
-4. **Sync user stories as ADO User Stories**:
-   - Create user stories for new user stories
-   - Update existing user stories
-   - Update state based on user story status
-5. **Link spec to feature** (update frontmatter)
-
-## Examples
-
-### Sync spec to ADO (create or update)
-
-```bash
-/specweave-ado:sync-spec spec-001
-```
-
-**Output**:
-```
-🔄 Syncing spec spec-001 to ADO Feature...
-   Creating new ADO Feature...
-   ✅ Created ADO Feature #456: https://dev.azure.com/org/project/_workitems/edit/456
-   Syncing 35 user stories...
-   ✅ Created US-001 → User Story #457
-   ✅ Created US-002 → User Story #458
-   ...
-✅ Sync complete!
-   Created: 35 user stories
-   ADO Feature: https://dev.azure.com/org/project/_workitems/edit/456
-```
-
-### Sync FROM ADO to spec (bidirectional)
-
-```bash
-/specweave-ado:sync-spec spec-001 --direction from-ado
-```
-
-**Output**:
-```
-🔄 Syncing FROM ADO to spec spec-001...
-   Fetching ADO Feature #456...
-   ⚠️  Detected 3 conflict(s)
-   🔄 Resolving: US-002 marked Closed in ADO (ADO wins)
-   🔄 Resolving: US-005 marked Active in ADO (ADO wins)
-✅ Sync FROM ADO complete!
-   Updated: 3 user stories
-```
-
-## Arguments
-
-- `<spec-id>` - Spec ID (e.g., `spec-001` or just `001`)
-- `--direction <mode>` - Sync direction (default: `to-ado`)
-  - `to-ado` - Push local spec to ADO
-  - `from-ado` - Pull ADO state to spec
-  - `bidirectional` - Sync both ways (conflict resolution)
-
-## Configuration
-
-**Required `.env` variables**:
-
-```bash
-# Azure DevOps Configuration
-ADO_ORGANIZATION=mycompany
-ADO_PROJECT=MyProject
-ADO_PERSONAL_ACCESS_TOKEN=your_pat_token_here
-```
-
-**How to get Personal Access Token (PAT)**:
-1. Go to https://dev.azure.com/{organization}/_usersSettings/tokens
-2. Click "New Token"
-3. Set scopes:
-   - Work Items: Read, Write, & Manage
-   - Project: Read
-4. Copy token to `.env`
-
-## Conflict Resolution
-
-When syncing FROM ADO, conflicts are resolved as follows:
-
-**ADO wins** (default):
-- User story state changes → update spec
-- Acceptance criteria status → update spec
-- Work item closure → mark user story done
-
-**Local wins** (future):
-- Spec changes take precedence
-- Push to ADO
-
-## Requirements
-
-1. **Azure DevOps account** with project access
-2. **Personal Access Token** (with Work Items: Read, Write, & Manage)
-3. **Project permissions** (create features, create user stories)
-4. **Spec file exists** at `.specweave/docs/internal/specs/spec-{id}.md`
-
-## What Gets Synced
-
-### Spec → ADO Feature
-
-- ✅ Title: `[SPEC-001] Feature Area Title`
-- ✅ Description: Overview + progress stats (HTML)
-- ✅ Tags: `spec:spec-001`, `priority:P1`
-- ✅ State: New/Active/Resolved/Closed based on spec
-
-### User Story → ADO User Story
-
-- ✅ Title: `[US-001] As a user, I want...`
-- ✅ Description: User story + acceptance criteria checklist (HTML)
-- ✅ Tags: `user-story`, `spec:spec-001`, `priority:P1`
-- ✅ Parent: Links to feature work item
-- ✅ State: New (todo) / Active (in-progress) / Closed (done)
-
-### Acceptance Criteria → Checklist
-
-```html
-<h2>Acceptance Criteria</h2>
-<ul>
-  <li>☑ User can log in with email/password</li>
-  <li>☐ Invalid credentials show error message</li>
-  <li>☐ Account locks after 5 failed attempts</li>
-</ul>
-```
-
-*Note*: ADO uses HTML in descriptions, with ☑/☐ for checkboxes.
-
-## Architecture
-
-**Why This Architecture?**
-
-✅ **Permanent tracking**: Specs never deleted, ADO links remain valid
-✅ **Feature-level granularity**: One ADO Feature per feature (not per increment)
-✅ **PM-friendly**: Stakeholders see progress in ADO board
-✅ **Brownfield-ready**: Existing ADO features map to specs
-
-**What's WRONG?**
-
-❌ Increment → ADO Work Item (increments are temporary!)
-❌ Tasks → ADO Tasks (too granular, implementation details)
-❌ Multiple features per feature (split across increments)
-
-## Metadata
-
-After sync, spec frontmatter is updated:
-
-```yaml
----
-id: spec-001
-title: Core Framework Architecture
-status: in-progress
-priority: P0
-externalLinks:
-  ado:
-    featureId: 456
-    featureUrl: https://dev.azure.com/org/project/_workitems/edit/456
-    syncedAt: "2025-11-10T12:00:00Z"
-    organization: mycompany
-    project: MyProject
----
-```
-
-## Troubleshooting
-
-**"ADO API authentication failed"**:
-- Check `.env` has correct `ADO_ORGANIZATION`, `ADO_PROJECT`, `ADO_PERSONAL_ACCESS_TOKEN`
-- Verify PAT is valid (not expired)
-- Test authentication: `curl -u :{PAT} https://dev.azure.com/{org}/_apis/projects?api-version=7.0`
-
-**"Spec not found"**:
-- Check spec exists: `ls .specweave/docs/internal/specs/`
-- Use correct ID: `spec-001` or `001`
-
-**"Cannot create feature"**:
-- Ensure you have permissions to create features in the project
-- Check project name is correct in `.env`
-
-**"Parent link failed"**:
-- Ensure feature exists before creating user stories
-- Check feature ID is correct
-
-**"No user stories to sync"**:
-- Add user stories to spec.md:
-  ```markdown
-  **US-001**: As a user, I want...
-  - [ ] **AC-001-01**: Acceptance criteria 1
-  ```
-
-## Related
-
-- `/specweave-github:sync-spec` - Sync to GitHub Project
-- `/specweave-jira:sync-spec` - Sync to Jira Epic
-- `/specweave:sync-docs` - Sync living docs from increments to specs
-
-## Implementation
-
-**File**: `plugins/specweave-ado/lib/ado-spec-sync.ts`
-
-**Core Class**: `AdoSpecSync`
-
-**Methods**:
-- `syncSpecToAdo(specId)` - Push to ADO
-- `syncFromAdo(specId)` - Pull from ADO
-- `detectConflicts(spec, feature)` - Compare states
-- `resolveConflicts(spec, conflicts)` - Apply resolution strategy
-
-## Azure DevOps API Reference
-
-**Endpoints used**:
-- `POST /wit/workitems/$Feature` - Create feature
-- `PATCH /wit/workitems/{id}` - Update work item
-- `GET /wit/workitems/{id}` - Fetch work item
-- `POST /wit/wiql` - Search for work items (WIQL query)
-
-**Authentication**: Basic auth with empty username + Personal Access Token
-
-**API Version**: 7.0
-
-## Work Item States
-
-**Feature States**:
-- New → Spec status: draft
-- Active → Spec status: in-progress
-- Resolved → Spec status: complete
-- Closed → Spec status: archived
-
-**User Story States**:
-- New → User story status: todo
-- Active → User story status: in-progress
-- Closed → User story status: done