specweave 0.6.8 → 0.7.1

package/plugins/specweave/skills/increment-planner/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: increment-planner
-description: Creates comprehensive implementation plans for SpecWeave increments (aka features - both terms are interchangeable). This skill should be used when planning new increments/features, creating specifications, or organizing implementation work. Activates for: increment planning, feature planning, implementation plan, create increment, create feature, plan increment, plan feature, organize work, break down increment, break down feature, new product, build project, MVP, SaaS, app development, product description, tech stack planning, feature list.
+description: Creates comprehensive implementation plans for ANY type of SpecWeave increment (feature, hotfix, bug, change-request, refactor, experiment). Supports all work types from features to bug investigations to POCs. Activates for: increment planning, feature planning, hotfix, bug investigation, root cause analysis, SRE investigation, change request, refactor, POC, prototype, spike work, experiment, implementation plan, create increment, organize work, break down work, new product, build project, MVP, SaaS, app development, tech stack planning, production issue, critical bug, stakeholder request.
 ---
 
 # Increment Planner Skill
@@ -11,10 +11,11 @@ description: Creates comprehensive implementation plans for SpecWeave increments
 - **[Increment Lifecycle Guide](.specweave/docs/internal/delivery/guides/increment-lifecycle.md)**
 
 This guide contains:
-- Complete increment structure (spec.md, plan.md, tasks.md, tests.md)
+- Complete increment structure (spec.md, plan.md, tasks.md with embedded tests)
 - WIP limits and status progression
 - Task vs increment decision tree
 - Context manifest creation for 70%+ token reduction
+- **v0.7.0+**: Test-Aware Planning (tests embedded in tasks.md, no separate tests.md)
 
 **Load this guide using the Read tool BEFORE creating feature plans.**
 
@@ -24,31 +25,62 @@ This skill creates comprehensive, well-structured implementation plans for SpecW
 
 ## Purpose
 
-The increment-planner skill automates the creation of feature implementation plans, ensuring:
-- Auto-numbered feature directories (`0001-9999` 4-digit format)
+The increment-planner skill automates the creation of implementation plans for ANY type of work:
+- Auto-numbered increment directories (`0001-9999` 4-digit format)
 - Duplicate detection (prevents creating 0002 when 0002 already exists)
-- Complete feature artifacts (spec.md, plan.md, tasks.md, tests.md)
+- Complete increment artifacts (spec.md, plan.md, tasks.md with embedded tests)
 - Proper context manifests for selective loading
 - Constitutional compliance
-- Separation of WHAT/WHY (spec) from HOW (plan) from STEPS (tasks)
+- Separation of WHAT/WHY (spec) from HOW (plan) from STEPS (tasks with test plans)
+- **v0.7.0+**: Test-Aware Planning (bidirectional AC↔Task↔Test linking)
+
+## Increment Types (v0.7.0+)
+
+**Increments can be any type of work**, not just features. SpecWeave supports six types:
+
+| Type | Description | Use When | Limit |
+|------|-------------|----------|-------|
+| **feature** | Standard feature development | Adding new functionality | Max 2 active |
+| **hotfix** | Critical production fixes | Production is broken | Unlimited |
+| **bug** | Production bugs with SRE investigation | Bug requires root cause analysis | Unlimited |
+| **change-request** | Stakeholder requests | Business requirements change | Max 2 active |
+| **refactor** | Code improvement | Technical debt, code quality | Max 1 active |
+| **experiment** | POC/spike work | Exploring options, prototypes | Unlimited* |
+
+**Examples**:
+- **Feature**: "Add user authentication", "Implement payment processing"
+- **Hotfix**: "Fix critical security vulnerability CVE-2024-1234"
+- **Bug**: "Investigate memory leak in production API", "Performance degradation in checkout flow"
+- **Change Request**: "Redesign dashboard per stakeholder feedback"
+- **Refactor**: "Extract service layer from monolith", "Migrate to TypeScript"
+- **Experiment**: "Evaluate GraphQL vs REST", "Prototype real-time collaboration"
+
+**Key Insight**: The increment structure (spec.md, plan.md, tasks.md) works for ALL types. Even a bug investigation needs:
+- **spec.md**: What's broken? Expected vs actual behavior? Impact?
+- **plan.md**: Investigation approach, tools, hypothesis
+- **tasks.md**: Investigation steps, fix implementation, verification
 
 ## When to Use This Skill
 
 Use this skill when:
