workflow-tdd-plan
TDD planning pipeline with multi-mode routing (plan/verify). Session discovery → context gathering (spawn_agent) → test coverage analysis (spawn_agent) → conditional conflict resolution → TDD task generation (spawn_agent) → structure validation → interactive verification. Produces IMPL_PLAN.md with Red-Green-Refactor cycles, task JSONs, TODO_LIST.md.
60
53%
Does it follow best practices?
Impact
Pending
No eval scenarios have been run
Passed
No known issues
Optimize this skill with Tessl
npx tessl skill review --optimize ./.codex/skills/workflow-tdd-plan/SKILL.mdQuality
Discovery
67%Based on the skill's description, can an agent find and select it at the right time? Clear, specific descriptions lead to better discovery.
The description is technically detailed and specific about what the skill does, listing a clear pipeline of actions and concrete output artifacts. However, it reads more like internal architecture documentation than a skill description optimized for selection, lacking an explicit 'Use when...' clause and using jargon (spawn_agent, multi-mode routing) that users wouldn't naturally use in requests. Adding natural trigger terms and explicit usage guidance would significantly improve discoverability.
Suggestions
Add an explicit 'Use when...' clause, e.g., 'Use when the user wants to plan an implementation using test-driven development, create a TDD plan, or generate test-first task breakdowns.'
Replace internal implementation jargon like 'spawn_agent', 'multi-mode routing', and 'session discovery' with user-facing language that describes the benefit, e.g., 'gathers project context', 'analyzes existing test coverage'.
Include natural trigger terms users would say, such as 'TDD plan', 'test-driven development', 'implementation plan', 'test-first approach', 'red-green-refactor workflow'.
| Dimension | Reasoning | Score |
|---|---|---|
Specificity | Lists multiple specific concrete actions: session discovery, context gathering, test coverage analysis, conflict resolution, TDD task generation, structure validation, interactive verification. Also names specific outputs (IMPL_PLAN.md, task JSONs, TODO_LIST.md). | 3 / 3 |
Completeness | The 'what' is well-covered with the pipeline steps and outputs, but there is no explicit 'Use when...' clause or equivalent trigger guidance explaining when Claude should select this skill. The 'when' is only implied by the technical context. | 2 / 3 |
Trigger Term Quality | Contains relevant terms like 'TDD', 'test coverage', 'Red-Green-Refactor', and 'plan/verify', but uses heavily technical jargon (spawn_agent, multi-mode routing, session discovery) that users wouldn't naturally say. Missing common user phrases like 'write tests first', 'test-driven', 'implementation plan'. | 2 / 3 |
Distinctiveness Conflict Risk | Highly specific niche combining TDD planning, multi-mode routing, and specific output artifacts (IMPL_PLAN.md, TODO_LIST.md). Very unlikely to conflict with other skills due to its unique pipeline structure and domain focus. | 3 / 3 |
Total | 10 / 12 Passed |
Implementation
39%Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.
This skill has outstanding workflow clarity with well-defined phases, conditional branching, validation checkpoints, and error recovery — it's a model for complex pipeline design. However, it is severely undermined by extreme verbosity (the ASCII diagrams alone consume significant tokens, and TDD concepts are repeated multiple times) and a complete lack of progressive disclosure despite being one of the longest skill files possible. The code, while mostly concrete, has some incomplete sections that prevent full actionability.
Suggestions
Extract the detailed phase implementations into separate files (e.g., phases/phase-2-context.md, phases/phase-5-generation.md) and keep SKILL.md as a concise overview with the pipeline diagram and references.
Remove the ASCII pipeline diagram OR the data flow diagram — they convey nearly identical information. Keep whichever is more compact.
Eliminate the repeated TDD compliance section at the bottom — the Red-Green-Refactor requirements are already thoroughly specified in Phase 5's agent instructions and Phase 6's validation logic.
Fix incomplete code in Phase 4 (undefined `conflicts` variable, unclear `ccw cli` integration) and Phase 7 (syntax error in the conditional) to make the code fully executable.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | Extremely verbose at ~500+ lines. The massive ASCII pipeline diagram, data flow diagram, and session structure could be drastically condensed. Much of the code is repetitive (e.g., session discovery logic, agent spawning patterns are nearly identical). The TDD compliance section at the end repeats concepts already covered in the workflow phases. Claude doesn't need explanations of what Red-Green-Refactor means. | 1 / 3 |
Actionability | Contains substantial executable JavaScript code with concrete spawn_agent calls, file paths, and JSON schemas. However, Phase 4's conflict resolution code is incomplete (references undefined `conflicts` variable, uses a `ccw cli` command without clear integration), and Phase 7 has a syntax error (`if (mode === 'verify' || /* auto-verify */)`). The code is illustrative but not fully copy-paste executable. | 2 / 3 |
Workflow Clarity | Excellent multi-step workflow with clear sequencing across 7 phases, conditional branching (Phase 4 only when risk ≥ medium), explicit validation in Phase 6 with error recovery options (Fix and Retry / Continue / Abort), a quality gate in Phase 7, and a clear confirmation gate after Phase 6. The error handling table provides recovery strategies for each failure mode. | 3 / 3 |
Progressive Disclosure | Monolithic wall of content with no references to external files despite being 500+ lines. The entire implementation, all phase details, data flow diagrams, session structure, error handling, and compliance requirements are all inline. This content desperately needs splitting — agent instructions, validation logic, and TDD compliance rules could each be separate referenced files. | 1 / 3 |
Total | 7 / 12 Passed |
Validation
72%Checks the skill against the spec for correct structure and formatting. All validation checks must pass before discovery and implementation can be scored.
Validation — 8 / 11 Passed
Validation for skill structure
| Criteria | Description | Result |
|---|---|---|
skill_md_line_count | SKILL.md is long (754 lines); consider splitting into references/ and linking | Warning |
allowed_tools_field | 'allowed-tools' contains unusual tool name(s) | Warning |
frontmatter_unknown_keys | Unknown frontmatter key(s) found; consider removing or moving to metadata | Warning |
Total | 8 / 11 Passed | |
- Repository
- catlog22/Claude-Code-Workflow
- Commit
227244f
- Reviewed
Table of Contents
Is this your skill?
If you maintain this skill, you can claim it as your own. Once claimed, you can manage eval scenarios, bundle related skills, attach documentation or rules, and ensure cross-agent compatibility.