test-aware-planner
Test-Aware Planning agent that generates tasks.md **ONE USER STORY AT A TIME** with embedded test plans. **CRITICAL CHUNKING RULE - Prevents crashes.** Activates for test planning, task generation with tests, BDD scenarios, coverage planning, and test-driven task breakdown. Keywords test-aware planning, chunked generation, BDD, Given-When-Then, test cases, coverage targets, embedded tests, tasks.md generation, test strategy, unit tests, integration tests, E2E tests, testable acceptance criteria.
When & Why to Use This Skill
The Test-Aware Planner is a specialized agent designed to bridge the gap between software requirements and implementation through test-driven task generation. It automates the creation of a comprehensive `tasks.md` file, embedding BDD-style test plans (Given-When-Then) and coverage targets directly into each task. By enforcing a strict 'one user story at a time' chunking rule, it ensures high-quality, stable output that prevents AI context crashes while maintaining 100% alignment with acceptance criteria.
Use Cases
- Automating Test-Driven Development (TDD) workflows by generating detailed unit, integration, and E2E test plans before coding begins.
- Breaking down complex product specifications into granular, testable tasks to ensure full coverage of acceptance criteria (AC).
- Implementing Behavior-Driven Development (BDD) using Given-When-Then scenarios to align technical tasks with business requirements.
- Managing large-scale project planning by processing user stories incrementally to stay within token limits and prevent AI generation errors.
- Establishing clear code coverage targets (80-90%) for core logic and API endpoints during the initial planning phase.
| name | test-aware-planner |
|---|---|
| description | Test-Aware Planning agent that generates tasks.md **ONE USER STORY AT A TIME** with embedded test plans. **CRITICAL CHUNKING RULE - Prevents crashes.** Activates for test planning, task generation with tests, BDD scenarios, coverage planning, and test-driven task breakdown. Keywords test-aware planning, chunked generation, BDD, Given-When-Then, test cases, coverage targets, embedded tests, tasks.md generation, test strategy, unit tests, integration tests, E2E tests, testable acceptance criteria. |
| allowed-tools | Read, Write, Grep, Glob, Edit |
Test-Aware Planner Skill
Overview
You generate tasks.md with embedded test plans for each task. No separate tests.md - tests are inline with tasks.
Progressive Disclosure
Load phases as needed:
| Phase | When to Load | File |
|---|---|---|
| Spec Analysis | Reading spec.md/plan.md | phases/01-spec-analysis.md |
| Task Generation | Creating tasks | phases/02-task-generation.md |
| Validation | Checking AC coverage | phases/03-validation.md |
Core Principles
- ONE user story per response - Never generate all tasks at once
- Embedded tests - Test plans inline with tasks
- AC coverage - Every AC-ID must be covered
Quick Reference
Task Format
## 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:
## Phase 1: Shared (sw-app-shared)
### User Story: US-SHARED-001 - Types
**Linked ACs**: AC-SHARED-US1-01
Workflow
- Analysis (< 500 tokens): List user stories, ask which first
- Generate ONE US tasks (< 800 tokens): Write to tasks.md
- Report progress: "US-001 complete. Ready for US-002?"
- Repeat: One user story at a time
Token Budget
- Analysis: 300-500 tokens
- Each user story: 600-800 tokens
NEVER exceed 2000 tokens per response!
Validation Checklist
- 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