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.zip

Installs 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).
1023 chars✓ has a “when” triggerlonger than Claude Code's old 250-char listing cap (fine on current versions)
Intermediate

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

You give it
Feature requirements or project goals
You get back
Implemented code with verification reports and decision logs

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):

  1. 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.
  2. Tests derive from the spec's acceptance criteria and assert spec-defined outcomes - they never mirror the implementation.
  3. The gate must pass before a task is done - the test runner decides, not self-assessment. One atomic commit per task, with tasks.md marked 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.
  4. Every criterion has a check, and every check a proof. tasks.md ## Checks holds 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.py runs each group and lone proof once at HEAD, 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 and validate_verification.py exits 0.
  5. 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.png from 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).
  6. 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.
  7. 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:

WhenCommand
Before presenting the specvalidate_spec.py <feature> - EARS criteria, filled assumptions, requirement IDs, and with captures: binding or quoted, cited, shown, departures approved
Before presenting the tasksvalidate_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 taskvalidate_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 commitcheck_commit.py --message "<msg>" - it also prints what follows the last task
After the last task, and after the fixcheck_proofs.py <feature> - writes proofs.md
Before declaring the feature donevalidate_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 templateselftest.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:

ScopeWhatSpecifyDesignTasksExecute
Small≤3 files, one sentenceOne-liner spec (inline)SkipSkipImplement + verify inline
MediumClear feature, <10 tasksSpec (brief)Skip - design inlineSkip - tasks implicitImplement + verify
LargeMulti-component featureFull spec + requirement IDsArchitecture + componentsFull breakdown + dependenciesImplement + verify per task
ComplexAmbiguity, new domainFull spec + discuss gray areasResearch + architectureBreakdown + phase planImplement + 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 ## Checks section at the end of spec.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:

  1. Specify → (Design) → (Tasks) → Execute (depth auto-sized)

Resume work - a new session, or after a compaction:

  1. Re-read this file, then the reference for the phase the files show. A summary keeps the task, not these rules.
  2. Read .specs/STATE.md Decisions and the feature's files - spec.md and tasks.md (their **Approved**: lines, marks and

Content truncated.

When not to use it

  • →Architecture decomposition analysis
  • →Creating technical design documents

Prerequisites

Access to .specs/ directory for state and feature files

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.

SkillInstallsUpdatedSafetyDifficulty
tlc-spec-driven (this skill)77moNo flagsIntermediate
trello416moReviewBeginner
executing-plans66moNo flagsIntermediate
github-project-management49moReviewAdvanced

Try saying

Example prompts that trigger this skill in your AI assistant.

More by tech-leads-club

View all by tech-leads-club →

accessibility

tech-leads-club

Audit and improve web accessibility following WCAG 2.1 guidelines. Use when asked to "improve accessibility", "a11y audit", "WCAG compliance", "screen reader support", "keyboard navigation", or "make accessible".

42174

perf-lighthouse

tech-leads-club

Run Lighthouse audits locally via CLI or Node API, parse and interpret reports, set performance budgets. Use when measuring site performance, understanding Lighthouse scores, setting up budgets, or integrating audits into CI. Triggers on: lighthouse, run lighthouse, lighthouse score, performance audit, performance budget.

1361

subagent-creator

tech-leads-club

Guide for creating AI subagents with isolated context for complex multi-step workflows. Use when users want to create a subagent, specialized agent, verifier, debugger, or orchestrator that requires isolated context and deep specialization. Works with any agent that supports subagent delegation. Triggers on "create subagent", "new agent", "specialized assistant", "create verifier".

828

aws-advisor

tech-leads-club

Expert AWS Cloud Advisor for architecture design, security review, and implementation guidance. Leverages AWS MCP tools for accurate, documentation-backed answers. Use when user asks about AWS architecture, security, service selection, migrations, troubleshooting, or learning AWS. Triggers on AWS, Lambda, S3, EC2, ECS, EKS, DynamoDB, RDS, CloudFormation, CDK, Terraform, Serverless, SAM, IAM, VPC, API Gateway, or any AWS service.

529

cursor-subagent-creator

tech-leads-club

Creates Cursor-specific AI subagents with isolated context for complex multi-step workflows. Use when creating subagents for Cursor editor specifically, following Cursor's patterns and directories (.cursor/agents/). Triggers on "cursor subagent", "cursor agent".

538

domain-analysis

tech-leads-club

Identifies subdomains and suggests bounded contexts in any codebase following DDD Strategic Design. Use when analyzing domain boundaries, identifying business subdomains, assessing domain cohesion, mapping bounded contexts, or when the user asks about DDD strategic design, domain analysis, or subdomain classification.

39

Search skills

Search the agent skills registry