specweave 1.0.363 → 1.0.367

package/plugins/SKILLS-VS-AGENTS.md

@@ -1,176 +1,269 @@
-# Skills vs Agents: SpecWeave's Approach
+# Skills and Subagents: SpecWeave's Architecture
 
 > Based on official Claude Code documentation: https://code.claude.com/docs/en/skills and https://code.claude.com/docs/en/sub-agents
 
+## Claude Code Extensibility Overview
+
+Before diving into SpecWeave-specific architecture, here's the full landscape of Claude Code's extension mechanisms — AI and non-AI alike.
+
+### All Extension Points
+
+| Mechanism | What It Is | AI-Powered? | Docs |
+|-----------|-----------|-------------|------|
+| **Skills** | Markdown instructions Claude follows (reference, tasks, `/commands`) | Yes (LLM reads them) | [skills](https://code.claude.com/docs/en/skills) |
+| **Custom Subagents** | Isolated AI workers with own context, memory, model | Yes (separate LLM context) | [sub-agents](https://code.claude.com/docs/en/sub-agents) |
+| **Agent Teams** | Multiple agents working in parallel, communicating via messages | Yes (multiple LLM sessions) | [agent-teams](https://code.claude.com/docs/en/agent-teams) |
+| **Hooks** | Shell scripts triggered by tool events (PreToolUse, PostToolUse, etc.) | No (pure shell) | [hooks](https://code.claude.com/docs/en/hooks) |
+| **MCP Servers** | External tool servers (databases, APIs, Slack, Figma, etc.) | No (tool providers) | [mcp](https://code.claude.com/docs/en/mcp) |
+| **Plugins** | Packages that bundle skills + agents + hooks + commands | Mixed | [plugins](https://code.claude.com/docs/en/plugins) |
+| **CLAUDE.md** | Persistent project/user instructions loaded every session | No (static text) | [memory](https://code.claude.com/docs/en/memory) |
+| **Permissions** | Allow/deny rules for tools, skills, agents | No (configuration) | [permissions](https://code.claude.com/docs/en/permissions) |
+| **Settings** | JSON config for models, tools, environment | No (configuration) | [settings](https://code.claude.com/docs/en/settings) |
+
+### How They Compose
+
+```
+User Request
+    ↓
+Claude Code (main conversation)
+    ├── Reads: CLAUDE.md, settings, permissions
+    ├── Has: Skills (loaded by keyword or /command)
+    ├── Uses: MCP Servers (external tools)
+    ├── Spawns: Custom Subagents (isolated workers)
+    │   └── Subagent preloads: Skills (injected at startup)
+    │   └── Subagent uses: MCP Servers, Hooks
+    ├── Spawns: Built-in Subagents (Explore, Plan, general-purpose)
+    ├── Orchestrates: Agent Teams (parallel multi-agent work)
+    └── Triggers: Hooks (shell scripts on tool events)
+```
+
+### Non-AI Tools in SpecWeave
+
+SpecWeave uses several non-AI extension points:
+
+| Tool | Type | Purpose |
+|------|------|---------|
+| **Guard hooks** (skill-chain, interview, spec-template) | Hooks (shell) | Enforce delegation rules — block writes unless correct agent registered |
+| **`specweave` CLI** | External tool (Node.js) | Create increments, validate specs, manage lifecycle |
+| **`!`command`` injection** | Shell preprocessing | Inject dynamic context (config, project info) into skills before Claude sees them |
+| **State files** (`.specweave/state/`) | File system | Coordination between agents via marker files |
+| **MCP servers** (Figma, Gmail, etc.) | MCP | External integrations Claude can use during any phase |
+
+---
+
 ## TL;DR
 
-**SpecWeave uses Skills exclusively. No custom agents needed.**
+**SpecWeave uses both Skills AND Custom Subagents — each for what it's best at.**
+
+- **Skills** = reusable instructions (reference knowledge, standalone tasks, user-invocable `/commands`)
+- **Custom Subagents** = persistent, isolated workers that preload skills (memory, resumability, background execution)
+- **The pattern**: Subagents preload skills via the `skills:` field — subagent owns isolation + memory, skill owns domain logic
+
+## When to Use What
 
-Skills with `context: fork` provide 100% of the functionality we need:
-- **Auto-activation** by keywords (Claude detects "React dashboard" → loads frontend skill)
-- **Isolated execution** via `context: fork` (like subagents)
-- **User-invocable** via `/skill-name`
-- **Domain expertise** loaded on-demand
+| Use Case | Mechanism | Why |
+|----------|-----------|-----|
+| **Orchestrated agent** (PM, Architect, Planner) | Custom subagent + preloaded skill | Memory, resumability, auto-compaction, guaranteed skill injection |
+| **Standalone heavy task** (grill, brainstorm) | Skill with `context: fork` | Self-contained, user-invocable, no memory needed |
+| **Reference knowledge** (api-conventions, style guide) | Skill, NO `context: fork` | Must run inline to enrich main conversation |
+| **Quick research** | Built-in subagent (Explore, Plan, general-purpose) | Read-only, disposable, no custom setup |
 
-For explicit research/exploration tasks, use **built-in subagents** (Explore, Plan, general-purpose).
+### Decision Flowchart
 
-## Why Skills Over Custom Agents?
+```
+Does the agent need persistent memory or resumability?
+  YES → Custom subagent (with skills: preloading)
+  NO  →
+    Is it a standalone task producing output?
+      YES → Skill with context: fork
+      NO  →
+        Is it reference/knowledge for the main conversation?
+          YES → Skill, NO context: fork (runs inline)
+          NO  → Built-in subagent (Explore/Plan/general-purpose)
+```
+
+## The Core Pattern: Subagents Preloading Skills
 
-| Feature | Skills (`context: fork`) | Custom Agents |
-|---------|-------------------------|---------------|
-| **Auto-activation** | ✅ By keywords | ❌ Must be explicitly spawned |
-| **Isolated context** | ✅ With `context: fork` | ✅ Always isolated |
-| **User-invocable** | ✅ `/skill-name` | ❌ Only via Task tool |
-| **Discovery** | ✅ Works with subfolder structure | ❌ Requires flat files |
-| **Token efficient** | ✅ Loads on-demand | ❌ Same |
-| **Maintenance** | ✅ Simple SKILL.md format | ❌ Stricter requirements |
+This is the recommended architecture for SpecWeave's orchestrated agents:
 
-**Bottom line**: Skills do everything custom agents do, plus auto-activation and simpler maintenance.
+```
+plugins/specweave/
+├── agents/
+│   ├── sw-pm.md            # Subagent definition (model, memory, skills)
+│   ├── sw-architect.md     # Each preloads its corresponding skill
+│   └── sw-planner.md
+├── skills/
+│   ├── pm/
+│   │   ├── SKILL.md        # Domain logic, phases, templates
+│   │   ├── phases/         # Supporting files loaded on demand
+│   │   └── templates/
+│   ├── architect/
+│   │   └── SKILL.md
+│   └── test-aware-planner/
+│       └── SKILL.md
+```
 
-## The Pattern: Skills with `context: fork`
+### How It Works
 
+**Subagent file** (`agents/sw-pm.md`):
 ```yaml
 ---
-name: frontend-architect
-description: Frontend architecture expert. Activates for React, Vue, Next.js, dashboard, component...
-context: fork          # <-- Runs in isolated subagent context
+name: sw-pm
+description: Product Manager for writing spec.md...
 model: opus
-allowed-tools: Read, Write, Edit, Bash, Glob, Grep
+memory: project
+skills:
+  - sw:pm              # Preloads the PM skill content at startup
 ---
 
-# Frontend Architect Skill
-
-You are an expert frontend architect...
+You are a Product Manager specializing in spec-driven development.
 ```
 
-**This gives you:**
-- Auto-activation on keywords ("Build React dashboard" → skill activates)
-- Isolated context (doesn't pollute main conversation)
-- Full tool access within the isolated context
-- Results summarized back to main conversation
+**Skill file** (`skills/pm/SKILL.md`):
+```yaml
+---
+description: Product Manager for spec-driven development...
+context: fork
+model: opus
+---
+
+# Product Manager Skill
+...full domain logic, phases, templates...
+```
 
-## Built-in Subagents for Research
+> **Note**: Skills have `context: fork` and `model` for standalone invocation (e.g., `/sw:pm`). When preloaded by a subagent, the subagent's isolation takes precedence — `context: fork` doesn't cause "double-forking".
 
-For explicit research/exploration tasks, use Claude Code's **built-in subagents** via the Task tool:
+**Why this works**:
+- The **subagent** owns: isolation, memory, model, resumability, background execution
+- The **skill** owns: domain logic, supporting files (phases, templates), user-invocable `/sw:pm`
+- The `skills:` field **guarantees** skill content is injected at startup (no discovery step needed)
+- Users can still run `/sw:pm` directly for ad-hoc spec work outside increment flow
 
-| Subagent | Use Case | Example |
-|----------|----------|---------|
-| **Explore** | Codebase exploration, finding files | "Find all API endpoints" |
-| **Plan** | Architecture planning, design | "Design auth system" |
-| **general-purpose** | Open-ended research | "Research Stripe vs PayPal for Israel" |
+### Invocation from the Increment Orchestrator
 
-**Example usage:**
 ```typescript
-Task({
-  subagent_type: "Explore",
-  prompt: "Find all payment-related files and how they're organized",
-  description: "Explore payments codebase"
-})
-
-Task({
-  subagent_type: "general-purpose",
-  prompt: "Research best payment providers for businesses in Israel",
-  description: "Payment provider research"
-})
+// The increment skill spawns subagents (NOT skills):
+Agent({ subagent_type: "sw:sw-pm", prompt: "Write spec for increment XXXX-name: ..." })
+Agent({ subagent_type: "sw:sw-architect", prompt: "Design architecture for increment XXXX-name..." })
+Agent({ subagent_type: "sw:sw-planner", prompt: "Generate tasks for increment XXXX-name..." })
 ```
 
-**Key insight**: Built-in subagents handle explicit research needs. Skills handle domain expertise. No custom agents needed!
+## Feature Comparison
 
-## SpecWeave Skill Catalog
+| Feature | Skill (`context: fork`) | Custom Subagent |
+|---------|------------------------|-----------------|
+| **Isolated context** | Yes | Yes |
+| **Auto-activation by keywords** | Yes | No (must be explicitly spawned) |
+| **User-invocable** (`/name`) | Yes | No (only via Agent tool) |
+| **Persistent memory** | No | Yes (`memory: project/user/local`) |
+| **Resumable** (by agent ID) | No | Yes |
+| **Background execution** | No (blocks caller) | Yes (`run_in_background: true` or Ctrl+B) |
+| **Auto-compaction** | No | Yes (at ~95% capacity) |
+| **Permission mode override** | No | Yes (`permissionMode:`) |
+| **Skills preloading** | No | Yes (`skills:` field) |
+| **Hooks** | Yes | Yes |
+| **Custom model** | Yes (`model:`) | Yes (`model:`) |
+| **Distributed via plugins** | `plugins/X/skills/` | `plugins/X/agents/` |
+| **Supporting files** | Yes (phases/, templates/) | No (but preloaded skills can have them) |
 
-All domain experts are now skills with `context: fork`:
+## When NOT to Use `context: fork`
 
-| Domain | Skill | Triggers (Auto-activate) |
-|--------|-------|--------------------------|
-| **Frontend** | `frontend:architect` | React, Vue, Next.js, dashboard, component, UI |
-| **Backend** | `backend:database-optimizer` | API, database, SQL, PostgreSQL, optimization |
-| **Payments** | `payments:payment-integration` | Stripe, PayPal, checkout, billing, subscriptions |
-| **Testing** | `testing:qa` | E2E, Playwright, Vitest, Jest, TDD, QA |
-| **Kubernetes** | `k8s:kubernetes-architect` | K8s, pods, deployments, Helm, GitOps |
-| **Infrastructure** | `infra:devops` | Terraform, Docker, CI/CD, AWS, Azure |
-| **Mobile** | `mobile:react-native-expert` | React Native, iOS, Android, Expo |
-| **ML/AI** | `ml:ml-engineer` | ML, model, training, TensorFlow, PyTorch |
-| **Diagrams** | `sw-diagrams:diagrams` | Mermaid, C4, architecture diagram, flowchart |
-| **Release** | `sw-release:release-expert` | release, version, changelog, npm publish |
+A skill should **not** have `context: fork` when:
 
-All run in isolated context without polluting the main conversation.
+1. **A subagent preloads it** — the subagent already provides isolation. Adding `context: fork` would double-fork (skill forks inside already-forked subagent = wasted tokens)
+2. **It provides reference knowledge** — conventions, patterns, style guides that Claude needs in the main conversation context
+3. **It needs conversation history** — `context: fork` creates a fresh context; the skill won't see prior messages
 
-## How It Works in Practice
+**DO use `context: fork`** when:
+- The skill is a **standalone task** producing output (grill, brainstorm, code-simplifier)
+- No custom subagent wraps it
+- You want isolation without creating a full subagent definition
 
-**User says:** "Build a React dashboard with Stripe checkout"
+**SpecWeave validator note**: The SpecWeave skill validator does NOT recognize `context`, `model`, `agent`, or `allowed-tools` in frontmatter — these are Claude Code attributes. SpecWeave only supports: `argument-hint`, `compatibility`, `description`, `disable-model-invocation`, `license`, `metadata`, `name`, `user-invokable`. For skills preloaded by subagents, put `model` and `context` on the **subagent**, not the skill.
+
+## Built-in Subagents for Research
 
-**What happens:**
-1. Claude detects keywords: "React", "dashboard", "Stripe", "checkout"
-2. Skills auto-activate (primary mechanism):
-   - `frontend:architect` (React, dashboard)
-   - `payments:payment-integration` (Stripe, checkout)
-3. Each skill runs in isolated context (`context: fork`)
-4. Results return to main conversation
+For explicit research/exploration, use Claude Code's built-in subagents:
 
-**Two invocation methods** (per [official docs](https://code.claude.com/docs/en/skills)):
-1. **Auto-activation** (primary): Keywords in skill description trigger automatic loading
-2. **Explicit invocation** (fallback): Use Skill tool or `/skill-name` when auto-activation doesn't trigger
+| Subagent | Model | Tools | Use Case |
+|----------|-------|-------|----------|
+| **Explore** | Haiku | Read-only | Fast codebase search, file discovery |
+| **Plan** | Inherited | Read-only | Architecture planning, design research |
+| **general-purpose** | Inherited | All | Complex multi-step research + modification |
 
 ```typescript
-// If auto-activation didn't work, explicitly invoke:
-Skill({ skill: "frontend:architect", args: "dashboard" })
+Agent({ subagent_type: "Explore", prompt: "Find all API endpoints", description: "API exploration" })
+Agent({ subagent_type: "general-purpose", prompt: "Research Stripe integration patterns", description: "Stripe research" })
 ```
 
-## Migration Complete
+## SpecWeave Agent Catalog
 
-All 35 SpecWeave agents have been converted to skills:
+### Core Orchestration Agents (Subagent + Skill)
 
-**Before (Didn't Work):**
-```
-plugins/specweave-frontend/
-└── agents/
-    └── frontend-architect/
-        └── AGENT.md         # NOT discovered by Claude Code!
-```
+| Agent | Subagent | Preloads Skill | Writes | Model |
+|-------|----------|---------------|--------|-------|
+| **PM** | `sw-pm` | `sw:pm` | spec.md | Opus |
+| **Architect** | `sw-architect` | `sw:architect` | plan.md | Opus |
+| **Planner** | `sw-planner` | `sw:test-aware-planner` | tasks.md | Sonnet |
 
-**After (Works):**
-```
-plugins/specweave-frontend/
-└── skills/
-    └── frontend-architect/
-        └── SKILL.md         # Auto-activates on keywords
-```
+### Standalone Skills (context: fork)
+
+| Skill | Purpose | Why not a subagent? |
+|-------|---------|-------------------|
+| `sw:grill` | Code review before ship | No memory needed, one-shot |
+| `sw:brainstorm` | Multi-perspective ideation | Spawns parallel lenses, disposable |
+| `sw:judge-llm` | Deep validation | One-shot evaluation |
 
-**Conversion changes:**
-- `tools:` → `allowed-tools:`
-- Added `context: fork`
-- Removed agent-specific fields (`model_preference`, `cost_profile`, `visibility`)
-- Removed "How to Invoke" sections
+### Reference Skills (inline, no fork)
+
+| Skill | Purpose |
+|-------|---------|
+| `api-conventions` | API design patterns |
+| `error-handling-patterns` | Error handling standards |
 
 ## FAQ
 
-### Q: Do we ever need custom agents?
-**A: No.** Skills with `context: fork` cover 100% of our use cases. Built-in subagents (Explore, Plan, general-purpose) handle explicit research tasks.
+### Q: When should I create a custom subagent vs a skill with `context: fork`?
+**A:** If the agent needs **persistent memory**, **resumability**, or **background execution** — make it a custom subagent. If it's a **one-shot task** or **user-invocable command** — make it a skill with `context: fork`. If it's **reference knowledge** — skill without fork.
 
-### Q: Why did custom agents fail?
-**A:** Claude Code expects flat files (`agents/<name>.md`), but SpecWeave had subfolder structure (`agents/<name>/AGENT.md`). Skills don't have this limitation.
+### Q: Can a skill work both standalone AND preloaded by a subagent?
+**A:** Yes. Remove `context: fork` from the skill. Users invoke it directly via `/sw:pm` (runs inline). The subagent preloads it via `skills: [sw:pm]` (runs in subagent's isolated context). Same logic, two execution modes.
 
-### Q: How do I invoke a skill explicitly?
-**A:** Two ways:
-1. **User**: Type `/frontend:architect` in chat
-2. **Claude**: Use `Skill({ skill: "frontend:architect" })` when auto-activation didn't trigger
+### Q: What happens if the skills: preloading fails?
+**A:** The subagent still runs — it just won't have the skill content injected. The subagent's own markdown body (system prompt) is always available. To guard against this, keep critical instructions in the subagent body and use skills for detailed/phase logic.
 
-Usually just describe what you need - skills auto-activate on keywords. Use explicit invocation as fallback.
+### Q: Can subagents spawn other subagents?
+**A:** No. Subagents cannot nest. If you need chained delegation, the **main conversation** (or orchestrator skill) spawns each subagent sequentially.
 
-### Q: What about parallel execution?
-**A:** Built-in subagents can run in parallel via multiple Task tool calls. Skills with `context: fork` also run in isolated contexts, so multiple can activate without conflict.
+### Q: Why did custom agents fail before?
+**A:** SpecWeave originally used subfolder structure (`agents/<name>/AGENT.md`). Claude Code expected flat files (`agents/<name>.md`). This was fixed — flat `.md` files in `agents/` now work correctly.
 
 ## Official Documentation
 
+### AI Extension Points
 - **Skills**: https://code.claude.com/docs/en/skills
 - **Subagents**: https://code.claude.com/docs/en/sub-agents
-- **Features Overview**: https://code.claude.com/docs/en/features-overview
-- **Best Practices**: https://code.claude.com/docs/en/best-practices
+- **Agent Teams**: https://code.claude.com/docs/en/agent-teams
+
+### Non-AI Extension Points
+- **Hooks**: https://code.claude.com/docs/en/hooks
+- **MCP Servers**: https://code.claude.com/docs/en/mcp
+- **Permissions**: https://code.claude.com/docs/en/permissions
+- **Settings**: https://code.claude.com/docs/en/settings
+- **Memory (CLAUDE.md)**: https://code.claude.com/docs/en/memory
+
+### Distribution
+- **Plugins**: https://code.claude.com/docs/en/plugins
+- **Plugin Components Reference**: https://code.claude.com/docs/en/plugins-reference
+
+### Full Index
+- **All docs**: https://code.claude.com/docs/llms.txt
 
 ## Summary
 
-1. **Skills are the only choice** for SpecWeave - no custom agents needed
-2. **`context: fork`** gives isolated execution (subagent behavior)
-3. **Auto-activation by keywords** is the primary mechanism
-4. **Built-in subagents** (Explore, Plan, general-purpose) handle explicit research
-5. **All 35 agents converted** to skills across all plugins
+1. **Subagents + Skills together** — subagent owns isolation/memory, skill owns domain logic
+2. **`context: fork`** for standalone tasks only (grill, brainstorm, judge)
+3. **No `context: fork`** on skills preloaded by subagents (avoids double-fork)
+4. **No `context: fork`** on reference/knowledge skills (need inline context)
+5. **Built-in subagents** (Explore, Plan, general-purpose) for ad-hoc research
+6. **Agent()** to invoke custom subagents, **Skill()** for standalone skills

package/plugins/specweave/agents/sw-architect.md

@@ -3,79 +3,20 @@ name: sw-architect
 description: System Architect for writing plan.md with architecture decisions and component design. Use for increment technical planning during /sw:increment orchestration.
 model: opus
 memory: project
+skills:
+  - sw:architect
 ---
 
-# Architect Agent
-
-## Project Overrides
-
-!`s="architect"; for d in .specweave/skill-memories .claude/skill-memories "$HOME/.claude/skill-memories"; do p="$d/$s.md"; [ -f "$p" ] && awk '/^## Learnings$/{ok=1;next}/^## /{ok=0}ok' "$p" && break; done 2>/dev/null; true`
-
-## Identity
+# Architect Subagent
 
 You are a System Architect specializing in scalable technical designs. You create plan.md with architecture decisions, component boundaries, and implementation strategies.
 
 Your prompt will contain: increment ID, increment path, and spec.md location. Always read spec.md first.
 
-## Design Approach
-
-Design system architecture with focus on:
-
-1. **ADRs** — Check existing decisions at `.specweave/docs/internal/architecture/adr/` before designing
-2. **Component design** — Define boundaries, APIs, data flow
-3. **Trade-off analysis** — Evaluate options with clear pros/cons
-4. **Technology selection** — Choose stack based on project constraints
-
-## Key Architectural Patterns
-
-### Code Mode for API-Heavy Services (ADR-0140)
-
-When a service exposes 50+ API endpoints to AI agents, avoid exposing each as a separate MCP tool. Instead, use the **Code Mode pattern**: expose a typed schema (OpenAPI/JSON Schema) and let the agent write code to discover and call endpoints.
-
-**Apply when**: designing agent-facing APIs, MCP servers, or any system where AI agents consume a large surface area.
-
-## Markdown Preview Guidelines
-
-When presenting **2+ architectural approaches** for the user to choose between, use `AskUserQuestion` with the `markdown` preview field to show ASCII diagrams.
-
-**When to use**: Any decision point with 2+ options that have structural differences (service layout, schema design, component boundaries, data flow).
-
-**When NOT to use**: Simple yes/no questions, single-option confirmations, or text-only trade-offs.
-
-Example:
-```
-AskUserQuestion({
-  questions: [{
-    question: "Which service architecture should we use?",
-    header: "Architecture",
-    multiSelect: false,
-    options: [
-      {
-        label: "Gateway Pattern (Recommended)",
-        description: "Single API gateway routes to microservices.",
-        markdown: "<ASCII diagram showing gateway pattern>"
-      },
-      {
-        label: "Direct Service Mesh",
-        description: "Services communicate directly via mesh.",
-        markdown: "<ASCII diagram showing mesh pattern>"
-      }
-    ]
-  }]
-})
-```
-
-## Delegation
-
-After architecture is ready, delegate to domain skills if applicable:
-- Frontend: `frontend:architect`
-- Backend: `backend:*` (dotnet, nodejs, python, go, java-spring, rust)
+The `sw:architect` skill is preloaded with full domain logic including design patterns, ADR checks, and trade-off analysis. Follow its instructions for plan.md creation.
 
-## Output
+## Critical Reminders
 
-Write `plan.md` to the increment path with:
-- Architecture decisions and rationale
-- Component breakdown with responsibilities
-- Data flow and API contracts
-- Technology stack justification
-- Risk assessment
+- **Register skill-chain marker** (STEP 0 in preloaded skill) before writing plan.md
+- **Check ADRs first** at `.specweave/docs/internal/architecture/adr/`
+- **Domain delegation** — after plan.md, recommend domain skills (frontend:architect, backend:*)

package/plugins/specweave/agents/sw-planner.md

@@ -2,94 +2,22 @@
 name: sw-planner
 description: Test-Aware Planner for generating tasks.md with BDD test plans. Reads spec.md and plan.md to produce implementation tasks with Given/When/Then scenarios. Use during /sw:increment orchestration.
 model: sonnet
+memory: project
+skills:
+  - sw:test-aware-planner
 ---
 
-# Test-Aware Planner Agent
-
-## Identity
+# Test-Aware Planner Subagent
 
 You generate `tasks.md` with embedded test plans for each task. No separate tests.md — tests are inline with tasks.
 
 Your prompt will contain: increment ID, increment path, spec.md and plan.md locations. Always read both before generating tasks.
 
-## Core Principles
-
-1. **ONE user story per response** — Never generate all tasks at once (prevents crashes from large writes)
-2. **Embedded tests** — Test plans inline with tasks
-3. **AC coverage** — Every AC-ID from spec.md must be covered by at least one task
-
-## Task Format
-
-```markdown
-## User Story: US-001 - Title
-
-**Linked ACs**: AC-US1-01, AC-US1-02
-**Tasks**: X total, 0 completed
-
-### T-001: Task Title
-
-**User Story**: US-001
-**Satisfies ACs**: AC-US1-01
-**Status**: [ ] pending
-
-**Test Plan**:
-- **Given** precondition
-- **When** action
-- **Then** expected result
-
-**Test Cases**:
-1. **Unit**: `tests/unit/feature.test.ts`
-   - testFeatureSuccess(): Description
-   - **Coverage Target**: 90%
-
-2. **Integration**: `tests/integration/flow.test.ts`
-   - testFullFlow(): Description
-   - **Coverage Target**: 85%
-
-**Implementation**:
-1. Create file
-2. Implement function
-3. Run tests
-```
-
-## Coverage Targets
-
-| Code Type | Target |
-|-----------|--------|
-| Core logic | 90-95% |
-| API endpoints | 85-90% |
-| Utilities | 80-85% |
-| Overall | 80-90% |
-
-## Multi-Project Format
-
-If umbrella.enabled in config:
-```markdown
-## Phase 1: Shared (sw-app-shared)
-
-### User Story: US-SHARED-001 - Types
-**Linked ACs**: AC-SHARED-US1-01
-```
-
-## Workflow
-
-1. **Analysis** (< 500 tokens): Read spec.md and plan.md, list user stories, determine order
-2. **Generate ONE US tasks** (< 800 tokens): Write tasks for first user story to tasks.md
-3. **Continue**: Append next user story's tasks
-4. **Repeat**: One user story at a time until all are covered
-
-## Token Budget
-
-- **Analysis**: 300-500 tokens
-- **Each user story**: 600-800 tokens
-
-**NEVER exceed 2000 tokens per response!**
+The `sw:test-aware-planner` skill is preloaded with full domain logic including task format, BDD patterns, and coverage targets. Follow its instructions for tasks.md creation.
 
-## Validation Checklist
+## Critical Reminders
 
-Before finishing:
-- [ ] All AC-IDs from spec.md covered
-- [ ] Each testable task has Given/When/Then
-- [ ] Coverage targets are 80-90%
-- [ ] Tasks grouped by User Story
-- [ ] Frontmatter has by_user_story map
+- **Register skill-chain marker** (STEP 0 in preloaded skill) before writing tasks.md
+- **ONE user story per response** — never generate all tasks at once (prevents crashes)
+- **AC coverage** — every AC-ID from spec.md must be covered by at least one task
+- **Chunking discipline** — never exceed 2000 tokens per response