Tlc Spec Driven

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

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 — the Tasks phase was wrongly skipped.

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

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)

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)

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:

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.

Commands

Project-level:

Feature-level (auto-sized):

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 skill is installed in the user's environment before proceeding. If it is installed, delegate all diagram creation and rendering to it. If it is not installed, proceed with inline mermaid code blocks as usual and recommend the user install mermaid-studio for richer diagram capabilities (rendering to SVG/PNG, validation, theming, etc.). Display this recommendation at most once per session.

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 skill is installed in the user's environment before proceeding. If it is installed, delegate code exploration and navigation tasks to it. If it is not installed, fall back to the built-in code analysis tools (see code-analysis.md) and recommend the user install codenavi for more effective codebase exploration. Display this recommendation at most once per session.

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.

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 to avoid repeating. For heavy tasks (brownfield mapping, complex design), briefly note the reasoning requirements before starting.

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.

Code Analysis

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

<p align="center"> <img src="https://img.shields.io/badge/Skill-TLC%20Spec--Driven-blue?style=for-the-badge" alt="skill badge" /> <img src="https://img.shields.io/badge/Stack-Agnostic-green?style=for-the-badge" alt="stack agnostic" /> <img src="https://img.shields.io/badge/Version-2.0.0-purple?style=for-the-badge" alt="version" /> </p>

<h1 align="center">🎯 TLC Spec-Driven</h1>

<p align="center"> <strong>Plan and implement projects with precision. Granular tasks. Clear dependencies. Right tools. Zero ceremony.</strong> </p>

<p align="center"> <em>From the <a href="https://github.com/tech-leads-club">Tech Lead's Club</a> community</em> </p>

<p align="center"> <strong>Author:</strong> <a href="https://github.com/felipfr">Felipe Rodrigues</a> · <a href="https://linkedin.com/in/felipfr">LinkedIn</a> </p>

✨ What Is This Skill?

TLC Spec-Driven transforms how AI agents approach software projects. Instead of a rigid, bureaucratic pipeline, it uses 4 adaptive phases that auto-size based on complexity — applying full rigor for complex features and skipping ceremony for simple ones:

┌──────────┐   ┌──────────┐   ┌─────────┐   ┌─────────┐
│ SPECIFY  │ → │  DESIGN  │ → │  TASKS  │ → │ EXECUTE │
└──────────┘   └──────────┘   └─────────┘   └─────────┘
   required      optional*      optional*     required

* Agent auto-skips when scope doesn't need it

The complexity is in the system, not in your workflow. You talk naturally — the skill decides how deep to go:

🚀 Quick Start

Installation

npx @tech-leads-club/agent-skills install -s tlc-spec-driven

First Commands

💬 Natural Conversation, Not Commands

>

These are trigger phrases, not strict commands. The skill works through natural conversation — talk to your agent like you would to a colleague. Say things like _"I want to build an authentication system"_ or _"Fix the login button, it returns 401"_. The agent understands context and intent, not just keywords.

📁 Project Structure

The skill creates a .specs/ directory to organize all project documentation:

.specs/
├── project/
│   ├── PROJECT.md      # Vision, goals, tech stack, constraints
│   ├── ROADMAP.md      # Milestones, features, status tracking
│   └── STATE.md        # Persistent memory: decisions, blockers, learnings, todos, deferred ideas
│
├── codebase/           # Brownfield analysis (existing projects only)
│   ├── STACK.md        # Technology stack and dependencies
│   ├── ARCHITECTURE.md # Patterns, data flow, code organization
│   ├── CONVENTIONS.md  # Naming, style, coding patterns
│   ├── STRUCTURE.md    # Directory layout and modules
│   ├── TESTING.md      # Test frameworks and patterns
│   ├── INTEGRATIONS.md # External services and APIs
│   └── CONCERNS.md     # Tech debt, risks, fragile areas
│
├── features/           # Feature specifications
│   └── [feature-name]/
│       ├── spec.md     # Requirements with traceable IDs (FEAT-01, AUTH-02...)
│       ├── context.md  # User decisions for gray areas (only when needed)
│       ├── design.md   # Architecture and components (only for large/complex)
│       └── tasks.md    # Atomic tasks with dependencies (only for large/complex)
│
└── quick/              # Ad-hoc tasks (quick mode)
    └── NNN-slug/
        ├── TASK.md     # Description + verification
        └── SUMMARY.md  # What was done + commit

🔄 The Four Adaptive Phases

Specify (always)

Goal: Capture WHAT to build with testable, traceable requirements.

The agent acts as a thinking partner — not an interviewer. It asks clarifying questions, challenges vagueness, and captures requirements with traceable IDs:

### P1: User Login ⭐ MVP

**User Story:** As a user, I want to log in so that I can access my account.

| Requirement ID | Acceptance Criteria                                                            |
| -------------- | ------------------------------------------------------------------------------ |
| AUTH-01        | WHEN user enters valid credentials THEN system SHALL authenticate and redirect |
| AUTH-02        | WHEN user enters invalid credentials THEN system SHALL display error message   |
| AUTH-03        | WHEN user is already logged in THEN system SHALL redirect to dashboard         |

Discuss gray areas (auto-triggered): When the spec has ambiguous, user-facing decisions (layout preferences, interaction patterns, error handling style), the agent automatically asks the user about them — creating a context.md that locks those decisions before design. This is NOT a separate phase — it only happens within Specify when ambiguity is detected.

Design (when needed)

Goal: Define HOW to build it. Architecture, components, what to reuse.

Skipped when: The change is straightforward — no architectural decisions, no new patterns. For simple features, design happens inline during Execute.

Includes research: Before designing with unfamiliar tech, the agent follows the Knowledge Verification Chain (codebase → project docs → Context7 MCP → web search → flag uncertain). It never assumes or fabricates — if it can't find documentation, it says so.

Output: design.md with architecture diagrams, component definitions, and integration points.

Tasks (when needed)

Goal: Break into GRANULAR, ATOMIC tasks with clear dependencies.

Skipped when: There are ≤3 obvious steps. In that case, tasks are listed inline at the start of Execute.

Safety valve: If listing inline steps reveals >5 steps or complex dependencies, the agent STOPS and creates a formal tasks.md — acknowledging that the Tasks phase was wrongly skipped.

Each task includes: What (deliverable), Where (file path), Depends on (prerequisites), Reuses (existing code), Requirement (traceable ID), Done when (verifiable criteria), Commit (message format).

Execute (always)

Goal: Implement one task at a time. Verify. Commit. Repeat.

Every task follows the same cycle:

Plan → Implement → Verify → Commit → Next

Key principles:

• Surgical changes — Only touch required files
• No scope creep — If it's not in the task, don't touch it. Capture ideas in STATE.md as Deferred Ideas
• Verify before commit — Check all "Done when" criteria
• Atomic git commits — One task = one commit, following Conventional Commits 1.0.0

feat(auth): add email validation to login form

refactor(api): extract token refresh logic into service

fix(cart): prevent negative quantity on item decrement

Feature-level validation happens after all tasks complete — including acceptance criteria checks, code quality review, and optionally interactive UAT for complex user-facing features.

⚡ Quick Mode

For small tasks (bug fixes, config changes, tweaks ≤3 files) that don't need the full pipeline:

You: Quick fix: login button returns 401 because token refresh skips expired check

Agent: Quick Task: Fix token refresh expired check
       Files: src/services/auth.ts
       Approach: Add expiry validation before refresh attempt
       Verify: Login with expired token returns new session, not 401

       [Implements...]

       ✅ Done. Committed: fix(auth): add expiry check to token refresh

Guardrails: Max 3 files, max 1 hour, no design decisions, no new dependencies. If any of these are exceeded, the agent recommends the full pipeline.

📋 Complete Command Reference

These trigger patterns help the agent recognize your intent, but you don't need to use them verbatim. Speak naturally — the agent understands variations and context.

Project-Level

Feature-Level (auto-sized)

🔁 Workflow Examples

Starting a New Project

You: Initialize project

Agent: I'll help you set up your project. Let me ask a few questions:
       1. What are you building?
       2. Who is it for and what problem does it solve?
       ...

You: [Answer questions]

Agent: ✅ Created .specs/project/PROJECT.md
       Next: Would you like to create a roadmap? Say "Create roadmap"

Working with an Existing Codebase

You: Map codebase

Agent: I'll analyze your existing codebase and document:
       - Technology stack, Architecture patterns, Coding conventions
       - Project structure, Testing infrastructure, External integrations
       - Concerns (tech debt, risks, fragile areas)

       [Analyzes codebase...]

       ✅ Created 7 brownfield docs in .specs/codebase/
       Next: Initialize project to define goals and roadmap

Implementing a Feature (auto-sized)

You: Specify feature user-authentication

Agent: [Asks clarifying questions, creates spec.md with requirement IDs]
       I notice some gray areas in the UX — how should failed login attempts behave?
       [Discusses gray areas, creates context.md]

You: Design the feature

Agent: [Researches JWT best practices via Context7, creates design.md]

You: Break into tasks

Agent: [Creates tasks.md with 8 atomic tasks + parallel execution plan]

You: Implement T1

Agent: Implementing T1: Create auth service interface
       Files: src/services/auth.interface.ts
       Approach: Define interface based on design
       Verify: Interface compiles, exports correctly

       [Implements...]

       ✅ Committed: feat(auth): create auth service interface
       Next available: T2, T3 [P] (parallel)

Quick Bug Fix

You: Quick fix: dark mode toggle doesn't persist after page refresh

Agent: Quick Task: Persist dark mode preference
       Files: src/hooks/useTheme.ts, src/utils/storage.ts
       Approach: Save preference to localStorage on toggle
       Verify: Toggle dark mode, refresh page, preference persists

       [Implements...]

       ✅ Committed: fix(theme): persist dark mode preference to localStorage

