Awesome-omni-skill comprehensive-tdd-planning

TDD planning with agent-per-file execution. Planning is verbose. Agent files are minimal execution context.

install

source · Clone the upstream repo

git clone https://github.com/diegosouzapw/awesome-omni-skill

Claude Code · Install into ~/.claude/skills/

T=$(mktemp -d) && git clone --depth=1 https://github.com/diegosouzapw/awesome-omni-skill "$T" && mkdir -p ~/.claude/skills && cp -r "$T/skills/ai-agents/comprehensive-tdd-planning" ~/.claude/skills/diegosouzapw-awesome-omni-skill-comprehensive-tdd-planning && rm -rf "$T"

manifest: skills/ai-agents/comprehensive-tdd-planning/SKILL.md

source content

Comprehensive TDD Planning v2.0.0

Architecture

Phase	Verbosity	Purpose
Planning ( `plan.md` )	Verbose	Figure things out, iterate, full specs
Execution ( `*.agent.md` )	Minimal	Distilled context for agent, ~200-400 lines

Directory Structure

NNNN-descriptive-name/
├── README.md           # Index, dependency graph, status matrix
├── plan.md             # Full verbose feature specs (planning reference)
├── interfaces.md       # Contract source of truth
├── gotchas.md          # Discovered issues (append-only)
└── agents/
    └── NNN_agent_[name].agent.md # Minimal execution context per agent (zero-padded)

Agent Files: Design Principles

Agent files are distilled execution context, not documentation.

IN Agent Files

Feature IDs + one-line TL;DRs
Interface contracts (your exports + what you receive)
Files to create/modify
Test IDs
Concise TDD cycles (one line per cycle)
Relevant gotchas (brief)
Done checklist

OUT of Agent Files

Verbose Gherkin (TL;DR sufficient)
Methodology explanations (agent knows TDD)
Git workflow (in CLAUDE.md)
Other agents' details
Historical context

Target Size

~200-400 lines for 2-4 features. Larger = split agent.

Searching is Failure

If agent files are well-constructed, searching

plan.md

is rare—only for unexpected edge cases. Frequent searching means agent files need improvement.

Workflow

Create Plan

Gather context → verbose
```
plan.md
```
Map interfaces →
```
interfaces.md
```
Draw dependencies →
```
README.md
```
Distill agent files →
```
agents/*.agent.md
```

Assign Work

Copy agents/columns.agent.md → paste to agent → done

During Execution

Agent works from their
```
.agent.md
```
Updates status when complete
Appends to
```
gotchas.md
```
if issues found
Searches only for unexpected edge cases

Status Values

Status	Meaning	Action
`GAP`	Not started	Begin work
`WIP`	In progress	Continue
`PASS`	Complete	Done
`BLOCKED`	Waiting on dep	Work elsewhere

Commands

Command	Purpose	When
`create-feature-plan`	Create new plan + agent files	Starting new work
`update-feature-plan`	Modify plan, regenerate agents	Mid-flight changes, interface evolution
`close-feature-agent`	Verify completion, sync status	Agent finishes work
`migrate-feature-plan`	Convert v1.x plan to v2.0.0	Existing plans need migration
`list-feature-plans`	List available plans	Finding plans
`work`	Smart orchestration (auto-detect plan, assess, suggest)	After PR merged, starting new session
`heal`	Auto-heal plan (cleanup, pattern detection)	Cleanup completed agents, detect issues
`run <plan>`	Select and run next best agent task	Ready to start work on plan
`next-task <plan>`	Select next task (no run)	Preview next task selection
`assess-agents <plan>`	Assess agent completion status	Check status, find cleanup needs

update-feature-plan

Handles mid-flight changes:

Apply feedback to verbose planning docs
Identify cascade - interface changes affect downstream agents
Regenerate affected agent files (distill, don't patch)
Verify consistency across all files

Key insight: Interface changes cascade. If #2's export changes, all agents that receive from #2 need regenerated files.

migrate-feature-plan

Converts v1.x plans (with

parallelization.md

speed_prompts.md

, YAML front matter) to v2.0.0:

Extract interfaces from YAML →
```
interfaces.md
```
Extract gotchas →
```
gotchas.md
```
Distill agent files from plan + parallelization →
```
agents/*.agent.md
```
Archive old files (
```
parallelization.md
```
,
```
speed_prompts.md
```
)

Lifecycle

create-feature-plan
       ↓
   [plan.md + agents/*.agent.md created]
       ↓
   [copy agent file to Claude]
       ↓
   [agent implements]
       ↓
   [PR merged]
       ↓
   just work (auto-detect plan, assess status, suggest next task)
       ↓
   [if cleanup needed] → just heal (auto-fix completed agents)
       ↓
close-feature-agent ←─────────────────┐
       ↓                              │
   [status synced, unblocked identified]
       ↓                              │
   [if interfaces changed] → update-feature-plan
       ↓                              │
   [next agent file ready]            │
       ↓                              │
   [repeat] ──────────────────────────┘

Smart Orchestration

After a PR is merged, use

just work

to:

Auto-detect plan from last merged PR (title, branch, description, files)
Assess status of all agents (completed, active, needs cleanup)
Identify cleanup (completed agents not moved to
```
completed/
```
)
Determine next task using scoring algorithm (dependencies, workload, priority)
Provide recommendations with clickable links to plan files

Use

just heal

to:

Auto-move completed agents to
```
completed/
```
directory
Detect stuck agents (WIP for 7+ days)
Identify dependency bottlenecks
Learn from patterns and suggest improvements

All commands support

--auto

flag to auto-detect plan from last PR:

```
just next-task --auto
```
```
just assess-agents --auto
```
```
just run-agent --auto
```

close-feature-agent

Lightweight checkpoint:

Verify - Files exist, exports match, tests pass
Sync - Update README.md status matrix
Report - Show newly-unblocked features
Capture - Sync gotchas to gotchas.md

Does NOT regenerate agent files (use

update-feature-plan

for that).

Workflow Entry Points

See

workflow.md

for complete workflow documentation including:

System overview (plan, agent, feature, status concepts)
Workflow states and transitions
Command decision tree
When to use each command
Common patterns and anti-patterns
Troubleshooting guide

Quick Reference: When to Use Which Command

Primary Entry Point:

```
/work
```
- After PR merge, starting work session, need status overview

Focused Entry Points:

```
/run-agent <plan>
```
or
```
/run-agent --auto
```
- Ready to start working, auto-selects next best agent
```
/plan-list-agents <plan>
```
- Want to see all agents and choose which one to run
```
/plan-cleanup
```
or
```
/heal
```
- Cleanup needed, want to auto-fix
```
/plan-check-status
```
or
```
/assess-agents <plan>
```
- Need detailed status, troubleshooting
```
/list-feature-plans
```
- Need to find a plan

After Work:

```
/close-feature-agent <agent-path>
```
- Verify completion, sync status

Plan Management:

```
/create-feature-plan
```
- Create new plan
```
/update-feature-plan <plan>
```
- Modify existing plan
```
/list-feature-plans
```
- List all plans

Key Principles

Planning is cheap - Be verbose, iterate
Execution context is precious - Minimal, dense
Distill, don't copy - Agent files are refined extracts
Interfaces are boundaries - Clear contracts enable parallelism
One agent, one file - Coherent context, no mental merging
Close the loop - Verify completion before moving on