Tech Lead's Club - Spec-Driven Development

Overview

This public intake copy packages

packages/skills-catalog/skills/(development)/tlc-spec-driven

https://github.com/tech-leads-club/agent-skills

Use it when the operator needs the upstream workflow, support files, and repository context to stay intact while the public validator and private enhancer continue their normal downstream flow.

This intake keeps the copied upstream files intact and uses

metadata.json

ORIGIN.md

Tech Lead's Club - Spec-Driven Development Plan and implement projects 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

Imported source sections that did not map cleanly to the public headings are still preserved below or in the support files. Notable imported sections: Project Structure, Context Loading Strategy, Sub-Agent Delegation, Skill Integrations, Knowledge Verification Chain, Output Behavior.

When to Use This Skill

Use this section as the trigger filter. It should make the activation boundary explicit before the operator loads files, runs commands, or opens a pull request.

• Use when the request clearly matches the imported source intent: 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....
• Use when the operator should preserve upstream workflow detail instead of rewriting the process from scratch.
• Use when provenance needs to stay visible in the answer, PR, or review packet.
• Use when copied upstream references, examples, or scripts materially improve the answer.
• Use when the workflow should remain reviewable in the public intake repo before the private enhancer takes over.

Operating Table

metadata.json

ORIGIN.md

references/brownfield-mapping.md

references/code-analysis.md

## Related Skills

Workflow

This workflow is intentionally editorial and operational at the same time. It keeps the imported source useful to the operator while still satisfying the public intake standards that feed the downstream enhancer flow.

1. Initialize project → PROJECT.md + ROADMAP.md
2. For each feature → Specify → (Design) → (Tasks) → Execute (depth auto-sized)
3. Map codebase → 7 brownfield docs
4. For each feature → same adaptive workflow
5. Confirm the user goal, the scope of the imported workflow, and whether this skill is still the right router for the task.
6. Read the overview and provenance files before loading any copied upstream support files.
7. Load only the references, examples, prompts, or scripts that materially change the outcome for the current request.

Imported Workflow Notes

Imported: Workflow

New project:

1. Initialize project → PROJECT.md + ROADMAP.md
2. For each feature → Specify → (Design) → (Tasks) → Execute (depth auto-sized)

Existing codebase:

1. Map codebase → 7 brownfield docs
2. Initialize project → PROJECT.md + ROADMAP.md
3. For each feature → same adaptive workflow

Quick mode: Describe → Implement → Verify → Commit (for ≤3 files, one-sentence scope)

Imported: Project Structure

.specs/
├── project/
│   ├── PROJECT.md      # Vision & goals
│   ├── ROADMAP.md      # Features & milestones
│   └── STATE.md        # Memory: decisions, blockers, lessons, todos, deferred ideas
├── codebase/           # Brownfield analysis (existing projects)
│   ├── STACK.md
│   ├── ARCHITECTURE.md
│   ├── CONVENTIONS.md
│   ├── STRUCTURE.md
│   ├── TESTING.md
│   ├── INTEGRATIONS.md
│   └── CONCERNS.md
├── features/           # Feature specifications
│   └── [feature]/
│       ├── spec.md     # Requirements with traceable IDs
│       ├── context.md  # User decisions for gray areas (only when discuss is triggered)
│       ├── design.md   # Architecture & components (only for Large/Complex)
│       └── tasks.md    # Atomic tasks with verification (only for Large/Complex)
└── quick/              # Ad-hoc tasks (quick mode)
    └── NNN-slug/
        ├── TASK.md
        └── SUMMARY.md

Examples

Example 1: Ask for the upstream workflow directly

Use @tlc-spec-driven to handle <task>. Start from the copied upstream workflow, load only the files that change the outcome, and keep provenance visible in the answer.

Explanation: This is the safest starting point when the operator needs the imported workflow, but not the entire repository.

Example 2: Ask for a provenance-grounded review

Review @tlc-spec-driven against metadata.json and ORIGIN.md, then explain which copied upstream files you would load first and why.

Explanation: Use this before review or troubleshooting when you need a precise, auditable explanation of origin and file selection.

Example 3: Narrow the copied support files before execution

Use @tlc-spec-driven for <task>. Load only the copied references, examples, or scripts that change the outcome, and name the files explicitly before proceeding.

Explanation: This keeps the skill aligned with progressive disclosure instead of loading the whole copied package by default.

Example 4: Build a reviewer packet

Review @tlc-spec-driven using the copied upstream files plus provenance, then summarize any gaps before merge.

Explanation: This is useful when the PR is waiting for human review and you want a repeatable audit packet.

Imported Usage Notes

Imported: Commands

Project-level:

Feature-level (auto-sized):

Best Practices

Treat the generated public skill as a reviewable packaging layer around the upstream repository. The goal is to keep provenance explicit and load only the copied source material that materially improves execution.

• Scope - What - Specify - Design - Tasks - Execute
• Small - ≤3 files, one sentence - Quick mode — skip pipeline entirely - - - - - -
• 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 + parallel plan - Implement + interactive UAT
• 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)

Imported Operating Notes

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

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)
• Discuss is triggered within Specify only when the agent detects ambiguous gray areas that need user input
• Interactive UAT is triggered within Execute only for user-facing features with complex behavior
• Quick mode is the express lane — for bug fixes, config changes, and small tweaks

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

