tlc-spec-driven
A 4-phase planning tool that breaks projects into atomic, verifiable tasks with persistent state management.
Install
mkdir -p .claude/skills/tlc-spec-driven && curl -L -o skill.zip "https://agentskills.codes/api/skills/download/8440" && unzip -o skill.zip -d .claude/skills/tlc-spec-driven && rm skill.zipInstalls to .claude/skills/tlc-spec-driven
Activation
This is the description your AI agent reads to decide when to run this skill — the better it matches your request, the more reliably it fires.
Project and feature planning with 4 adaptive phases - Specify, Design, Tasks, Execute. Auto-sizes depth by complexity. Creates atomic tasks with verification criteria, atomic git commits, requirement traceability, and persistent memory across sessions. Stack-agnostic. Use when (1) Starting new projects (initialize vision, goals, roadmap), (2) Working with existing codebases (map stack, architecture, conventions), (3) Planning features (requirements, design, task breakdown), (4) Implementing with verification and atomic commits, (5) Quick ad-hoc tasks (bug fixes, config changes), (6) Tracking decisions/blockers/deferred ideas across sessions, (7) Pausing/resuming work. Triggers on "initialize project", "map codebase", "specify feature", "discuss feature", "design", "tasks", "implement", "validate", "verify work", "UAT", "quick fix", "quick task", "pause work", "resume work". Do NOT use for architecture decomposition analysis (use architecture skills) or technical design docs (use create-technical-design-doc).Key capabilities
- →Define project specifications with requirement traceability
- →Break down features into atomic tasks with verification criteria
- →Maintain persistent project memory and decision logs
- →Execute implementation with atomic git commits
- →Validate outcomes using an independent verifier sub-agent
- →Distill verification failures into reusable project-local lessons
How it works
The skill follows a four-phase adaptive pipeline of Specify, Design, Tasks, and Execute. It auto-sizes the depth of these phases based on the complexity of the requested feature.
Inputs & outputs
When to use tlc-spec-driven
- →Initializing a new repository
- →Breaking down complex features into actionable tasks
- →Tracking project decisions and blockers
- →Mapping existing codebase architecture
About this skill
Tech Lead's Club - Spec-Driven Development
Plan and implement features with precision. Granular tasks. Clear dependencies. Right tools. Zero ceremony.
┌──────────┐ ┌──────────┐ ┌─────────┐ ┌─────────┐
│ SPECIFY │ → │ DESIGN │ → │ TASKS │ → │ EXECUTE │
└──────────┘ └──────────┘ └─────────┘ └─────────┘
required optional* optional* required
* Agent auto-skips when scope doesn't need it
Critical Rules (read before acting)
Loading this skill's files. Reference files live under references/ in this skill's own directory (where this SKILL.md resides). Resolve them relative to the skill directory, never the workspace root. When a step tells you to read a reference, read it to the end before acting.
Running this skill's scripts. Every scripts/*.py lives under that same skill directory: run python3 <skill-dir>/scripts/<name>.py ..., never python3 scripts/... from the project root. Project data under .specs/ is read and written relative to the project root (pass --root when the cwd is elsewhere). Run a script rather than read it: its messages say what to change. On Windows, where python3 may be the Microsoft Store alias, run python or py -3.
Execution contract - every task, non-negotiable (holds even if you do not open the reference files):
- Ask, then stop for approval. Every gray area that is the user's - scope, product behaviour, a departure from a binding source - is asked before the spec is presented; an assumption never stands in for one. Approving the spec and approving the tasks are the two stops for a human. When nobody is there to answer, end your turn with the questions. Each approval is written as
**Approved**: <date> - user: "<their words>"in spec.md and tasks.md; one the user did not give is never written. Every answer goes into its file in the turn it arrives - the chat does not survive a compaction. - Tests derive from the spec's acceptance criteria and assert spec-defined outcomes - they never mirror the implementation.
- The gate must pass before a task is done - the test runner decides, not self-assessment. One atomic commit per task, with
tasks.mdmarked complete before it - and inside it when the repo tracks.specs/; where the repo ignores.specs/, the commit holds only the code and its tests, and never forces them in. Never batch tasks; never weaken, skip, or delete tests to make them pass. - Every criterion has a check, and every check a proof. tasks.md
## Checksholds one claim per criterion with the project's own test command that selects its test - tests that run together share one**Run <name>**:line, and each check names the line its test prints (Proof: run <name> | <line>). After the LAST task,check_proofs.pyruns each group and lone proof once atHEAD, one at a time, with the build; then a fresh Verifier (author ≠ verifier) runs always, never prompted - it judges whether each check's test would fail if the claim were false, tries examples nobody named, and finds assertions looser than their criterion. Done means every finding is closed by a commit andvalidate_verification.pyexits 0. - A screen is held to its design. A capture that comes with the request binds unless the user called it inspiration; its criterion cites the capture file. Each state a capture draws is saved as
captures/<capture>.running.pngfrom a browser window at the capture's size - an image resized afterwards shows another layout - and a fresh screens sub-agent retakes and judges it (verify-screens.md). - Where rules run. Every rule that changes what a user sees - including filtering, searching, sorting and counting - runs in a layer the repo's tests reach.
- Blast radius: approving a spec or tasks authorizes local implementation and local commits only.
git push, force-push, deploy, production DB changes, and other remote or destructive operations need an explicit go-ahead for that action.
Deterministic gates run before human review - not from memory. A non-zero exit means STOP and fix:
| When | Command |
|---|---|
| Before presenting the spec | validate_spec.py <feature> - EARS criteria, filled assumptions, requirement IDs, and with captures: binding or quoted, cited, shown, departures approved |
| Before presenting the tasks | validate_tasks.py <feature> - granularity, dependencies, Tests and Gate per task, ## Checks with a proof each, **Build**:, a Run line and an expected line for each run proof |
| Before the first task | validate_tasks.py <feature> --execute - the same checks, the spec and tasks each approved in the user's words, and the **Build**: line run once: red before any change stops |
| Before each commit | check_commit.py --message "<msg>" - it also prints what follows the last task |
| After the last task, and after the fix | check_proofs.py <feature> - writes proofs.md |
| Before declaring the feature done | validate_verification.py <feature> - proofs green at HEAD, clean tree, a ## Checks row judging each check, findings closed, pictures judged in round 1 or 2, walk logged, both approvals written |
| After editing a script or a template | selftest.py |
Skip a script only when no code-execution tool is available; then perform the same checks by reading the artifact.
Before Execute: read implement.md completely and run validate_tasks.py <feature> --execute, which also requires both approvals in the user's words; if a formal tasks.md packs into more than one task-budgeted batch (> ~8 tasks), present the sub-agent offer first (see Sub-Agent Delegation).
Auto-Sizing: The Core Principle
The complexity determines the depth, not a fixed pipeline. Before starting any feature, assess its scope and apply only what's needed:
| Scope | What | Specify | Design | Tasks | Execute |
|---|---|---|---|---|---|
| Small | ≤3 files, one sentence | One-liner spec (inline) | Skip | Skip | Implement + verify inline |
| Medium | Clear feature, <10 tasks | Spec (brief) | Skip - design inline | Skip - tasks implicit | Implement + verify |
| Large | Multi-component feature | Full spec + requirement IDs | Architecture + components | Full breakdown + dependencies | Implement + verify per task |
| Complex | Ambiguity, new domain | Full spec + discuss gray areas | Research + architecture | Breakdown + phase plan | Implement + interactive UAT |
Rules:
- Specify and Execute are always required - you always need to know WHAT and DO it
- Design is skipped when the change is straightforward (no architectural decisions, no new patterns)
- Tasks is skipped when there are ≤3 obvious steps (they become implicit in Execute); the checks then go in a
## Checkssection at the end ofspec.md - Discuss is triggered within Specify when the agent detects gray areas that need user input, or when the feature has any implicit-requirement dimension present (persistence/state, external calls, auth, payments, concurrency, state transitions)
- Interactive UAT is triggered within Execute only for user-facing features with complex behavior
Safety valve: Even when Tasks is skipped, Execute ALWAYS starts by listing atomic steps inline (see implement.md). If that listing reveals >5 steps or complex dependencies, STOP and create a formal tasks.md - the Tasks phase was wrongly skipped.
.specs Structure
.specs/
├── STATE.md # Project memory: Decisions log (AD-NNN) + Handoff snapshot
├── LESSONS.md # Self-improving lessons playbook (rendered by scripts/lessons.py - do not hand-edit)
├── lessons.json # Canonical lessons state (machine-owned)
└── features/
└── [feature]/
├── spec.md # Requirements with traceable IDs, Differences from the source, Sources
├── captures/ # binding design files, and <capture>.running.png pictures
├── context.md # User decisions for gray areas (only when discuss is triggered)
├── design.md # Architecture & components (only for Large/Complex)
├── tasks.md # Atomic tasks, ## Checks with a proof each, ## Handoff
├── proofs.md # written by check_proofs.py: every proof at HEAD, and each run's output
├── screens.md # the screens sub-agent's inventory and verdict, per picture
└── verification.md # the Verifier's judgement of each check, and its findings closed by commits
Create artifacts lazily. Write each file only when its phase produces content - never scaffold empty context.md, design.md, or tasks.md up front. Absence is the correct state for a skipped phase.
Workflow
New feature:
- Specify → (Design) → (Tasks) → Execute (depth auto-sized)
Resume work - a new session, or after a compaction:
- Re-read this file, then the reference for the phase the files show. A summary keeps the task, not these rules.
- Read
.specs/STATE.mdDecisions and the feature's files -spec.mdandtasks.md(their**Approved**:lines, marks and
Content truncated.
When not to use it
- →Architecture decomposition analysis
- →Creating technical design documents
Prerequisites
Limitations
- →Requires manual intervention for sub-agent dispatching
- →Bounded to 3 iterations for fix-and-verify loops
- →Context limit of 40k tokens for active files
How it compares
Unlike manual planning, this skill enforces an automated, spec-anchored verification gate where the author and verifier are distinct agents.
Compared to similar skills
tlc-spec-driven side by side with the closest alternatives in the catalog.
| Skill | Installs | Updated | Safety | Difficulty |
|---|---|---|---|---|
| tlc-spec-driven (this skill) | 7 | 7mo | No flags | Intermediate |
| trello | 41 | 6mo | Review | Beginner |
| executing-plans | 6 | 6mo | No flags | Intermediate |
| github-project-management | 4 | 9mo | Review | Advanced |
Try saying
Example prompts that trigger this skill in your AI assistant.
More by tech-leads-club
View all by tech-leads-club →You might also like
trello
openclaw
Manage Trello boards, lists, and cards via the Trello REST API.
executing-plans
obra
Use when you have a written implementation plan to execute in a separate session with review checkpoints
github-project-management
ruvnet
Comprehensive GitHub project management with swarm-coordinated issue tracking, project board automation, and sprint planning
project-clickup
incidentfox
ClickUp project management integration for incident tracking and task management
coo-advisor
alirezarezvani
Operations leadership for scaling companies. Process design, OKR execution, operational cadence, and scaling playbooks. Use when designing operations, setting up OKRs, building processes, scaling teams, analyzing bottlenecks, planning operational cadence, or when user mentions COO, operations, process improvement, OKRs, scaling, operational efficiency, or execution.
sparv
cexll
Minimal SPARV workflow (Specify→Plan→Act→Review→Vault) with 10-point spec gate, unified journal, 2-action saves, 3-failure protocol, and EHRB risk detection.