-- Creating a new feature from a description
-- Planning implementation for a user story
-- Organizing work for a complex task
-- Breaking down epics into executable features
-- Structuring brownfield modifications
+- **Features**: Creating new functionality from a description
+- **Hotfixes**: Planning urgent production fixes
+- **Bugs**: Structuring SRE investigations and root cause analysis
+- **Change Requests**: Organizing stakeholder-driven changes
+- **Refactors**: Planning code improvement work
+- **Experiments**: Structuring POCs and technical spikes
+- **Brownfield**: Structuring modifications to existing codebases
 
 ## Activation Triggers
 
 This skill activates automatically when users say:
-- "Plan a feature for..."
-- "Create implementation plan for..."
-- "I want to add [feature description]"
-- "Help me structure [feature]"
-- "Break down this feature: ..."
+- **Features**: "Plan a feature for...", "Create implementation plan for..."
+- **Hotfixes**: "Fix critical bug in production", "Emergency security patch"
+- **Bugs**: "Investigate memory leak", "Debug performance issue", "Root cause analysis for..."
+- **Change Requests**: "Stakeholder requested...", "Business wants to change..."
+- **Refactors**: "Refactor...", "Extract service layer", "Improve code quality"
+- **Experiments**: "Prototype...", "Evaluate...", "POC for...", "Spike work"
+- **General**: "Create increment for...", "Help me structure [work]", "Break down this work: ..."
 
 ---
 