Troubleshooting

Problem: The operator skipped the imported context and answered too generically

Symptoms: The result ignores the upstream workflow in

packages/skills-catalog/skills/(development)/tlc-spec-driven

metadata.json

ORIGIN.md

Problem: The imported workflow feels incomplete during review

Symptoms: Reviewers can see the generated

SKILL.md

Problem: The task drifted into a different specialization

Symptoms: The imported skill starts in the right place, but the work turns into debugging, architecture, design, security, or release orchestration that a native skill handles better. Solution: Use the related skills section to hand off deliberately. Keep the imported provenance visible so the next skill inherits the right context instead of starting blind.

Related Skills

• @accessibility

  - Use when the work is better handled by that native specialization after this imported skill establishes context.

• @ai-cold-outreach

  - Use when the work is better handled by that native specialization after this imported skill establishes context.

• @ai-pricing

  - Use when the work is better handled by that native specialization after this imported skill establishes context.

• @ai-sdr

  - Use when the work is better handled by that native specialization after this imported skill establishes context.

Additional Resources

Use this support matrix and the linked files below as the operator packet for this imported skill. They should reflect real copied source material, not generic scaffolding.

references

references/brownfield-mapping.md

examples

examples/n/a

scripts

scripts/n/a

agents

agents/n/a

assets

assets/n/a

• brownfield-mapping.md
• code-analysis.md
• coding-principles.md
• concerns.md
• README.md
• brownfield-mapping.md

Imported Reference Notes

Imported: Context Loading Strategy

Base load (~15k tokens):

• PROJECT.md (if exists)
• ROADMAP.md (when planning/working on features)
• STATE.md (persistent memory)

On-demand load:

• Codebase docs (when working in existing project)
• CONCERNS.md (when planning features that touch flagged areas, estimating risk, or modifying fragile components)
• TESTING.md (when creating tasks or executing — drives test type assignment and gate checks)
• spec.md (when working on specific feature)
• context.md (when designing or implementing from user decisions)
• design.md (when implementing from design)
• tasks.md (when executing tasks)

Never load simultaneously:

• Multiple feature specs
• Multiple architecture docs
• Archived documents

Target: <40k tokens total context Reserve: 160k+ tokens for work, reasoning, outputs Monitoring: Display status when >40k (see context-limits.md)

Imported: Sub-Agent Delegation

Use sub-agents (the Task tool or equivalent) to keep the main context window lean and enable parallel execution. The orchestrating agent plans and coordinates; sub-agents do the heavy lifting.

When to delegate to a sub-agent:

[P]

[P]

Context each sub-agent receives:

The orchestrating agent MUST provide each sub-agent with:

• The specific task definition from tasks.md (What, Where, Depends on, Reuses, Done when, Tests, Gate)
• Relevant coding principles and conventions (coding-principles.md, CONVENTIONS.md)
• TESTING.md, if it exists (for gate check commands and test patterns)
• Any spec/design context the task references

The sub-agent does NOT receive: other tasks' definitions, accumulated chat history, validation reports from other tasks, or STATE.md (unless the task explicitly references a decision/blocker).

What sub-agents return:

Each sub-agent reports back:

• Status: Complete | Blocked | Partial
• Files changed: [list]
• Gate check result: [pass/fail + test counts]
• SPEC_DEVIATION markers (if any)
• Issues encountered (if any)

The orchestrating agent uses this to update tasks.md status, traceability, and decide next steps.

Imported: Skill Integrations

This skill coexists with other skills. Before specific tasks, check if complementary skills are installed and prefer them when available.

Diagrams → mermaid-studio

Whenever the workflow requires creating or updating a diagram (architecture overviews, data flows, component diagrams, sequence diagrams, etc.), always check if the

mermaid-studio

mermaid-studio

Code Exploration → codenavi

Whenever the workflow requires exploring or discovering things in an existing repository (brownfield mapping, code reuse analysis, pattern identification, dependency tracing, etc.), always check if the

codenavi

codenavi

Imported: Knowledge Verification Chain

When researching, designing, or making any technical decision, follow this chain in strict order. Never skip steps.

Step 1: Codebase → check existing code, conventions, and patterns already in use
Step 2: Project docs → README, docs/, inline comments, .specs/codebase/
Step 3: Context7 MCP → resolve library ID, then query for current API/patterns
Step 4: Web search → official docs, reputable sources, community patterns
Step 5: Flag as uncertain → "I'm not certain about X — here's my reasoning, but verify"

Rules:

• Never skip to Step 5 if Steps 1-4 are available
• Step 5 is ALWAYS flagged as uncertain — never presented as fact
• NEVER assume or fabricate. If you cannot find an answer, say "I don't know" or "I couldn't find documentation for this". Inventing APIs, patterns, or behaviors causes cascading failures across design → tasks → implementation. Uncertainty is always preferable to fabrication.

Imported: Output Behavior

Model guidance: After completing lightweight tasks (validation, state updates, session handoff), naturally mention once that such tasks work well with faster/cheaper models. Track in STATE.md under

Preferences

Be conversational, not robotic. Don't interrupt workflow—add as a natural closing note. Skip if user seems experienced or has already acknowledged the tip.

Imported: Code Analysis

Use available tools with graceful degradation. See code-analysis.md.