Session Continuity

You: Pause work

Agent: ✅ Created .specs/HANDOFF.md
       - Feature: user-authentication
       - Completed: T1, T2 (committed)
       - In progress: T3 (70%)
       - Next session: Continue T3, then T4

--- Later, new session ---

You: Resume work

Agent: Resuming user-authentication at T3
       - Completed: T1 (auth interface), T2 (token storage)
       - In progress: T3 - auth service at src/services/auth.service.ts:45
       - Next: Complete T3, then T4 (parallel with T5)

       Continue with T3?

🧠 Context Management

The skill is designed to work within context limits:

Target: <40k tokens loaded (20% of context) Reserve: 160k+ tokens for work, reasoning, outputs

When context exceeds 40k tokens, the skill displays a status indicator and suggests optimizations.

🔗 Skill Integrations

TLC Spec-Driven works even better when combined with complementary skills:

The skill automatically detects if these are installed and delegates specialized tasks to them. If not installed, it falls back gracefully and recommends them once per session.

📚 Reference Files

The skill includes detailed reference documentation loaded on-demand:

⚡ Tips for Best Results

Do's ✅

• Start with project initialization — Even for existing codebases
• Be specific about scope — Clear boundaries prevent creep
• Trust the auto-sizing — The agent applies the right depth
• Use natural language — No need to memorize commands
• Say "pause work" before ending — Enables seamless resumption
• Challenge the agent — If something looks wrong, say so

Don'ts ❌

• Don't force all phases — Let the agent skip what's unnecessary
• Don't work on multiple features at once — One feature per cycle
• Don't ignore verification — Even quick tasks need a verify step
• Don't accept vague answers — If the agent says something fuzzy, ask for specifics

💡 Model Recommendation

Best results with modern, reasoning-capable models:

>

- Claude Opus 4.6 / Sonnet 4.5 — Excellent for all phases

- Gemini 3 Pro / GPT 5.2 — Strong reasoning and large context window

- Gemini 3 Flash / Claude Haiku 4.5 — Great general-purpose performance

>

For cost optimization, the skill will suggest when lighter models are sufficient for simple tasks like validation or session handoff.

🤖 Compatibility

This skill works with any AI coding agent that supports skills or custom instructions.

Tested and verified on:

Note: If your agent supports loading custom instructions or skills, this skill should work. The agents above are simply where it has been actively tested.

❓ FAQ

Q: Can I skip phases? A: Yes! The skill auto-sizes. Design and Tasks are skipped for simple features. Quick mode skips the entire pipeline for small changes. You only get ceremony when scope demands it.

Q: What if my project already has code? A: Use "Map codebase" first. This creates 7 documents analyzing your existing architecture, conventions, stack, and concerns before you start adding features.

Q: How does requirement traceability work? A: Each requirement gets a unique ID (e.g., AUTH-01) in spec.md. Tasks reference these IDs, and validation checks which requirements are verified. You get a clear trail from spec → design → task → commit.

Q: What are atomic git commits? A: Each task produces exactly one commit following Conventional Commits 1.0.0. This means clean git history, easy bisect for debugging, and simple rollbacks when needed.

Q: Can I use this for small tasks or quick fixes? A: Yes! Say "Quick fix: [description]" for bug fixes, config changes, or small tweaks. You get quality guardrails (verify + commit) without the planning overhead.

Q: What happens if I close my session mid-task? A: Say "Pause work" before ending your session. This creates a handoff document. Next session, say "Resume work" to continue exactly where you left off.

Q: Does this work with any tech stack? A: Yes! The skill is completely stack-agnostic. It works with any language, framework, or architecture.

Q: What if the agent invents an API or pattern that doesn't exist? A: The skill enforces a strict Knowledge Verification Chain: codebase → project docs → Context7 MCP → web search → flag as uncertain. It NEVER fabricates information. If the agent can't find documentation, it will say "I don't know" instead of guessing.

📄 License

CC-BY-4.0 © Tech Lead's Club