@@ -79,20 +111,39 @@ Task(
 
   Context from existing docs: [summary of strategy docs from Step 1]
 
-  You MUST create BOTH living docs AND increment files:
-
-  1. Living docs (source of truth):
-     - Create .specweave/docs/internal/strategy/{module-name}/
-       * overview.md (product vision, problem, users)
-       * requirements.md (FR-001, NFR-001, technology-agnostic)
-       * user-stories.md (US1, US2, US3...)
-       * success-criteria.md (KPIs, metrics)
-
-  2. Increment file:
+  You MUST create living Spec (living docs - source of truth) AND optionally create increment spec.md:
+
+  1. Spec (living docs - SOURCE OF TRUTH, permanent):
+     - Create .specweave/docs/internal/specs/spec-{number}-{name}/spec.md
+     - This is the COMPLETE, PERMANENT source of truth
+     - Include ALL of:
+       * User stories (US-001, US-002, etc.) with full details
+       * Acceptance criteria (AC-US1-01, etc.)
+       * Functional requirements (FR-001, etc.)
+       * Non-functional requirements (NFR-001, etc.)
+       * Success criteria (metrics, KPIs)
+       * Test strategy
+     - This spec can be linked to Jira/ADO/GitHub Issues
+     - Spec persists even after increment completes
+     - No line limit (be thorough, this is source of truth)
+
+  2. Strategy docs (optional, high-level ONLY):
+     - IF this is a NEW module/product, create:
+       .specweave/docs/internal/strategy/{module-name}/
+       * overview.md (high-level product vision, market opportunity, personas)
+       * business-case.md (optional - ROI, competitive analysis)
+     - IMPORTANT:
+       * ❌ NO detailed user stories (those go in living spec.md)
+       * ❌ NO detailed requirements (those go in living spec.md)
+       * ❌ NO acceptance criteria (those go in living spec.md)
+       * ✅ ONLY strategic, high-level business context
+
+  3. Increment spec.md (optional, can duplicate living spec):
      - Create .specweave/increments/{number}-{name}/spec.md
-     - Keep spec.md < 250 lines (summary only)
-     - MUST reference living docs
-     - Include links to ../../docs/internal/strategy/{module}/
+     - This CAN duplicate content from living spec.md (temporary reference - that's OK!)
+     - OR it can just reference the spec: \"See SPEC-{number}-{name} for complete requirements\"
+     - Increment spec.md may be deleted after increment completes
+     - Living spec.md persists as permanent documentation
 
   Tech stack: [detected tech stack]"
 )
@@ -132,74 +183,163 @@ Task(
 
 Wait for Architect agent to complete!
     ↓
-STEP 4: Validate Living Docs
-├─ Check .specweave/docs/internal/strategy/{module}/ is NOT empty
+STEP 4: Invoke Test-Aware Planner Agent (🚨 MANDATORY - USE TASK TOOL)
+
+YOU MUST USE THE TASK TOOL - DO NOT SKIP:
+
+Task(
+  subagent_type: "test-aware-planner",
+  description: "Generate tasks with embedded tests",
+  prompt: "Create tasks.md with embedded test plans for: [user feature description]
+
+  FIRST, read the increment files:
+  - .specweave/increments/{number}-{name}/spec.md (user stories with AC-IDs)
+  - .specweave/increments/{number}-{name}/plan.md (technical architecture)
+
+  You MUST create tasks.md with embedded test plans:
+
+  Generate .specweave/increments/{number}-{name}/tasks.md:
+  - Parse spec.md for user stories (US1, US2) and AC-IDs (AC-US1-01, etc.)
+  - Parse plan.md for technical architecture and test strategy
+  - Generate tasks with embedded test plans (NO separate tests.md)
+  - Each task includes:
+    * Test Plan (Given/When/Then in BDD format)
+    * Test Cases (unit/integration/E2E with file paths and function names)
+    * Coverage Targets (80-90% overall)
+    * Implementation steps
+    * TDD workflow (if test_mode: TDD)
+  - For non-testable tasks (docs, config): Use Validation section
+  - Ensure all AC-IDs from spec.md are covered
+
+  Follow the workflow in plugins/specweave/agents/test-aware-planner/AGENT.md
+  Use templates from plugins/specweave/agents/test-aware-planner/templates/
+
+  Tech stack: [detected tech stack]"
+)
+
+Wait for test-aware-planner agent to complete!
+    ↓
+STEP 5: Validate Living Docs and Increment Files
+├─ Check .specweave/docs/internal/specs/spec-{number}-{name}/spec.md exists (SOURCE OF TRUTH)
+├─ Check living spec.md contains ALL user stories, requirements, AC-IDs (with AC-IDs)
 ├─ Check .specweave/docs/internal/architecture/adr/ has ≥3 ADRs
-├─ Check increment spec.md REFERENCES (not duplicates) strategy docs
-└─ Check increment plan.md REFERENCES (not duplicates) architecture docs
+├─ Check strategy docs (if created) are high-level only (no detailed user stories)
+├─ Check .specweave/increments/{number}-{name}/spec.md references or duplicates living spec
+├─ Check .specweave/increments/{number}-{name}/plan.md references architecture docs
+├─ Check .specweave/increments/{number}-{name}/tasks.md has embedded test plans
+└─ Check tasks.md covers ALL AC-IDs from living spec.md
     ↓
-✅ SUCCESS: Living docs updated, increment created
+✅ SUCCESS: Living spec created (permanent), increment created (temporary)
 ```
 
 ### What Gets Created
 
-#### Living Docs (Source of Truth) ✅
+#### Living Spec (Living Docs - Source of Truth) ✅
 ```
-.specweave/docs/
-├── internal/
-│   ├── strategy/
-│   │   └── {module}/                    # ← PM Agent creates this
-│   │       ├── overview.md               # Product vision, problem statement
-│   │       ├── requirements.md           # Complete FR/NFR (technology-agnostic)
-│   │       ├── user-stories.md           # All user stories (US1, US2, ...)
-│   │       └── success-criteria.md       # KPIs, business metrics
-│   │
-│   └── architecture/
-│       ├── system-design.md              # ← Architect updates this
-│       ├── adr/                          # ← Architect creates ADRs
-│       │   ├── ####-websocket-vs-polling.md
-│       │   ├── ####-database-choice.md
-│       │   └── ####-deployment-platform.md
-│       ├── diagrams/                     # ← Architect creates diagrams
-│       │   └── {module}/
-│       │       ├── system-context.mmd    # C4 Level 1
-│       │       └── system-container.mmd  # C4 Level 2
-│       └── data-models/
-│           └── {module}-schema.sql
+.specweave/docs/internal/specs/
+└── spec-{number}-{name}/             # ← PM Agent (MANDATORY)
+    └── spec.md                      # COMPLETE user stories, AC, requirements
+                                     # This is the PERMANENT source of truth
+                                     # Can be linked to Jira/ADO/GitHub Issues
+                                     # Persists after increment completes
 ```
 
-#### Increment Files (Summary) ✅
+#### Strategy Docs (Optional, High-Level) ⚠️
+```
+.specweave/docs/internal/strategy/
+└── {module}/                        # ← PM Agent (only if NEW module)
+    ├── overview.md                  # High-level product vision, market opportunity
+    └── business-case.md             # (optional) ROI, competitive analysis
+
+❌ NO requirements.md (goes in living spec.md)
+❌ NO user-stories.md (goes in living spec.md)
+❌ NO success-criteria.md (goes in living spec.md)
+```
+
+#### Architecture Docs (Living Documentation) ✅
+```
+.specweave/docs/internal/architecture/
+├── system-design.md              # ← Architect updates this
+├── adr/                          # ← Architect creates ADRs
+│   ├── ####-websocket-vs-polling.md
+│   ├── ####-database-choice.md
+│   └── ####-deployment-platform.md
+├── diagrams/                     # ← Architect creates diagrams
+│   └── {module}/
+│       ├── system-context.mmd    # C4 Level 1
+│       └── system-container.mmd  # C4 Level 2
+└── data-models/
+    └── {module}-schema.sql
+```
+
+#### Increment Files (Temporary Implementation Tracker) ✅
 ```
 .specweave/increments/0001-feature-name/
-├── spec.md                 # ← PM Agent (< 250 lines, references strategy docs)
-├── plan.md                 # ← Architect Agent (< 500 lines, references architecture docs)
-├── tasks.md                # ← Tech Lead Agent (generated later)
-├── tests.md                # ← QA Agent (generated later)
+├── spec.md                 # ← PM Agent (CAN duplicate living spec.md - temporary reference)
+│                           #    OR just reference: "See SPEC-0001-feature-name"
+│                           #    May be deleted after increment completes
+├── plan.md                 # ← Architect Agent (technical design, references ADRs)
+├── tasks.md                # ← test-aware-planner Agent (tasks with embedded test plans)
+│                           #    v0.7.0+: Tests embedded in each task (BDD format)
+│                           #    Each task includes: Test Plan, Given/When/Then, test files
 └── context-manifest.yaml   # ← increment-planner creates
 ```
 
+**v0.7.0 Architecture Pivot**: tests.md eliminated, tests are now embedded directly in tasks.md
+
+**Key Difference**:
+- **Living spec.md** = Permanent source of truth (persists after increment)
+- **Increment spec.md** = Temporary reference (can be deleted after increment)
+
 ---
 
 ### Validation Rules (MANDATORY)
 
 Before completing feature planning, verify:
 
-**Living Docs Created**:
-- [ ] `.specweave/docs/internal/strategy/{module}/requirements.md` exists
+**Living Spec (Living Docs - Source of Truth, Mandatory)**:
+- [ ] `.specweave/docs/internal/specs/spec-{number}-{name}/spec.md` exists
+- [ ] Living spec.md contains ALL user stories (US-001, US-002, etc.) with full details
+- [ ] Living spec.md contains ALL acceptance criteria (AC-US1-01, etc.)
+- [ ] Living spec.md contains ALL requirements (FR-001, NFR-001, etc.)
+- [ ] Living spec.md contains success criteria (metrics, KPIs)
+- [ ] Living spec.md may reference `../../strategy/{module}/overview.md` for context
+- [ ] No line limit on living spec.md (be thorough - this is permanent!)
+
+**Strategy Docs (Optional)**:
+- [ ] If created, `.specweave/docs/internal/strategy/{module}/overview.md` is high-level only
+- [ ] No detailed user stories in strategy docs (US-001, etc. - those go in Spec)
+- [ ] No detailed requirements in strategy docs (FR-001, NFR-001, etc. - those go in Spec)
+- [ ] Strategy docs provide business context only (market, opportunity, personas)
+
+**Architecture Docs (Mandatory)**:
 - [ ] `.specweave/docs/internal/architecture/adr/` has ≥3 ADRs
-- [ ] `requirements.md` is technology-agnostic (no PostgreSQL, WebSocket, etc.)
 - [ ] ADRs follow template (Context, Decision, Alternatives, Consequences)
+- [ ] Diagrams created for module (system-context, system-container)
+
+**Increment spec.md (Optional - can duplicate living spec)**:
+- [ ] `spec.md` either duplicates living spec.md OR references it ("See SPEC-{number}-{name}")
+- [ ] If duplicated, content matches living spec.md
+
+**Increment plan.md (Mandatory)**:
+- [ ] `plan.md` references architecture docs (`../../docs/internal/architecture/adr/`)
+- [ ] `plan.md` contains technical implementation details
 
-**Increment Files Reference Living Docs**:
-- [ ] `spec.md` has links to `../../docs/internal/strategy/{module}/`
-- [ ] `plan.md` has links to `../../docs/internal/architecture/adr/`
-- [ ] `spec.md` is < 250 lines (summary only)
-- [ ] `plan.md` is < 500 lines (summary only)
+**Increment tasks.md (Mandatory, v0.7.0+)**:
+- [ ] `tasks.md` contains tasks with embedded test plans (NO separate tests.md)
+- [ ] Each testable task has Test Plan (Given/When/Then)
+- [ ] Each testable task has Test Cases (unit/integration/E2E)
+- [ ] Coverage targets specified (80-90% overall)
+- [ ] ALL AC-IDs from Spec spec.md are covered by tasks
+- [ ] Non-testable tasks have Validation section
 
 **Agents Followed Process**:
+- [ ] PM Agent created Spec spec.md as permanent source of truth
 - [ ] PM Agent scanned existing strategy docs before creating new ones
-- [ ] Architect Agent read PM's strategy docs before creating architecture
+- [ ] Architect Agent read Spec spec.md before creating architecture
 - [ ] Architect created ADRs for ALL technical decisions
+- [ ] test-aware-planner Agent read Spec spec.md and plan.md before creating tasks.md
+- [ ] test-aware-planner covered ALL AC-IDs from Spec with tasks
 
 ---
 
@@ -275,11 +415,12 @@ Generate the complete feature directory with all required files:
 .specweave/increments/####-short-name/
 ├── spec.md                 # Feature specification (WHAT and WHY)
 ├── plan.md                 # Implementation plan (HOW)
-├── tasks.md                # Executable tasks (STEPS)
-├── tests.md                # Test strategy and cases
+├── tasks.md                # Executable tasks (STEPS) with embedded test plans (v0.7.0+)
 └── context-manifest.yaml   # Context loading specification
 ```
 
+**v0.7.0 Change**: tests.md eliminated - tests are now embedded in each task in tasks.md
+
 ### Step 5: Generate spec.md
 
 **Purpose**: Define WHAT this feature does and WHY it's needed.
@@ -345,11 +486,13 @@ created: YYYY-MM-DD
 - Measurable acceptance criteria
 - Prioritized user stories (P1/P2/P3)
 
-### Step 6: Detect Required Plugins (INTELLIGENT AUTO-LOADING)
+### Step 6: Detect Required Plugins & Check PM Tool (INTELLIGENT AUTO-LOADING + PM SYNC)
 
-**Purpose**: Analyze spec content to identify required SpecWeave plugins and suggest installation.
+**Purpose**: Analyze spec content to identify required SpecWeave plugins AND check if external PM tool sync is configured.
 
-**Why This Matters**: SpecWeave's plugin system enables context efficiency (70%+ reduction) by loading only relevant capabilities. This step ensures users have the right tools before implementation begins.
+**Why This Matters**:
+1. SpecWeave's plugin system enables context efficiency (70%+ reduction) by loading only relevant capabilities
+2. PM tool integration enables automatic sync of increment progress to external systems (GitHub Issues, Jira, Azure DevOps)
 
 **Detection Algorithm**:
 
@@ -357,6 +500,8 @@ created: YYYY-MM-DD
    ```
    Keywords → Plugin Mapping:
    - "GitHub", "issue", "pull request", "PR" → specweave-github
+   - "Jira", "ticket", "epic" → specweave-jira
+   - "Azure DevOps", "ADO", "work item" → specweave-ado
    - "Kubernetes", "K8s", "Helm", "kubectl" → specweave-kubernetes
    - "Figma", "design system", "design tokens" → specweave-figma
    - "Stripe", "PayPal", "billing", "subscriptions" → specweave-payments
@@ -368,11 +513,19 @@ created: YYYY-MM-DD
    - "Mermaid", "C4", "diagrams", "architecture diagrams" → specweave-diagrams
    ```
 
-2. **Check if plugins are already installed**:
+2. **Check External PM Tool Configuration** (NEW v0.8.0):
+   - Read `.specweave/config.json`
+   - If `externalPM.enabled = true` and `externalPM.tool` is set:
+     - Check if corresponding plugin installed (specweave-github, specweave-jira, or specweave-ado)
+     - Prepare to auto-create external issue/work item after increment creation
+   - If `externalPM.enabled = false` or not configured:
+     - Skip PM tool sync (local-only mode)
+
+3. **Check if plugins are already installed**:
    - For Claude Code: Check if plugin available via `/plugin list --installed`
    - Skip already-installed plugins
 
-3. **Suggest installation** (if plugins detected):
+4. **Suggest installation** (if plugins detected):
    ```
    🔌 This increment requires additional plugins:
 
@@ -391,36 +544,102 @@ created: YYYY-MM-DD
    💡 Plugins will auto-activate during implementation!
    ```
 
-4. **Wait for user to install** (don't block, but remind):
+5. **Auto-Sync to PM Tool** (v0.8.0+):
+
+   **🚨 CRITICAL: SpecWeave Repo Dog-Food Requirement**:
+   - IF repo = "anton-abyzov/specweave"
+     - Read `.specweave/config.json`
+     - Check: `plugins.settings.specweave-github.repo = "anton-abyzov/specweave"`
+     - IF NOT configured → ❌ **HARD ERROR** (block increment creation):
+       ```
+       ❌ SpecWeave repo MUST use GitHub sync!
+
+       This is a "dog food" requirement (ADR-0007):
+       - SpecWeave demonstrates its own features
+       - GitHub Issues show public progress
+       - Community can track development
+
+       Fix: Create .specweave/config.json with GitHub settings
+       See: CLAUDE.md for config structure
+       ```
+     - IF configured → Continue to auto-sync (required)
+
+   **For All Other Repos** (normal behavior):
+   - **If PM tool configured and plugin installed**:
+     ```
+     🔗 External PM Tool Sync:
+        Tool: GitHub Issues
+        Auto-sync: Enabled
+
+     Creating GitHub issue for increment 0007-user-authentication...
+     ✅ GitHub Issue #42 created
+        URL: https://github.com/myorg/myapp/issues/42
+        Linked to: .specweave/increments/0007-user-authentication/metadata.json
+
+     Progress will sync automatically after each task completion!
+     ```
+   - **If PM tool configured but plugin NOT installed**:
+     ```
+     ⚠️  External PM Tool Configured: GitHub Issues
+        Plugin missing: specweave-github
+
+     To enable auto-sync: /plugin install specweave-github@specweave
+     Or continue without PM sync (local-only mode)
+     ```
+   - **If PM tool not configured**:
+     ```
+     ℹ️  No external PM tool configured (local-only mode)
+        To enable GitHub/Jira/ADO sync: Run project initialization or update config
+     ```
+
+6. **Wait for user to install** (don't block, but remind):
    - If user proceeds without installing, remind them before task execution
    - Skills from uninstalled plugins won't be available
    - User can install later: plugins activate on next Claude Code session
 
-**When to Suggest**:
+**When to Execute**:
 - ✅ After spec.md generation (Step 5 complete)
 - ✅ Before plan.md generation (gives context for planning)
+- ✅ After ALL increment files created (spec.md, plan.md, tasks.md)
 - ❌ Don't block increment creation (plugins optional, not required)
 
-**Example Output**:
+**Example Output (Full Flow)**:
 
 ```
-📝 Spec created: .specweave/increments/0007-github-sync/spec.md
+📝 Increment created: 0007-user-authentication
+
+Files:
+• spec.md (user stories, acceptance criteria)
+• plan.md (technical architecture)
+• tasks.md (implementation steps with embedded tests)
 
 🔌 Plugin Detection:
-   Detected: "GitHub Issues", "bidirectional sync"
-   → Suggested: specweave-github
+   Detected: "user authentication", "JWT tokens", "session management"
+   → No additional plugins required
+
+🔗 External PM Tool Sync:
+   Tool: GitHub Issues
+   Plugin: specweave-github ✅ Installed
 
-   To install: /plugin install specweave-github@specweave
-   Or continue without it (can install later)
+   Creating GitHub issue...
+   ✅ Issue #42 created: "Increment 0007: User Authentication"
+      URL: https://github.com/myorg/myapp/issues/42
 
-Continue with plan.md generation? [Y/n]
+   Auto-sync enabled:
+   • Progress updates posted after each task completion
+   • Issue closed automatically when increment done
+
+Next steps:
+1. Review spec.md - verify user stories
+2. Approve plan.md - validate architecture
+3. Start work: /specweave:do
 ```
 
 **Integration with Existing Workflow**:
-- This is a **suggestion step**, not a blocking requirement
-- Increment creation continues regardless of plugin installation
-- Plugins can be installed any time (they auto-activate when needed)
-- This implements the "load on demand" philosophy
+- Plugin detection is a **suggestion step** (not blocking)
+- PM tool sync is **automatic** if configured (zero manual intervention)
+- Increment creation continues regardless of PM tool status
+- This implements the "seamless integration" philosophy
 
 ### Step 7: Generate plan.md
 
@@ -483,7 +702,7 @@ Continue with plan.md generation? [Y/n]
 ```
 
 ## Testing Strategy
-[High-level testing approach, see tests.md for details]
+[High-level testing approach - tests embedded in tasks.md (v0.7.0+)]
 
 ## Deployment Considerations
 [Infrastructure, environment, rollout]
@@ -596,97 +815,67 @@ T051 depends on T050 (integration must pass first)
    - Performance-critical algorithms
    - Novel problem-solving required
 
-### Step 9: Generate tests.md
-
-**Purpose**: Define comprehensive testing strategy and test cases.
-
-**Structure**:
-```markdown
-# Test Strategy: [Feature Title]
-
-## Test Philosophy
-
-Follow SpecWeave Constitution Article III: Test-First Development
-- Tests written before implementation
-- Tests must fail initially (red-green-refactor)
-- Integration tests with real environments
-
-## Test Categories
-
-### Unit Tests
-[Component-level tests]
-
-### Integration Tests
-[Module integration tests]
-
-### E2E Tests
-[End-to-end user flows]
-
-### Performance Tests
-[Load, stress, scalability tests]
-
-## Test Cases
-
-### TC-001: [Test Name]
-**Type**: Unit | Integration | E2E
-**Priority**: P1 | P2 | P3
-**User Story**: US1
-
-**Scenario**:
-- Given [precondition]
-- When [action]
-- Then [expected outcome]
-
-**Test Data**:
-[Sample inputs]
-
-**Expected Results**:
-[Specific, measurable outcomes]
-
-### TC-002: [Test Name]
-...
-
-## Test Coverage Targets
+### Step 9: Embed Tests in tasks.md (v0.7.0+ Architecture)
 
-- Unit test coverage: >80%
-- Integration test coverage: Critical paths
-- E2E coverage: All P1 user stories
+**Purpose**: Ensure every task includes comprehensive test plans directly in tasks.md.
 
-## Testing Tools
+**v0.7.0 Architecture Pivot**: tests.md eliminated. Tests are now embedded in each task for:
+- ✅ Closer proximity to implementation (no sync issues)
+- ✅ Bidirectional AC↔Task↔Test linking
+- ✅ Test-first development (tests defined before implementation)
+- ✅ Clear traceability (each task knows its tests)
 
-- Unit: [Framework]
-- Integration: [Framework]
-- E2E: [Framework]
-
-## Test Environments
-
-- Local: [Setup]
-- CI/CD: [Pipeline]
-- Staging: [Environment]
-
-## Regression Testing
-
-For brownfield modifications:
-1. Document existing behavior
-2. Create tests for current functionality
-3. User validation of tests
-4. Implement changes
-5. Verify regression tests still pass
+**Task Structure with Embedded Tests**:
+```markdown
+### T-001: Implement login API endpoint
+
+**Description**: Create REST API endpoint for user authentication
+
+**References**: AC-US1-01, AC-US1-02
+
+**Implementation Details**:
+- Validate email format
+- Check password against bcrypt hash
+- Generate JWT token
+- Return 401 for invalid credentials
+
+**Test Plan**:
+- **File**: `tests/unit/auth-service.test.ts`
+- **Tests**:
+  - **TC-001**: Valid credentials
+    - Given valid email and password
+    - When POST /api/auth/login
+    - Then return 200 with JWT token
+  - **TC-002**: Invalid email
+    - Given malformed email
+    - When POST /api/auth/login
+    - Then return 401 with error message
+  - **TC-003**: Wrong password
+    - Given correct email, wrong password
+    - When POST /api/auth/login
+    - Then return 401, no details leaked
+
+**Dependencies**: None
+**Estimated Effort**: 4 hours
+**Status**: [ ] Not Started
+```
 
-## Success Criteria
+**Key Features**:
+- **References**: Links to acceptance criteria (bidirectional traceability)
+- **Test Plan**: Specific test file and test functions
+- **BDD Format**: Given/When/Then for clarity
+- **Coverage**: Each testable task MUST have test plan
 
-- [ ] All P1 tests passing
-- [ ] Coverage targets met
-- [ ] Performance tests pass
-- [ ] No regressions detected
-```
+**test-aware-planner Agent**:
+- Generates tasks.md with embedded tests
+- Ensures 80%+ coverage of testable tasks
+- Marks non-testable tasks (documentation, config)
+- Uses BDD format throughout
 
-**Key Principles**:
-- Test-first philosophy
-- Comprehensive coverage (unit, integration, E2E)
-- Clear test cases with Given-When-Then
-- Regression prevention for brownfield
-- Measurable success criteria
+**Validation**:
+- Use `/validate-coverage` to check AC and task coverage
+- Target: 80-90% coverage (not 100% - diminishing returns)
+- Integration with `/done` command (runs validation before completion)
 
 ### Step 10: Generate context-manifest.yaml
 
@@ -746,13 +935,13 @@ Before completing:
 1. **Constitutional Compliance**:
    - Article V: Modular Scalability (proper structure)
    - Article VI: Separation of Concerns (spec vs plan vs tasks)
-   - Article IX: Testing Mandate (tests.md comprehensive)
+   - Article IX: Testing Mandate (tasks.md with embedded tests comprehensive)
 
 2. **Quality Checks**:
    - spec.md is technology-agnostic
-   - plan.md has sufficient technical detail
-   - tasks.md has exact file paths
-   - tests.md covers all P1 user stories
+   - plan.md has sufficient technical detail + test strategy
+   - tasks.md has exact file paths + embedded test plans (BDD format)
+   - tasks.md covers all P1 AC-IDs with test cases
    - context-manifest.yaml is precise
 
 3. **Update Features Index**:
@@ -838,14 +1027,13 @@ Before completing:
 - Next: 0003
 - Path: `.specweave/increments/0003-stripe-payment-integration/`
 
-**Step 4**: Create structure
+**Step 4**: Create structure (v0.7.0+)
 ```
 .specweave/increments/0003-stripe-payment-integration/
-├── spec.md
-├── plan.md
-├── tasks.md
-├── tests.md
-└── context-manifest.yaml
+├── spec.md                  # WHAT & WHY
+├── plan.md                  # HOW + test strategy
+├── tasks.md                 # Implementation + embedded tests (BDD)
+└── context-manifest.yaml    # Context loading config
 ```
 
 **Step 5**: Generate spec.md
@@ -907,23 +1095,24 @@ Acceptance Criteria:
 ...
 ```
 
-**Step 8**: Generate tests.md
-```markdown
-# Test Strategy: Stripe Payment Integration
-
-## Test Cases
-
-### TC-001: Successful Subscription Creation
-Type: Integration
-Priority: P1
-User Story: US1
-
-Scenario:
-- Given a valid customer and plan ID
-- When createSubscription() is called
-- Then subscription is created in Stripe
-- And webhook confirms activation
-...
+**Step 8**: Invoke test-aware-planner Agent (v0.7.0+)
+```typescript
+// Use Task tool to invoke test-aware-planner agent
+Task({
+  subagent_type: "test-aware-planner",
+  description: "Generate tasks with embedded tests",
+  prompt: `Create tasks.md with embedded test plans for Stripe payment integration.
+
+  Read increment files:
+  - .specweave/increments/0003-stripe-payment-integration/spec.md
+  - .specweave/increments/0003-stripe-payment-integration/plan.md
+
+  Generate tasks.md with:
+  - BDD test plans (Given/When/Then) per task
+  - Test cases (unit/integration/E2E with file paths)
+  - Coverage targets (80-90% overall)
+  - AC-ID traceability from spec.md`
+});
 ```
 
 **Step 9**: Generate context-manifest.yaml
@@ -940,10 +1129,10 @@ priority: high
 ```
 
 **Step 10**: Validate
-- ✅ spec.md is technology-agnostic
-- ✅ plan.md documents Stripe SDK choice
-- ✅ tasks.md follows test-first
-- ✅ tests.md covers all P1 stories
+- ✅ spec.md is technology-agnostic with AC-IDs
+- ✅ plan.md documents Stripe SDK choice + test strategy
+- ✅ tasks.md has embedded test plans (BDD format)
+- ✅ tasks.md covers all P1 AC-IDs with tests
 - ✅ Constitutional compliance verified
 
 **Output**:
@@ -952,10 +1141,9 @@ priority: high
 
 Location: .specweave/increments/0003-stripe-payment-integration/
 Files created:
-- spec.md
-- plan.md
-- tasks.md
-- tests.md
+- spec.md (12 user stories, 34 AC-IDs)
+- plan.md (5 phases, architecture diagrams, test strategy)
+- tasks.md (23 tasks with embedded tests, 85% coverage target)
 - context-manifest.yaml
 
 Next steps:
@@ -1013,7 +1201,7 @@ This skill enforces:
 
 - **Article V**: Modular Scalability - Auto-numbered features prevent conflicts
 - **Article VI**: Separation of Concerns - spec vs plan vs tasks are distinct
-- **Article IX**: Skill Testing Mandate - tests.md ensures comprehensive testing
+- **Article IX**: Testing Mandate - tasks.md with embedded tests ensures comprehensive testing (v0.7.0+)
 
 ## Integration with Other Skills