<p align="center"> _{Built with ❤️ by the Tech Lead's Club community} </p>

Brownfield Mapping

Trigger: "Map codebase", "Analyze existing code", "Document current architecture"

Purpose: Understand existing project structure before adding features.

Process

Before starting, check if the codenavi skill is available for code exploration (see Skill Integrations in SKILL.md). If available, prefer it for all discovery and navigation tasks below.

High-level approach:

1. Explore directory structure systematically 2. Identify technology stack from dependency manifests 3. Extract patterns from representative code samples 4. Document observed conventions and architectures 5. Catalog external integrations 6. Identify concerns: tech debt, known bugs, security risks, performance bottlenecks, fragile areas

Analysis depth:

• Sample 5-10 representative files per category
• Focus on consistency and patterns, not exhaustive coverage
• Extract actual examples, not assumptions

Output: 7 Files in .specs/codebase/

---

1. STACK.md

Purpose: Document technology stack and dependencies.

Size limit: 2,000 tokens (~1,200 words)

Extract from:

• Dependency manifest files
• Build configuration
• Runtime configuration

Document:

# Tech Stack

**Analyzed:** [date]

## Core

- Framework: [detected name + version]
- Language: [detected name + version]
- Runtime: [detected name + version]
- Package manager: [detected manager]

## Frontend (if applicable)

- UI Framework: [name + version]
- Styling: [approach + tools]
- State Management: [library/pattern]
- Form Handling: [library if present]

## Backend (if applicable)

- API Style: [REST/GraphQL/gRPC + framework]
- Database: [ORM/query builder + database system]
- Authentication: [library/approach]

## Testing

- Unit: [framework]
- Integration: [framework]
- E2E: [framework if present]

## External Services

- [Category]: [Service name]
- [Category]: [Service name]

## Development Tools

- [Tool category]: [Tool name]

Instructions:

• Extract from actual dependency files
• Include versions for major dependencies
• Categorize by purpose
• Note testing frameworks explicitly

---

2. ARCHITECTURE.md

Purpose: Document architectural patterns and data flow.

Size limit: 4,000 tokens (~2,400 words)

Extract from:

• Directory organization
• Code structure analysis
• Repeated patterns across files

Document:

# Architecture

**Pattern:** [Identified pattern - monolith/microservices/modular/etc]

## High-Level Structure

[Create diagram/description based on actual organization]

## Identified Patterns

### [Pattern Name]

**Location:** [where this pattern lives]
**Purpose:** [what this achieves]
**Implementation:** [how it's structured]
**Example:** [reference to actual file/function]

### [Pattern Name]

[Same structure]

## Data Flow

### [Key Flow - e.g., Authentication/Payment/etc]

[Map actual flow from code analysis]

### [Key Flow]

[Map actual flow]

## Code Organization

**Approach:** [feature-based/layer-based/domain-driven/etc]

**Structure:**
[Document actual directory organization]

**Module boundaries:**
[How code is divided into modules/packages]

Instructions:

• Identify patterns from actual code, not assumptions
• Document observed architectural decisions
• Create flow diagrams for critical paths
• Reference concrete examples from codebase

---

3. CONVENTIONS.md

Purpose: Document code style and naming conventions.

Size limit: 3,000 tokens (~1,800 words)

Extract from:

• Analyzing 5-10 representative files
• Identifying consistent patterns
• Observing actual conventions in use

Document:

# Code Conventions

## Naming Conventions

**Files:**
[Observed pattern - document actual approach]
Examples: [actual filenames from codebase]

**Functions/Methods:**
[Observed pattern]
Examples: [actual function names]

**Variables:**
[Observed pattern]
Examples: [actual variable names]

**Constants:**
[Observed pattern]
Examples: [actual constant names]

## Code Organization

**Import/Dependency Declaration:**
[Observed ordering pattern]
[Example from actual file]

**File Structure:**
[Observed organization within files]
[Example from actual file]

## Type Safety/Documentation

**Approach:** [Type system/documentation approach used]
[Example from actual code]

## Error Handling

**Pattern:** [Observed error handling approach]
[Example from actual code]

## Comments/Documentation

**Style:** [When/how comments are used]
[Example from actual code]

Instructions:

• Extract patterns from actual code samples
• Document observed conventions, not ideal conventions
• Include concrete examples from codebase
• Note exceptions or variations where found

---

4. STRUCTURE.md

Purpose: Document directory layout and file organization.

Size limit: 2,000 tokens (~1,200 words)

Document:

# Project Structure

**Root:** [project root path]

## Directory Tree

[Visual tree representation - max 3 levels deep]

## Module Organization

### [Module/Area Name]

**Purpose:** [what this area handles]
**Location:** [where files live]
**Key files:** [important files in this area]

### [Module/Area Name]

[Same structure]

## Where Things Live

**[Capability/Feature]:**

- UI/Interface: [location]
- Business Logic: [location]
- Data Access: [location]
- Configuration: [location]

**[Capability/Feature]:**
[Same structure]

## Special Directories

**[Directory name]:**
**Purpose:** [what belongs here]
**Examples:** [key files in this directory]

Instructions:

• Create tree view of actual directory structure
• Limit depth to maintain readability
• Document purpose of key directories
• Map capabilities to physical locations

---

5. TESTING.md

Purpose: Document testing infrastructure and patterns.

Size limit: 4,000 tokens (~2,400 words)

Document:

# Testing Infrastructure

## Test Frameworks

**Unit/Integration:** [framework name + version]
**E2E:** [framework name + version]
**Coverage:** [tool if used]

## Test Organization

**Location:** [where tests live]
**Naming:** [test file naming pattern]
**Structure:** [how tests are organized]

## Testing Patterns

### Unit Tests

**Approach:** [observed pattern]
**Location:** [where unit tests live]
[Description of actual pattern used]

### Integration Tests

**Approach:** [observed pattern]
**Location:** [where integration tests live]
[Description of actual pattern used]

### E2E Tests

**Approach:** [observed pattern if present]
**Location:** [where E2E tests live]
[Description of actual pattern used]

## Test Execution

**Commands:** [how to run tests]
**Configuration:** [test configuration approach]

## Coverage Targets

**Current:** [if measurable]
**Goals:** [if documented]
**Enforcement:** [if automated]

## Test Coverage Matrix

Analyze the codebase to determine which code layers require which test types.
For each layer, document the required test type, file location pattern, and run command.

| Code Layer | Required Test Type          | Location Pattern       | Run Command |
| ---------- | --------------------------- | ---------------------- | ----------- |
| [layer]    | [unit/integration/e2e/none] | [glob or path pattern] | [command]   |

## Parallelism Assessment

| Test Type | Parallel-Safe? | Isolation Model | Evidence                      |
| --------- | -------------- | --------------- | ----------------------------- |
| [type]    | [Yes/No]       | [description]   | [file/pattern that proves it] |

## Gate Check Commands

| Gate Level | When to Use                            | Command                     |
| ---------- | -------------------------------------- | --------------------------- |
| Quick      | After tasks with unit tests only       | [unit test command]         |
| Full       | After tasks with e2e/integration tests | [unit + e2e commands]       |
| Build      | After phase completion                 | [build + lint + unit + e2e] |

Instructions:

• Identify test frameworks from dependencies and code
• Document actual testing patterns observed
• Note test organization approach
• Include execution instructions
• Test Coverage Matrix: Sample 5-10 existing test files to identify which layers are tested and how. Look at test file locations relative to source to determine patterns. Extract run commands from package.json, project.json, Makefile, CI config. Mark layers with no existing tests as "none" with a note in CONCERNS.md.
• Parallelism Assessment: NOT parallel-safe signals: shared DB connection (same URL from config), table-level cleanup in beforeEach/afterAll (.del(), DELETE FROM, TRUNCATE), shared mock state reset on globals. Parallel-safe signals: per-test DB creation (Testcontainers, dynamic schema, SQLite in-memory), data namespacing (all data keyed by unique test ID), no shared mutable state between test files, all deps mocked (jest.fn(), vi.fn()).
• Gate Check Commands: Extract from actual project commands — do not invent commands.

---

6. INTEGRATIONS.md

Purpose: Document external service integrations.

Size limit: 5,000 tokens (~3,000 words)

Document:

# External Integrations

## [Service Category]

**Service:** [service name]
**Purpose:** [what this integration provides]
**Implementation:** [where integration lives in code]
**Configuration:** [how service is configured]
**Authentication:** [auth approach if applicable]

## [Service Category]

[Same structure]

## API Integrations

### [API Name]

**Purpose:** [what this API provides]
**Location:** [where API client/code lives]
**Authentication:** [auth method]
**Key endpoints:** [major endpoints used]

## Webhooks

### [Webhook Source]

**Purpose:** [what events are handled]
**Location:** [webhook handler location]
**Events:** [event types processed]

## Background Jobs

**Queue system:** [system if used]
**Location:** [where job definitions live]
**Jobs:** [key background jobs]

Instructions:

• Identify integrations from code and configuration
• Document authentication approaches
• Note webhook handlers if present
• Include background job infrastructure

---

7. CONCERNS.md

Purpose: Surface actionable warnings about the codebase — tech debt, known bugs, security gaps, performance bottlenecks, fragile areas, scaling limits, risky dependencies, missing features, and test coverage gaps.

Size limit: 5,000 tokens (~3,000 words)

See concerns.md for the full template, guidelines, and examples.

Instructions:

• Document only concerns backed by evidence (file paths, measurements, reproduction steps)
• Include fix approaches, not just problems
• Omit sections with no findings
• Prioritize by risk/impact
• Use professional, solution-oriented tone

---

Total Context Budget

Combined: ~19,000 tokens (10% of context window) Acceptable for: Brownfield projects requiring codebase understanding Loading strategy: Load relevant docs on-demand based on task

Code Analysis Tools

Use graceful degradation for code search and structural analysis.

Tool Priority

1. ast-grep (sg) - Structural pattern-based search 2. ripgrep (rg) - Fast context-aware text search 3. grep - Standard text search (always available)

Detection

Check tool availability before use:

# Check for ast-grep
if command -v sg >/dev/null 2>&1; then
  # Use ast-grep for structural search
elif command -v rg >/dev/null 2>&1; then
  # Fall back to ripgrep
else
  # Use standard grep as final fallback
fi

Usage Examples

Finding function definitions:

# ast-grep (best - structural)
sg -p 'function $NAME($$$) { $$$ }'

# ripgrep (fallback - fast text)
rg '^function\s+\w+\(' --type-add 'source:*.[extension]' -t source

# grep (last resort - basic)
grep -r '^function ' --include="*.[extension]"

Finding imports/requires:

# ast-grep
sg -p 'import { $$$ } from "$MODULE"'

# ripgrep
rg '^import .* from' --type-add 'source:*.[extension]' -t source

# grep
grep -r '^import ' --include="*.[extension]"

Finding class/component definitions:

# ast-grep
sg -p 'class $NAME { $$$ }'

# ripgrep
rg '^(class|export class)\s+\w+' --type-add 'source:*.[extension]' -t source

# grep
grep -r '^class ' --include="*.[extension]"

Search Scope

Best practices:

• Limit to source file extensions relevant to project
• Exclude directories: node_modules, vendor, dist, build, .git
• Focus on source directories: src, lib, app
• Use file type filters when available

Performance tips:

• Use specific patterns over broad searches
• Limit directory depth with --max-depth (ripgrep/grep)
• Cache results for repeated queries

Fallback Notice

If ast-grep unavailable, display once per session:

⚠️ ast-grep not detected. Install for more precise structural code analysis.
   https://ast-grep.github.io/guide/quick-start.html

When to Use

• Finding usage patterns across codebase
• Identifying code structure and organization
• Locating function/class/component definitions
• Analyzing import/dependency patterns
• Refactoring impact analysis
• Code navigation in unfamiliar codebases

Coding Principles

Behavioral bias, not checklist. Read before every implementation.

---

Before Coding

• State assumptions explicitly. If uncertain, ask.
• Multiple interpretations exist? Present all—don't pick silently.
• Simpler approach exists? Say so. Push back when warranted.
• Something unclear? Stop. Name what's confusing. Ask.
• User's approach seems wrong? Disagree honestly. Don't be sycophantic.

---

During Implementation

Simplicity

• No features beyond what was asked
• No abstractions for single-use code
• No "flexibility" or "configurability" not requested
• No error handling for impossible scenarios
• 200 lines that could be 50? Rewrite it.

Surgical Changes

• Don't "improve" adjacent code, comments, or formatting
• Don't refactor things that aren't broken
• Match existing style, even if you'd do differently
• Unrelated dead code noticed? Mention it—don't delete it
• Remove ONLY imports/variables/functions YOUR changes orphaned
• Don't remove pre-existing dead code unless asked

Test Integrity

• NEVER weaken an existing test assertion to make it pass
• NEVER delete a test to reduce failure count
• NEVER use the test framework's skip/disable/pending mechanism to bypass a failing test
• NEVER modify tests written in the RED phase during GREEN phase
• If a test is genuinely wrong, STOP and confirm with the user before changing it
• Tests are the spec — implementation conforms to tests, not the other way around

Goal-Driven

• Transform vague tasks into verifiable goals
• Multi-step work? State brief plan with verify checkpoints
• Every changed line must trace directly to user's request

---

After Each Change

Ask: "Would senior engineer call this overcomplicated?" If yes → simplify before proceeding.

Phase: Codebase Concerns

Trigger: Part of brownfield mapping, or explicitly "document concerns", "find tech debt", "what's risky in this codebase"

Purpose: Surface actionable warnings about the codebase. Focused on "what to watch out for when making changes." This is living documentation, not a complaint list.

When to Generate

CONCERNS.md is generated as part of the brownfield mapping flow (alongside STACK.md, ARCHITECTURE.md, etc.). It can also be created or updated independently when:

• Exploring a new area of the codebase reveals risks
• A bug investigation uncovers systemic issues
• A feature implementation hits unexpected fragility
• A dependency audit reveals risks

Process

1. Gather Evidence

During codebase exploration, look for concrete signals — not opinions. Evidence sources:

• Code patterns that indicate shortcuts (TODO/FIXME/HACK comments, duplicated logic, missing error handling)
• Test coverage gaps (untested critical paths, missing edge cases)
• Dependency manifests (outdated packages, deprecated libraries, security advisories)
• Performance indicators (N+1 queries, missing indexes, synchronous blocking calls)
• Security patterns (client-side-only auth checks, unvalidated inputs, exposed secrets)

2. Classify and Document

Each concern must have: what the problem is, where it lives (file paths), why it matters (impact), and how to fix it (approach).

3. Prioritize by Risk

Focus on concerns that could cause real damage — data loss, security breaches, user-facing failures, scaling walls. Minor style issues and normal TODOs do not belong here.

---

Template: .specs/codebase/CONCERNS.md

Size limit: 5,000 tokens (~3,000 words)

# Codebase Concerns

**Analysis Date:** [YYYY-MM-DD]

## Tech Debt

**[Area/Component]:**

- Issue: [What's the shortcut/workaround]
- Files: [Specific file paths with backticks]
- Why: [Why it was done this way]
- Impact: [What breaks or degrades because of it]
- Fix approach: [How to properly address it]

## Known Bugs

**[Bug description]:**

- Symptoms: [What happens]
- Trigger: [How to reproduce]
- Files: [Where the bug lives]
- Workaround: [Temporary mitigation if any]
- Root cause: [If known]
- Blocked by: [If waiting on something]

## Security Considerations

**[Area requiring security care]:**

- Risk: [What could go wrong]
- Files: [Where the risk lives]
- Current mitigation: [What's in place now]
- Recommendations: [What should be added]

## Performance Bottlenecks

**[Slow operation/endpoint]:**

- Problem: [What's slow]
- Files: [Where the bottleneck lives]
- Measurement: [Actual numbers: "500ms p95", "2s load time"]
- Cause: [Why it's slow]
- Improvement path: [How to speed it up]

## Fragile Areas

**[Component/Module]:**

- Files: [Where the fragility lives]
- Why fragile: [What makes it break easily]
- Common failures: [What typically goes wrong]
- Safe modification: [How to change it without breaking]
- Test coverage: [Is it tested? Gaps?]

## Scaling Limits

**[Resource/System]:**

- Current capacity: [Numbers: "100 req/sec", "10k users"]
- Limit: [Where it breaks]
- Symptoms at limit: [What happens]
- Scaling path: [How to increase capacity]

## Dependencies at Risk

**[Package/Service]:**

- Risk: [e.g., "deprecated", "unmaintained", "breaking changes coming"]
- Impact: [What breaks if it fails]
- Migration plan: [Alternative or upgrade path]

## Missing Critical Features

**[Feature gap]:**

- Problem: [What's missing]
- Current workaround: [How users cope]
- Blocks: [What can't be done without it]
- Implementation complexity: [Rough effort estimate]

## Test Coverage Gaps

**[Untested area]:**

- What's not tested: [Specific functionality]
- Risk: [What could break unnoticed]
- Priority: [High/Medium/Low]
- Difficulty to test: [Why it's not tested yet]

---

_Concerns audit: [date]_
_Update as issues are fixed or new ones discovered_

Include only sections that have findings. Empty sections should be omitted entirely.

---

What Belongs vs. What Doesn't

Include:

• Tech debt with clear impact and fix approach
• Known bugs with reproduction steps
• Security gaps and mitigation recommendations
• Performance bottlenecks with measurements
• Fragile code that breaks easily
• Scaling limits with numbers
• Dependencies that need attention
• Missing features that block workflows
• Test coverage gaps

Exclude:

• Opinions without evidence ("code is messy")
• Complaints without solutions ("auth sucks")
• Future feature ideas (that's for product planning)
• Normal TODOs (those live in code comments)
• Architectural decisions that are working fine
• Minor code style issues

---

Writing Guidelines

• Always include file paths — Concerns without locations are not actionable. Use backticks: src/file.ts
• Be specific with measurements ("500ms p95" not "slow")
• Include reproduction steps for bugs
• Suggest fix approaches, not just problems
• Focus on actionable items
• Prioritize by risk/impact

Tone: Professional, not emotional. Solution-oriented. Risk-focused. Factual.

• ✅ "N+1 query pattern in app/api/courses/route.ts — 1.2s p95 with 50+ courses"
• ❌ "Terrible queries, everything is slow"
• ✅ "Fix: add index on user_id in subscriptions table"
• ❌ "Needs fixing"

---

How CONCERNS.md Gets Used

• Feature planning: Check CONCERNS.md before designing features that touch flagged areas
• Risk estimation: Use fragile areas and scaling limits to estimate change risk
• Onboarding new sessions: Load CONCERNS.md to give context about what to watch out for
• Refactoring prioritization: Use tech debt and test coverage gaps to plan improvement sprints
• Implementation phase: Consult before modifying any flagged component

This is living documentation. Update as issues are fixed or new ones discovered during any workflow phase.

Context Limits

File Size Limits

Context Zones

🟢 Healthy (<40k total): Silent 🟡 Moderate (40-60k): Discrete footer note 🔴 Critical (>60k): Active warning, suggest optimization

Monitoring

Display context status in footer when >40k:

📊 Context: 52k tokens (moderate)
  - STATE.md: 8k (yellow zone)
  - tasks.md: 11k (ok)
  - Total: 52k / 200k (26%)

Principles

Target: <40k tokens loaded (20% of window) Reserve: 160k+ tokens for work, reasoning, outputs

Design

Goal: Define HOW to build it. Architecture, components, what to reuse.

Skip this phase when: The change is straightforward — no architectural decisions, no new patterns, no component interactions to plan. For simple features, design happens inline during Execute.

Process

1. Load Context

Read .specs/features/[feature]/spec.md before designing. If .specs/features/[feature]/context.md exists, load it too — it contains implementation decisions that constrain the design (layout choices, behavior preferences, interaction patterns). Decisions marked as "Agent's Discretion" are yours to decide.

1.5. Research (Optional but Recommended)

If the feature involves unfamiliar technology, patterns, or integrations, research before designing. Document findings briefly in the design doc or as inline notes. This prevents incorrect assumptions from propagating into tasks.

Follow the Knowledge Verification Chain (see SKILL.md) in strict order:

Codebase → Project docs → Context7 MCP → Web search → Flag as uncertain

CRITICAL: NEVER assume or fabricate information. If you cannot find an answer through the chain, explicitly say "I don't know" or "I couldn't find documentation for this". Inventing an API, a pattern, or a behavior that doesn't exist is far worse than admitting uncertainty. Wrong assumptions propagate through design → tasks → implementation and cause cascading failures.

Good triggers for research: new libraries, unfamiliar APIs, performance-sensitive features, security-sensitive features, patterns you haven't used in this codebase before.

2. Define Architecture

Overview of how components interact. Use mermaid diagrams when helpful. Before creating any diagrams, check if the mermaid-studio skill is available (see Skill Integrations in SKILL.md).

3. Identify Code Reuse

CRITICAL: What existing code can we leverage? This saves tokens and reduces errors.

If .specs/codebase/CONCERNS.md exists, check it before designing. Any component flagged as fragile, carrying tech debt, or having test coverage gaps requires extra care in the design — document how the design mitigates those concerns.

4. Define Components and Interfaces

Each component: Purpose, Location, Interfaces, Dependencies, What it reuses.

5. Define Data Models

If the feature involves data, define models before implementation.

---

Template: .specs/[feature]/design.md

````markdown

[Feature] Design

Spec: .specs/[feature]/spec.md Status: Draft | Approved

---

Architecture Overview

[Brief description of the architecture approach]

graph TD
    A[User Action] --> B[Component A]
    B --> C[Service Layer]
    C --> D[Data Store]
    B --> E[Component B]

````

---

Code Reuse Analysis

Existing Components to Leverage

Integration Points

---

Components

[Component Name]

• Purpose: [What this component does - one sentence]
• Location: src/path/to/component/
• Interfaces:
• methodName(param: Type): ReturnType - [description]
• methodName(param: Type): ReturnType - [description]
• Dependencies: [What it needs to function]
• Reuses: [Existing code this builds upon]

[Component Name]

• Purpose: [What this component does]
• Location: src/path/to/component/
• Interfaces:
• methodName(param: Type): ReturnType
• Dependencies: [Dependencies]
• Reuses: [Existing code]

---

Data Models (if applicable)

[Model Name]

interface ModelName {
  id: string
  field1: string
  field2: number
  createdAt: Date
}

Relationships: [How this relates to other models]

[Model Name]

interface AnotherModel {
  id: string
  // ...
}

---

Error Handling Strategy

---

Tech Decisions (only non-obvious ones)

---

Tips

• Load context first — If context.md exists, decisions there are locked
• Research when uncertain — 5 minutes of research prevents hours of rework
• Reuse is king — Every component should reference existing patterns
• Interfaces first — Define contracts before implementation
• Keep it visual — Diagrams save 1000 words (check mermaid-studio skill in Skill Integrations)
• Small components — If component does 3+ things, split it
• Check CONCERNS.md — If it exists, flag fragile areas the design must address
• Confirm before Tasks — User approves design before breaking into tasks

Specify: Discuss Gray Areas

Goal: Capture HOW the user envisions the feature when the spec has ambiguous areas. This is NOT a separate phase — it's triggered within Specify when the agent detects gray areas that need user input.

Trigger: Automatically when gray areas are detected during spec creation, or explicitly via "discuss feature", "how should this work?", "capture context"

When to trigger (auto-detect): The spec contains user-facing behavior that could go multiple ways AND the user hasn't expressed a preference. If the spec is clear and unambiguous, skip this entirely.

When NOT to trigger: Infrastructure work, CRUD operations, well-defined API contracts, anything where the "how" is obvious from the "what".

Why This Phase Exists

Specifications capture WHAT to build. Design captures the architecture. But neither captures the user's vision for ambiguous areas — layout preferences, interaction patterns, error handling style, content tone. Without this, the agent guesses. With this, the agent builds what the user actually imagined.

The output — context.md — feeds directly into Design and Tasks:

• Design reads it to know what decisions are locked vs. flexible
• Tasks reads it to include specific behaviors in task definitions

Process

1. Analyze the Feature

Read .specs/features/[feature]/spec.md and identify the domain:

Generate 3-4 feature-specific gray areas. Not generic categories, but concrete decisions for THIS feature.

2. Present Gray Areas

Present the feature boundary (from spec.md) and the gray areas to the user. Let them choose which to discuss. Do NOT include a "skip all" option — the user invoked this phase to discuss.

3. Deep-Dive Each Area

For each selected area:

1. Ask 3-4 concrete questions with specific options (not vague categories) 2. After the questions, check: "More about [area], or move on?" 3. If more → ask 3-4 more, check again 4. After all areas → "Ready to create context?"

Question design:

• Options should be concrete ("Card layout" not "Option A")
• Each answer should inform the next question
• Include "You decide" as an option when reasonable — captures agent discretion

4. Scope Guardrail (CRITICAL)

The feature boundary from spec.md is fixed. Discussion clarifies HOW to implement, never WHETHER to add new capabilities.

Allowed: "How should posts be displayed?" (clarifying ambiguity) Not allowed: "Should we also add comments?" (new capability)

When user suggests scope creep: "That sounds like a separate feature. I'll note it in Deferred Ideas. Back to [current area]."

5. Write context.md

---

Template: .specs/features/[feature]/context.md

# [Feature] Context

**Gathered:** [date]
**Spec:** `.specs/features/[feature]/spec.md`
**Status:** Ready for design

---

## Feature Boundary

[Clear statement of what this feature delivers — the scope anchor from spec.md]

---

## Implementation Decisions

### [Area 1 that was discussed]

- [Specific decision made]
- [Another decision if applicable]

### [Area 2 that was discussed]

- [Specific decision made]

### [Area 3 that was discussed]

- [Specific decision made]

### Agent's Discretion

[Areas where user explicitly said "you decide" — agent has flexibility here during design/implementation]

---

## Specific References

[Any "I want it like X" moments, product references, specific behaviors, interaction patterns mentioned during discussion]

[If none: "No specific requirements — open to standard approaches"]

---

## Deferred Ideas

[Ideas that came up during discussion but belong in other features/phases. Captured here so they're not lost, but explicitly out of scope]

[If none: "None — discussion stayed within feature scope"]

---

Tips

• Decisions, not vision — "Card-based layout with subtle shadows" is a decision. "Should feel modern" is not.
• Scope is sacred — Deferred Ideas captures scope creep without losing ideas
• User = visionary, Agent = builder — Ask about how they imagine it, not about technical implementation
• Don't ask about: Technical architecture, performance, implementation details — that's Design's job
• Confirm before Design — User approves context.md before moving to design phase

Execute

Goal: Implement ONE task at a time. Surgical changes. Verify. Commit. Repeat.

This is where code gets written. Every task follows the same cycle: plan → implement → verify → commit. Verification is built into every task, not a separate phase.

---

MANDATORY: Before Starting Any Implementation

Read [coding-principles.md](coding-principles.md) and state:

1. Assumptions - What am I assuming? Any uncertainty? 2. Files to touch - List ONLY files this task requires 3. Success criteria - How will I verify this works?

⚠️ Do not proceed without stating these explicitly.

---

Process

Sub-agent context: When this task is executed by a sub-agent, the sub-agent receives the task definition, coding principles, TESTING.md, and relevant spec/design context. All steps below apply identically whether running in the main context or a sub-agent. The only difference: sub-agents report results back to the orchestrator rather than continuing to the next task.

0. List Atomic Steps (MANDATORY when Tasks phase was skipped)

If there is no tasks.md for this feature, you MUST list atomic steps before writing any code. This is non-negotiable — it prevents the agent from losing focus and doing too many things at once.

## Execution Plan

1. [Step] → files: [list] → verify: [how] → commit: [message]
2. [Step] → files: [list] → verify: [how] → commit: [message]
3. [Step] → files: [list] → verify: [how] → commit: [message]

Each step must be:

• ONE deliverable (one component, one function, one endpoint, one file change)
• Independently verifiable (can prove it works before moving on)
• Independently committable (gets its own atomic git commit)

If listing steps reveals >5 steps or complex dependencies, STOP and create a formal tasks.md instead. The Tasks phase was wrongly skipped.

1. Pick Task

From tasks.md (if exists) or from the execution plan above. User specifies ("implement T3") or suggest next available.

2. Verify Dependencies

If tasks.md exists, check dependencies. If using inline plan, follow the order listed.

❌ If blocked: "T3 depends on T2 which isn't done. Should I do T2 first?"

3. State Implementation Plan

Before writing code:

Files: [list]
Approach: [brief description]
Success: [how to verify]

4. Write Tests First (RED)

If the task includes tests (per the Tests field in tasks.md or TESTING.md coverage matrix):

1. Write the test file(s) BEFORE writing any implementation 2. Tests must encode the expected behavior from the task's "Done when" criteria 3. Run the test command — confirm tests FAIL (RED state) 4. If tests pass before implementation exists, the tests are too weak — rewrite them

Constraints:

• Tests define correct behavior independently of implementation
• Each acceptance criterion from "Done when" maps to at least one test assertion
• Edge cases from spec.md that apply to this task get test cases too

If the task does NOT include tests (e.g., entity-only, config-only), skip to Step 4b.

4b. Implement (GREEN)

Write the minimum implementation needed to satisfy the task's success criteria: pass all relevant tests (when present) and meet the defined verification/gate checks when there are no direct tests.

HARD CONSTRAINTS:

• Do NOT modify tests written in Step 4. The tests are the spec — implementation conforms to them.
• Do NOT weaken assertions (making them less specific to pass more easily)
• Do NOT delete or skip test cases
• Do NOT use the test framework's skip/disable/pending mechanism to bypass failing tests
• Minimum code to pass — save structural improvements for a refactor task

If a test is genuinely wrong (tests the wrong behavior per spec), STOP and ask the user before modifying it. Never silently change a test.

Follow coding-principles.md:

• Simplest code that works
• Touch ONLY listed files
• No scope creep

5. Gate Check (VERIFY)

Run the gate check command from the task definition. This is MANDATORY — not "if applicable."

1. Look up the command for the task's Gate level (quick/full/build) in TESTING.md's Gate Check Commands section, then run it 2. Non-zero exit code = STOP. Fix the failure. Re-run. Do not proceed until green. 3. Confirm the test count matches expectations (no tests were silently deleted or skipped)

Tiered gates (from TESTING.md Gate Check Commands):

The gate check is deterministic. The test runner decides if the code is correct, not the agent's self-assessment.

6. Post-Gate Review

After the gate check passes:

1. Verify test count: Are there at least as many test cases as before? (prevents silent deletion) 2. Verify no SPEC_DEVIATION: If implementation diverged from spec/design, add a marker:

// SPEC_DEVIATION: [what diverged]
// Reason: [why the deviation was necessary]

3. Quick complexity check: "Would senior engineer flag this as overcomplicated?"

• Yes → Simplify, re-run gate
• No → Proceed to commit

7. Atomic Git Commit

Each task gets its own commit immediately after verification. Never batch multiple tasks into one commit.

Format ([Conventional Commits 1.0.0](https://www.conventionalcommits.org/en/v1.0.0/)):

<type>(<scope>): <description>

[optional body]

[optional footer(s)]

Types:

Scope: Feature name or module area, lowercase, e.g., auth, cart, api

Description rules:

• Imperative mood ("add", not "added" or "adds")
• Lowercase first letter
• No period at the end
• Complete the sentence: "If applied, this commit will _[your description]_"

Breaking changes: Append ! after type/scope AND add BREAKING CHANGE: footer:

feat(api)!: change authentication endpoint response format

BREAKING CHANGE: login endpoint now returns JWT in body instead of cookie

Examples:

feat(auth): add email validation to login form

fix(cart): prevent negative quantity on item decrement

refactor(api): extract token refresh logic into service

Move token refresh from inline handler to dedicated AuthTokenService
for reuse across multiple endpoints.

Rules:

• One task = one commit
• Description references what was DONE, not what was planned
• Include only files listed in the task — never sneak in "while I'm here" changes
• If tests are part of the task, include them in the same commit

8. Scope Guardrail

During implementation, you will notice things that could be improved, refactored, or added. Do not act on them. Instead:

• If it's a bug: note it in STATE.md as a blocker or use quick mode
• If it's an improvement: note it in STATE.md under "Deferred Ideas" or "Lessons Learned"
• If it's related to the current task: only include it if it's in the "Done when" criteria

The heuristic: "Is this in my task definition?" If no, don't touch it.

9. Update Task Status

Mark task complete in tasks.md. Update requirement traceability in spec.md if requirement IDs are used.

---

Execution Template

## Implementing T[X]: [Task Title]

**Reading**: task definition from tasks.md
**Dependencies**: [All done? ✅ | Blocked by: TY]
**Tests**: [unit/e2e/integration/none]
**Gate**: [quick/full/build]

### Pre-Implementation (MANDATORY)

- **Assumptions**: [state explicitly]
- **Files to touch**: [list ONLY these]
- **Success criteria**: [how to verify]

### RED: Write Tests

- Test file(s): [paths]
- Test count: [N test cases]
- Confirmed failing: [Yes — all N tests fail as expected]

### GREEN: Implement

[Write minimum code to pass tests]

- Tests modified: None
- Tests skipped/deleted: None

### VERIFY: Gate Check

- Command: [gate check command]
- Result: [X passed, 0 failed]
- Test count: [N — matches RED phase count]

### Post-Gate

- [x] No SPEC_DEVIATION (or markers added)
- [x] No unnecessary changes made
- [x] Matches existing patterns

**Status**: ✅ Complete | ❌ Blocked | ⚠️ Partial

---

Tips

• One task at a time — Focus prevents errors
• Tools matter — Wrong MCP = wrong approach
• Reuses save tokens — Copy patterns, don't reinvent
• Check before commit — Verify all criteria, then commit
• Stay surgical — Touch only what's necessary
• Commit per task — Clean git history enables bisect and rollback
• Never "while I'm here" — Scope creep during implementation is the #1 quality killer
• Learn from mistakes — If something goes wrong, add a Lesson Learned to STATE.md

Project Initialization

Trigger: "Initialize project", "Setup project", "Start new project"

Process

Extract project vision via iterative Q&A (max 3-5 questions per message):

Essential questions:

1. What are you building? 2. Who is it for and what problem does it solve? 3. What tech stack are you using? (if known) 4. What's in scope for v1? What's explicitly excluded? 5. Critical constraints? (timeline, technical, resources)

Stop when: Clear understanding of vision, goals, and boundaries.

Output: .specs/project/PROJECT.md

Structure:

# [Project Name]

**Vision:** [1-2 sentence description]
**For:** [target users]
**Solves:** [core problem being addressed]

## Goals

- [Primary goal with measurable success metric]
- [Secondary goal with measurable success metric]

## Tech Stack

**Core:**

- Framework: [name + version]
- Language: [name + version]
- Database: [name]

**Key dependencies:** [3-5 critical libraries/frameworks]

## Scope

**v1 includes:**

- [Core capability 1]
- [Core capability 2]
- [Core capability 3]

**Explicitly out of scope:**

- [What is NOT being built]
- [What is NOT being built]

## Constraints

- Timeline: [if applicable]
- Technical: [if applicable]
- Resources: [if applicable]

Size limit: 2,000 tokens (~1,200 words)

Validation:

• Vision clear in 1-2 sentences?
• Goals have measurable outcomes?
• Scope boundaries explicit?

Quick Mode

Goal: Execute small, ad-hoc tasks with the same quality principles but without full pipeline ceremony.

Trigger: "Quick fix", "Quick task", "Small change", "Bug fix", "Just do X"

When to Use

Rule of thumb: If you can describe it in one sentence AND it touches ≤3 files, it's a quick task.

Process

1. Describe the Task

User provides a clear, one-sentence description. If vague, ask for specifics:

• ❌ "Fix the login" → Ask: "What's broken? What should happen instead?"
• ✅ "Fix: login button returns 401 because token refresh skips expired check"

2. Pre-Implementation Check

Before writing code, state:

Quick Task: [description]
Files: [list ONLY files to touch]
Approach: [one sentence]
Verify: [how to prove it works]

Get user approval before proceeding. If the pre-implementation check reveals the task is bigger than expected (>3 files, unclear dependencies, design decisions needed), recommend the full pipeline instead.

3. Implement

Follow coding-principles.md:

• Simplest code that works
• Touch ONLY listed files
• No scope creep — fix the thing, nothing else

4. Verify

Run verification from step 2. Mark done only after verification passes.

5. Commit

Atomic commit following Conventional Commits 1.0.0:

<type>(<scope>): <description>

Use imperative mood, lowercase, no period. See implement.md for full types table.

Examples:

• fix(auth): prevent 401 on token refresh
• feat(settings): add dark mode toggle
• chore(deps): update eslint to v9

6. Track

Update .specs/project/STATE.md with quick task record (see state-management.md Quick Tasks section).

---

Structure

Quick tasks live separately from planned features:

.specs/
└── quick/
    └── NNN-slug/
        ├── TASK.md       # Description + verification
        └── SUMMARY.md    # What was done + commit

TASK.md template:

# Quick Task NNN: [Title]

**Date:** [date]
**Status:** Done | In Progress | Blocked

## Description

[One sentence: what and why]

## Files Changed

- `src/path/to/file.ts` — [what changed]
- `src/path/to/other.ts` — [what changed]

## Verification

- [ ] [How to verify it works]
- [ ] [Expected behavior after fix]

## Commit

`[hash]` — [commit message]

---

Guardrails

• Max 3 files — If more, use full pipeline
• Max 1 hour — If longer, scope is wrong
• No design decisions — If you're choosing between approaches, use full pipeline
• No new dependencies — Adding packages needs full pipeline review
• Track everything — Even quick tasks get commits and STATE.md entries

---

Tips

• Quick ≠ sloppy — Same coding principles apply, just less ceremony
• When in doubt, go full — Better to over-plan than to ship broken code
• Quick tasks compound — If you're doing 5+ quick tasks for the same area, it's a feature that needs planning
• Verify before marking done — The whole point is quality, even for small tasks

Roadmap Creation

Trigger: "Create roadmap", "Plan features", "Map project phases"

Process

Based on PROJECT.md, decompose vision into:

• Milestones (shippable increments)
• Features (user-facing capabilities)
• Status tracking (planned/in-progress/complete)

Output: .specs/project/ROADMAP.md

Structure:

# Roadmap

**Current Milestone:** [milestone name]
**Status:** Planning | In Progress | Complete

---

## [Milestone 1 Name]

**Goal:** [What makes this milestone shippable]
**Target:** [Date or completion criteria]

### Features

**[Feature Name]** - STATUS

- [Capability 1]
- [Capability 2]
- [Capability 3]

**[Feature Name]** - STATUS

- [Capability 1]
- [Capability 2]

---

## [Milestone 2 Name]

**Goal:** [What this milestone adds]

### Features

**[Feature Name]** - PLANNED
**[Feature Name]** - PLANNED

---

## Future Considerations

- [Potential future capability]
- [Potential future capability]

Status values:

• PLANNED: Not started
• IN PROGRESS: Currently implementing
• COMPLETE: Shipped and verified

Size limit: 3,000 tokens (~1,800 words)

Update strategy:

• Mark features PLANNED → IN PROGRESS when starting
• Mark IN PROGRESS → COMPLETE when verified
• Add new milestones as project evolves

Validation:

• Each milestone has clear shippable outcome?
• Features are user-facing capabilities?
• Status reflects current reality?

Session Handoff

Pause Work

Trigger: "Pause work", "End session", "Create handoff"

Purpose: Checkpoint current state for resumption.

Output: .specs/HANDOFF.md (overwrites previous)

Size target: ~500 tokens

Structure:

# Handoff

**Date:** [ISO timestamp]
**Feature:** [feature name]
**Task:** [task identifier] - [brief status]

## Completed ✓

- [Completed work item]
- [Completed work item]

## In Progress

- [Current work] ([percentage or status])
- Specific location: [file:line if applicable]

## Pending

- [Next immediate step]
- [Following step]

## Blockers

- [Blocker description] - [impact]

## Context

- Branch: [git branch if applicable]
- Uncommitted: [files with changes]
- Related decisions: [STATE.md references if applicable]

Instructions:

• Focus on actionable information for resumption
• Include specific file/line references where relevant
• Note uncommitted changes explicitly
• Reference related STATE.md entries if applicable

Resume Work

Trigger: "Resume work", "Continue", "Load handoff"

Process:

1. Load HANDOFF.md 2. Load STATE.md for context 3. Summarize current position 4. Propose next action

Response pattern:

• "Resuming [feature] at [task]"
• "Completed: [summary]"
• "Next: [immediate action]"
• "Continue with [specific step]?"

Specify

Goal: Capture WHAT to build with testable, traceable requirements.

If the feature has ambiguous gray areas (multiple valid approaches for user-facing behavior), the agent will automatically trigger the discuss gray areas process within this phase. For clear, well-defined features, it goes straight to the next phase.

Process

1. Clarify Requirements

You are a thinking partner, not an interviewer. Start open — let the user dump their mental model. Follow the energy: whatever they emphasize, dig into that.

Ask conversationally (not as a checklist):

• "What problem are you solving?"
• "Who is the user and what's their pain?"
• "What does success look like?"

If needed:

• "What are the constraints (time, tech, resources)?"
• "What is explicitly out of scope?"

Challenge vagueness. Never accept fuzzy answers. "Good" means what? "Users" means who? "Simple" means how? Make the abstract concrete: "Walk me through using this." "What does that actually look like?"

Know when to stop. When you understand what they're building, why, who it's for, and what done looks like — offer to proceed.

2. Capture User Stories with Priorities

P1 = MVP (must ship), P2 (should have), P3 (nice to have)

Each story MUST be independently testable - you can implement and demo just that story.

3. Write Acceptance Criteria

Use WHEN/THEN/SHALL format - it's precise and testable:

• WHEN [event/action] THEN [system] SHALL [response/behavior]

---

Template: .specs/[feature]/spec.md

# [Feature Name] Specification

## Problem Statement

[Describe the problem in 2-3 sentences. What pain point are we solving? Why now?]

## Goals

- [ ] [Primary goal with measurable outcome]
- [ ] [Secondary goal with measurable outcome]

## Out of Scope

Explicitly excluded. Documented to prevent scope creep.

| Feature     | Reason         |
| ----------- | -------------- |
| [Feature X] | [Why excluded] |
| [Feature Y] | [Why excluded] |

---

## User Stories

### P1: [Story Title] ⭐ MVP

**User Story**: As a [role], I want [capability] so that [benefit].

**Why P1**: [Why this is critical for MVP]

**Acceptance Criteria**:

1. WHEN [user action/event] THEN system SHALL [expected behavior]
2. WHEN [user action/event] THEN system SHALL [expected behavior]
3. WHEN [edge case] THEN system SHALL [graceful handling]

**Independent Test**: [How to verify this story works alone - e.g., "Can demo by doing X and seeing Y"]

---

### P2: [Story Title]

**User Story**: As a [role], I want [capability] so that [benefit].

**Why P2**: [Why this isn't MVP but important]

**Acceptance Criteria**:

1. WHEN [event] THEN system SHALL [behavior]
2. WHEN [event] THEN system SHALL [behavior]

**Independent Test**: [How to verify]

---

### P3: [Story Title]

**User Story**: As a [role], I want [capability] so that [benefit].

**Why P3**: [Why this is nice-to-have]

**Acceptance Criteria**:

1. WHEN [event] THEN system SHALL [behavior]

---

## Edge Cases

- WHEN [boundary condition] THEN system SHALL [behavior]
- WHEN [error scenario] THEN system SHALL [graceful handling]
- WHEN [unexpected input] THEN system SHALL [validation response]

---

## Requirement Traceability

Each requirement gets a unique ID for tracking across design, tasks, and validation.

| Requirement ID | Story       | Phase  | Status  |
| -------------- | ----------- | ------ | ------- |
| [FEAT]-01      | P1: [Story] | Design | Pending |
| [FEAT]-02      | P1: [Story] | Design | Pending |
| [FEAT]-03      | P2: [Story] | -      | Pending |

**ID format:** `[CATEGORY]-[NUMBER]` (e.g., `AUTH-01`, `CART-03`, `NOTIF-02`)

**Status values:** Pending → In Design → In Tasks → Implementing → Verified

**Coverage:** X total, Y mapped to tasks, Z unmapped ⚠️

---

## Success Criteria

How we know the feature is successful:

- [ ] [Measurable outcome - e.g., "User can complete X in < 2 minutes"]
- [ ] [Measurable outcome - e.g., "Zero errors in Y scenario"]

---

Tips

• P1 = Vertical Slice — A complete, demo-able feature, not just backend or frontend
• WHEN/THEN is code — If you can't write it as a test, rewrite it
• Requirement IDs are mandatory — Every story maps to trackable IDs
• Edge cases matter — What breaks? What's empty? What's huge?
• Out of Scope prevents creep — If it's not here, it doesn't get built
• Confirm before Discuss — User must approve spec before moving to discuss phase

State Management

Purpose: Persistent memory across sessions - decisions, blockers, learnings.

Structure

Output: .specs/project/STATE.md

# State

**Last Updated:** [ISO timestamp]
**Current Work:** [Feature name] - [Task identifier]

---

## Recent Decisions (Last 60 days)

### AD-[NNN]: [Decision title] ([date])

**Decision:** [What was decided]
**Reason:** [Why this choice]
**Trade-off:** [What was sacrificed]
**Impact:** [How this affects implementation]

### AD-[NNN]: [Decision title] ([date])

[Same structure]

---

## Active Blockers

### B-[NNN]: [Blocker description]

**Discovered:** [Date]
**Impact:** [Severity and scope]
**Workaround:** [Temporary solution if available]
**Resolution:** [Path to permanent fix]

---

## Lessons Learned

### L-[NNN]: [Learning description]

**Context:** [Situation that occurred]
**Problem:** [What went wrong]
**Solution:** [How it was resolved]
**Prevents:** [What this knowledge prevents in future]

---

## Quick Tasks Completed

| #   | Description              | Date   | Commit | Status  |
| --- | ------------------------ | ------ | ------ | ------- |
| 001 | [Quick task description] | [date] | [hash] | ✅ Done |

---

## Deferred Ideas

Ideas captured during work that belong in future features or phases. Prevents scope creep while preserving good ideas.

- [ ] [Idea description] — Captured during: [feature/phase]
- [ ] [Idea description] — Captured during: [feature/phase]

---

## Todos

Capture in-progress thoughts and action items that don't fit in active tasks.

- [ ] [TODO: action item]
- [ ] [TODO: action item]

When to Update

Size Management (Hybrid Strategy)

Zones:

• 🟢 <7k tokens: No action
• 🟡 7-10k tokens: Footer note "STATE.md at [X]k. Cleanup recommended."
• 🔴 >10k tokens: Active prompt "STATE.md critical ([X]k). Cleanup now?"

Cleanup process:

• Move decisions >60 days to STATE-ARCHIVE.md
• Keep only active blockers
• Preserve recent learnings (<60 days)

Validation:

• Decisions have clear rationale?
• Blockers include resolution path?
• Learnings are actionable?

---

Preferences

Track user-facing behavioral state in STATE.md:

## Preferences

**Model Guidance Shown:** [ISO date or "never"]

Update when:

This prevents repetitive suggestions while maintaining natural, helpful behavior.

Tasks

Goal: Break into GRANULAR, ATOMIC tasks. Clear dependencies. Right tools. Parallel execution plan.

Skip this phase when: There are ≤3 obvious steps. In that case, tasks are implicit — go straight to Execute and list them inline in your implementation plan.

Why Granular Tasks?

Benefits of granular:

• Agents don't err - Single focus, no ambiguity
• Easy to test - Each task = one verifiable outcome
• Parallelizable - Independent tasks run simultaneously
• Errors isolated - One failure doesn't block everything

Rule: One task = ONE of these:

• One component
• One function
• One API endpoint
• One file change

---

Process

1. Review Design

Read .specs/[feature]/design.md before creating tasks.

1.5. Load Test Coverage Matrix

Read .specs/codebase/TESTING.md (if it exists) before creating tasks. The Test Coverage Matrix and Parallelism Assessment drive two critical decisions:

Co-located tests: Every task that creates or modifies a code layer with a required test type MUST include writing/updating those tests in the same task. Tests are NOT separate tasks.

Parallelism flags: Cross-reference the Parallelism Assessment when marking tasks [P]:

• If a task's required test type is marked "Parallel-Safe: No" → strip [P] flag
• If a task's required test type is marked "Parallel-Safe: Yes" → [P] is allowed
• If a task has no tests → [P] depends only on code dependencies

If TESTING.md does not exist (greenfield project), ask the user what test types and commands the project will use before creating tasks.

2. Break Into Atomic Tasks

Task = ONE deliverable. Examples:

• ✅ "Create UserService interface" (one file, one concept)
• ❌ "Implement user management" (too vague, multiple files)

3. Define Dependencies

What MUST be done before this task can start?

4. Create Execution Plan

Group tasks into phases. Identify what can run in parallel.

5. Validate Before Presenting (MANDATORY)

Before showing tasks to the user, run ALL three pre-approval checks. These are NOT optional — they are gates. If any check fails, restructure the tasks and re-run until all pass.

Check 1: Task Granularity — verify each task is atomic (see Granularity Check section).

Check 2: Diagram-Definition Cross-Check — verify the execution diagram matches every task's Depends on field (see Diagram-Definition Cross-Check section). Build the cross-check table and include it in the output.

Check 3: Test Co-location Validation — verify every task's Tests field matches the TESTING.md coverage matrix (see Test Co-location Validation section). Build the validation table and include it in the output.

Output both tables with the tasks so the user can see the validation results. Any ❌ means you MUST restructure before presenting — do not show failing tasks to the user and ask them to approve.

6. ASK About MCPs and Skills

CRITICAL: Before execution, ask the user:

"For each task, which tools should I use?"

>

Available MCPs: [list from project or user]

Available Skills: [list from project or user]

---

Template: .specs/[feature]/tasks.md

# [Feature] Tasks

**Design**: `.specs/[feature]/design.md`
**Status**: Draft | Approved | In Progress | Done

---

## Execution Plan

### Phase 1: Foundation (Sequential)

Tasks that must be done first, in order.

T1 → T2 → T3

### Phase 2: Core Implementation (Parallel OK)
After foundation, these can run in parallel.

┌→ T4 ─┐

T3 ──┼→ T5 ─┼──→ T8 └→ T6 ─┘ T7 ──────→

### Phase 3: Integration (Sequential)
Bringing it all together.

T8 → T9

---

Task Breakdown

T1: [Create X Interface]

What: [One sentence: exact deliverable] Where: src/path/to/file.ts Depends on: None Reuses: src/existing/BaseInterface.ts Requirement: [FEAT]-01

Tools:

• MCP: filesystem (or NONE)
• Skill: NONE

Done when:

• [ ] Interface defined with all methods from design
• [ ] Types exported correctly
• [ ] No TypeScript errors

Tests: [unit/e2e/integration/none — from coverage matrix] Gate: [quick/full/build — from gate check commands]

---

T2: [Implement Y Service] [P]

What: [Exact deliverable] Where: src/services/YService.ts Depends on: T1 Reuses: src/services/BaseService.ts patterns

Tools:

• MCP: filesystem, context7
• Skill: NONE

Done when:

• [ ] Implements interface from T1
• [ ] Handles error cases from design
• [ ] Gate check passes: [quick gate command from TESTING.md]
• [ ] Test count: [N] tests pass (no silent deletions)

Tests: unit Gate: quick

---

T3: [Create Z Component] [P]

What: [Exact deliverable] Where: src/components/ZComponent.tsx Depends on: T1 Reuses: src/components/BaseComponent.tsx

Tools:

• MCP: filesystem
• Skill: NONE

Done when:

• [ ] Component renders correctly
• [ ] Handles props from interface
• [ ] Follows existing component patterns
• [ ] Gate check passes: [quick gate command from TESTING.md]
• [ ] Test count: [N] tests pass (no silent deletions)

Tests: unit Gate: quick

---

T4: [Add A Feature to Y]

What: [Exact deliverable] Where: src/services/YService.ts (modify) Depends on: T2, T3 Reuses: Existing service patterns

Tools:

• MCP: filesystem, github
• Skill: api-design

Done when:

• [ ] Feature works per acceptance criteria
• [ ] Gate check passes: [full gate command from TESTING.md]
• [ ] Test count: [N] tests pass (no silent deletions)

Tests: integration Gate: full

Commit: feat([scope]): [description]

---

Parallel Execution Map

Visual representation of what can run simultaneously:

Phase 1 (Sequential):
  T1 ──→ T2 ──→ T3

Phase 2 (Parallel):
  T3 complete, then:
    ├── T4 [P]
    ├── T5 [P]  } Can run simultaneously
    └── T6 [P]

Phase 3 (Sequential):
  T4, T5, T6 complete, then:
    T7 ──→ T8

Parallelism constraint: A task marked [P] must have ALL of these:

• No unfinished dependencies
• Required test type is parallel-safe (per TESTING.md Parallelism Assessment)
• No shared mutable state with other [P] tasks in the same phase

If a task's tests are NOT parallel-safe, it MUST run sequentially even if its implementation code has no dependencies. The test execution is the bottleneck.

How parallel execution works:

Tasks marked [P] are executed via sub-agents — one sub-agent per task, launched concurrently. Each sub-agent receives only its task definition and relevant project context (see Sub-Agent Delegation in SKILL.md). The orchestrating agent waits for all sub-agents in a phase to complete before advancing to the next phase.

Sequential tasks (no [P]) are also delegated to sub-agents, but one at a time. This keeps implementation artifacts (file reads, test output, gate check logs) out of the main context.

The orchestrating agent's role during Execute: 1. Pick the next task(s) to execute 2. Provide each sub-agent with its task definition + context 3. Monitor sub-agent completion 4. Update tasks.md with results 5. Decide whether to proceed, fix, or escalate

---

Task Granularity Check

Before approving tasks, verify they are granular enough:

Granularity check:

• ✅ 1 component / 1 function / 1 endpoint = Good
• ⚠️ 2-3 related things in same file = OK if cohesive
• ❌ Multiple components or files = MUST split

---

Diagram-Definition Cross-Check

Before approving tasks, verify the execution diagram is consistent with the task definitions. These are independent artifacts that can drift — the diagram is drawn for visual clarity while task bodies are written for precision. Both must agree.

For each task, check:

Rules:

• Every Depends on in a task body must have a corresponding arrow in the diagram.
• Every arrow in the diagram must correspond to a Depends on in the target task's body.
• Tasks shown as parallel ([P]) in the diagram must not depend on each other.
• If a task depends on another task in the same parallel phase, they are NOT parallel — fix the diagram or remove the [P] flag.

---

Test Co-location Validation

Before approving tasks, verify EVERY task's Tests field is consistent with the TESTING.md Test Coverage Matrix. This is a hard gate — tasks that fail this check MUST be fixed.

For each task, check: does the task create or modify a code layer that has a required test type in the coverage matrix? If yes, the task's Tests field MUST match.

Rules:

• "Tested in another task" is NOT a valid justification for Tests: none. That is test deferral — the exact anti-pattern this validation prevents.
• Tests: none is only valid when the coverage matrix says "none" for that code layer.
• If a task creates MULTIPLE code layers (e.g., service + controller), use the HIGHEST test type required by any of them.
• Any ❌ VIOLATION → restructure the task to include its required tests before proceeding.

Resolving compilation dependencies:

When a task creates code that can't be tested until a later task completes (e.g., a controller that needs module wiring before its e2e tests can run), do NOT defer the tests to a separate task. Instead, restructure:

1. Merge forward: Move the untestable task's tests into the earliest task where they become runnable (e.g., the wiring task includes wiring + e2e tests for the controller it enables). 2. Merge backward: Absorb the blocking dependency into the current task so it becomes self-testable (e.g., controller task includes its own module registration).

Pick whichever option keeps tasks atomic and cohesive. The goal: no task produces unverified code. If code can't be tested in the task that creates it, the task boundaries are wrong.

---

Tips

• [P] = Parallel OK — Mark tasks that can run simultaneously
• Reuses = Token saver — Always reference existing code
• Tools per task — MCPs and Skills prevent wrong approaches
• Dependencies are gates — Clear what blocks what
• Done when = Testable — If you can't verify it, rewrite it
• Requirement ID = Traceable — Every task traces back to a spec requirement
• One commit per task — Plan the commit message format in advance

---

Task Verification Standards

Every task MUST include:

Done when checklist:

• Specific, testable outcomes
• Pass/fail criteria
• The specific test command from the Gate Check Commands table
• Expected pass count (prevents silent test deletion)

Verify section:

• Commands to prove functionality
• Expected outputs
• Success indicators

Structure:

### T1: [Task name]

**What:** [Deliverable]
**Where:** [File path]
**Tests**: [unit/e2e/integration/none]
**Gate**: [quick/full/build]

**Done when:**

- [ ] [Specific outcome]
- [ ] [Specific outcome]
- [ ] Gate check passes: `[command from Gate Check Commands]`
- [ ] Test count: [N] tests pass (no silent deletions)

**Verify:**
[Command to prove it works]
[Expected output/behavior]

Quality check:

• Can task be verified without human judgment?
• Is success criteria binary (pass/fail)?
• Can verification be automated?

Execute: Validate & Verify

Goal: Verify implementation meets spec AND coding principles. This is NOT a separate phase — verification is part of every task's completion within Execute.

Two levels of verification:

1. Per-task verification (always): After implementing each task, verify its "Done when" criteria before committing. This is mandatory and automatic.

2. Feature-level validation (on completion or on demand): After all tasks for a feature (or priority group) are done, run a comprehensive validation. Includes acceptance criteria check, code quality review, and optionally interactive UAT.

Interactive UAT is triggered when: The feature has complex user-facing behavior where human judgment matters (UI flows, interaction patterns, visual design). For backend-only or infrastructure work, automated checks are sufficient.

Trigger for explicit validation: "Validate", "verify work", "UAT", "test with me", "walk me through it"

---

Process

1. Check Completed Tasks

Go through tasks.md:

• [ ] All tasks marked done?
• [ ] Any blocked or partial?

2. Verify Acceptance Criteria

For each user story in spec.md:

### P1: [Story Title]

**Acceptance Criteria**:

1. WHEN [X] THEN [Y] → [PASS/FAIL]
2. WHEN [X] THEN [Y] → [PASS/FAIL]

3. Check Edge Cases

From spec.md edge cases:

• [ ] [Edge case 1] handled correctly
• [ ] [Edge case 2] handled correctly

4. Run Build-Level Gate Check (MANDATORY)

Run the Build-level gate check from TESTING.md. This is NOT optional.

If TESTING.md does not exist (greenfield project), use the gate command agreed upon with the user during the Tasks phase.

1. Run: [build gate command from TESTING.md, or the command agreed during planning] 2. Non-zero exit code = STOP. Do not proceed to Code Quality Check. 3. Record results:

• Total test count: [N]
• Passed: [N]
• Failed: [list]
• Skipped: [list — each skip must be justified]

Test Integrity Check:

• Compare current test count against the count before this feature was implemented
• If test count DECREASED: investigate why. Tests should only be deleted with explicit justification.
• If assertions were weakened (less specific than before): flag as potential regression

5. Code Quality Check (MANDATORY)

For each changed file, verify against coding-principles.md:

❌ Any "No"? → Fix before marking complete.

6. Interactive UAT (if user-facing feature)

For each testable deliverable, present one test at a time:

Test [N]: [Test Name]

Expected: [What should happen — specific and observable]

→ Does this work? Describe what you see.

Wait for user response:

Severity inference (never ask the user for severity):

7. Generate Fix Plans (if issues found)

For each issue found during UAT:

1. Diagnose — Analyze the codebase to find root cause 2. Create fix task — Write a task definition with:

• What: The specific fix
• Where: File paths
• Verify: How to prove the fix works
• Done when: Acceptance criteria for the fix

3. Present fix plan — Show all fix tasks to user for approval

Fix tasks follow the same format as regular tasks and can be executed with the implement phase.

Guardrail: Maximum 3 diagnostic iterations per issue. If root cause isn't found after 3 attempts, flag for human investigation.

8. Report

---

Validation Report Template

# [Feature] Validation

**Date**: [YYYY-MM-DD]
**Spec**: `.specs/features/[feature]/spec.md`

---

## Task Completion

| Task | Status     | Notes   |
| ---- | ---------- | ------- |
| T1   | ✅ Done    | -       |
| T2   | ✅ Done    | -       |
| T3   | ⚠️ Partial | [Issue] |

---

## User Story Validation

### P1: [Story Title] ⭐ MVP

| Criterion     | Result  |
| ------------- | ------- |
| WHEN X THEN Y | ✅ PASS |
| WHEN A THEN B | ✅ PASS |

**Status**: ✅ P1 Complete

### P2: [Story Title]

| Criterion     | Result             |
| ------------- | ------------------ |
| WHEN X THEN Y | ❌ FAIL - [reason] |

**Status**: ⚠️ P2 Issues

---

## Interactive UAT Results (if performed)

| #   | Test        | Result   | Details                                         |
| --- | ----------- | -------- | ----------------------------------------------- |
| 1   | [Test name] | ✅ Pass  | -                                               |
| 2   | [Test name] | ❌ Issue | [Verbatim user response] — Severity: [inferred] |
| 3   | [Test name] | ⏭️ Skip  | [Reason]                                        |

---

## Code Quality

| Principle        | Status |
| ---------------- | ------ |
| Minimum code     | ✅     |
| Surgical changes | ✅     |
| No scope creep   | ✅     |
| Matches patterns | ✅     |

---

## Edge Cases

- [x] Edge case 1: Handled correctly
- [ ] Edge case 2: NOT handled - needs fix

---

## Tests

- **Gate command**: [full command]
- **Result**: [X] passed, [Y] failed, [Z] skipped
- **Test count before feature**: [N]
- **Test count after feature**: [M]
- **Delta**: [+(M - N) new tests]
- **Skipped tests**: [list with justification for each]
- **Failures**: [list with details]

---

## Fix Plans (if issues found)

### Fix 1: [Issue description]

- **Root cause**: [What's actually wrong]
- **Fix task**: [Task definition]
- **Priority**: [Blocker/Major/Minor/Cosmetic]

---

## Requirement Traceability Update

Update spec.md requirement statuses:

| Requirement | Previous Status | New Status   |
| ----------- | --------------- | ------------ |
| [FEAT]-01   | Implementing    | ✅ Verified  |
| [FEAT]-02   | Implementing    | ❌ Needs Fix |

---

## Summary

**Overall**: ✅ Ready | ⚠️ Issues | ❌ Not Ready

**What works**: [List]

**Issues found**: [Issue 1: How to fix]

**Next steps**: [Action]

---

Tips

• P1 first — MVP must work before P2/P3
• WHEN/THEN = Test — Each criterion is a test case
• Be specific — "Doesn't work" isn't helpful
• Recommend fixes — Don't just report problems, create fix tasks
• Quality check is mandatory — Not optional
• Infer severity — Never ask the user "how bad is this?"
• Max 3 diagnostic iterations — Prevents infinite investigation loops
• Update traceability — Every verified requirement updates spec.md status