Specmint Tdd

Spec Mint TDD

Turn ephemeral plans into structured, persistent specs built through deep research and iterative interviews — with strict test-driven development at every step. Every task starts with a failing test, production code exists only to make tests pass, and refactoring happens under green. Tests use testcontainers for real services, mock only at boundaries, and make no external network calls. Specs have phases, tasks, acceptance criteria, a registry, resume context, a decision log, a TDD log, and a deviations log. They live in .specs/ at the project root and work with any AI coding tool that can read markdown.

Whether .specs/ is committed is repository policy. Respect .gitignore and the user's preference for tracked vs local-only spec state.

Critical Invariants

1. Single-file policy: Keep this workflow in one SKILL.md file.
2. Canonical paths:

• Registry: .specs/registry.md
• Per-spec files: .specs//SPEC.md, .specs//research-*.md,

.specs//interview-*.md

1. Authority rule: SPEC.md frontmatter is authoritative. Registry is a

denormalized index for quick lookup.

1. Active-spec rule: Target exactly one active spec at a time.
2. Parser policy: Use best-effort parsing with clear warnings and repair

guidance instead of hard failure on malformed rows.

1. TDD invariant: No production code without a failing test. The implement

workflow enforces red-green-refactor at every task. Tests are executed via the actual test runner, not assumed to pass. This is sacred — see "Tests Are Sacred" and "Blocking Rule" in the implement section.

1. Progress tracking is sacred: After completing any task, immediately

update SPEC.md (checkbox, ← current marker, phase marker, TDD log) AND registry.md (progress count, date). Then re-read both files to verify the edits landed correctly. Never move to the next task without updating both files. Never end a session with the registry out of sync with SPEC.md. This is non-negotiable — if you do nothing else, do this.

Session Start

If active-spec context was injected by host tooling, use it directly instead of reading files. Otherwise, fall back to reading files manually:

1. Read .specs/registry.md to check for a spec with active status
2. If one exists, briefly mention it:

"You have an active spec: User Auth System (5/12 tasks, Phase 2). Say 'resume' to pick up where you left off."

1. Don't force it — the user might want to do something else first

Deterministic Edge Cases (Best-Effort)

| Situation | Required behavior | |-----------|-------------------| | .specs/registry.md missing | If .specs/ exists, report "No registry yet" and offer to initialize it. If .specs/ is missing, report "No specs yet" and continue normally. | | Malformed registry row | Skip malformed row, emit warning with row text, continue parsing remaining rows. | | Multiple active rows | Warn user. Pick the row with the newest Updated date (or first active row if dates are unavailable) for this run. On next write, normalize to a single active spec. | | Registry row exists but .specs//SPEC.md missing | Warn and continue. Keep row visible in list/status with (SPEC.md missing). | | Registry and SPEC conflict | Trust SPEC.md, then repair registry values on next write. | | No active spec | List available specs and ask which to activate or resume. |

Working on a Spec

Resuming

When the user says "resume", "what was I working on", or similar:

1. Read .specs/registry.md — find the spec with active status. If none, list specs and ask which to resume
2. Load .specs//SPEC.md
3. Parse progress:

• Count completed [x] vs total tasks per phase
• Find current phase (first [in-progress] phase)
• Find current task (← current marker, or first unchecked in current phase)

1. Read the Resume Context section
2. Present a compact summary:

`` Resuming: User Auth System Progress: 5/12 tasks (Phase 2: OAuth Integration) Current: [TEST-AUTH-07] Write OAuth callback tests TDD Phase: RED (next: write test, run, confirm fail) Last Cycle: [IMPL-AUTH-06] GREEN — 4/4 pass Context: Finished Google OAuth (TEST-05 red, IMPL-06 green+refactored). Starting GitHub OAuth callback tests next. Next file: tests/auth/test_oauth_github.py ``

1. Begin working on the current task — don't wait for permission

Implementing a Spec (TDD)

When the user says "implement the spec", "implement phase N", "implement all phases", or similar:

Scope Detection

Parse the user's request to determine scope:

• "implement the spec" or "implement" — Start from the current task

(the ← current marker) and work forward

• "implement phase N" or "implement phase " — Implement all

tasks in that specific phase

• "implement all phases" or "implement everything" — Implement all

remaining unchecked tasks across all phases, in order

TDD Implementation Flow

1. Read .specs/registry.md to find the active spec
2. Load .specs//SPEC.md and parse phases/tasks
3. Identify the target tasks based on scope
4. For each task in order, determine if it is a TEST or IMPL task by its

task code prefix (TEST- vs IMPL-)

1. Tasks within a phase alternate: TEST then IMPL, TEST then IMPL. Each

TEST-IMPL pair is one red-green-refactor cycle.

For each TEST-IMPL pair (one red-green-refactor cycle):

RED — TEST task:

1. Mark the TEST task with ← current
2. Write the test file at the path specified in the task, with the assertions

and test descriptions listed

1. GATE: RUN the tests via Bash. Do not proceed without running them.
2. GATE: Confirm tests FAIL. If all tests fail — good, this is RED.
3. If tests pass unexpectedly: STOP. Report the anomaly to the user.

Do not proceed. Either the feature already exists or the tests are wrong.

1. Log the red output in the TDD Log using this exact format:

| [TEST-XX-NN] | : N tests, N failed — | — | — |

1. Check off the task: - [ ] -> - [x], remove ← current

GREEN — IMPL task:

1. Mark the IMPL task with ← current
2. Read the test file from the preceding TEST task — understand exactly what

the tests expect

1. Write the minimum production code to make the tests pass. Only what the

tests require. Nothing more.

1. GATE: RUN the tests via Bash. Do not proceed without running them.
2. GATE: Confirm tests PASS. If any test fails, fix the production code

and run again. Repeat until green. Do not modify tests to make them pass (see Tests Are Sacred below).

1. Log the green output in the TDD Log:

| [IMPL-XX-NN] | — | : N passed, 0 failed | — |

REFACTOR — still on the IMPL task:

1. Clean up the production code — remove duplication, improve naming, extract

helpers

1. GATE: RUN tests again via Bash. Confirm they are still green.
2. If refactoring broke tests: undo the refactoring, try a different approach.
3. Log refactoring in the TDD Log Refactor column (or "none")
4. Check off the IMPL task: - [ ] -> - [x], remove ← current
5. Update progress and date in .specs/registry.md

Then move to the next TEST-IMPL pair and repeat.

Self-Check Before Every Task

Before starting any task, pause and verify:

• [ ] Am I about to write production code? → Is there a failing test for it?
• [ ] Am I about to skip running tests? → Run them. Always.
• [ ] Am I about to modify a test to make it pass? → Stop. Fix the code instead.
• [ ] Did I log the last task's output in the TDD Log? → Do it now.
• [ ] Did I update the checkbox and ← current marker? → Do it now.

If any answer is wrong, correct it before proceeding.

Violation Examples

These are common TDD violations. If you recognize yourself doing any of these, STOP immediately and correct course:

| Violation | What it looks like | Correct action | |-----------|-------------------|---------------| | Writing code before test | "I'll implement the handler first, then test it" | Write the test first. Watch it fail. Then implement. | | Skipping test execution | "The tests would pass since I wrote the correct code" | Run the tests via Bash. Read the actual output. | | Modifying tests to pass | "I'll adjust the assertion to match what the code returns" | The test is the spec. Fix the production code to match. | | Batching tests | "I'll write all 3 tests, then implement all 3" | Write one test. Implement. Write the next test. Implement. | | Skipping refactor | "The code is fine, moving to the next test" | Review the code. Decide consciously. Log "none" if no changes. | | Forgetting TDD Log | "I'll update the log later" | Update it now, after each task. It's the audit trail. |

Tests Are Sacred

Tests define expected behavior. They are the specification in code form. During the GREEN phase, when tests fail:

• Fix the production code, not the tests
• The only time you modify a test is when it has an actual bug (wrong import,

syntax error, broken test setup) — not when the assertion doesn't match what your code returns

• If a test expects behavior X and your code does behavior Y, your code is

wrong — make it do X

• If you believe the test expectation is genuinely incorrect (e.g., the spec

changed, the user gave new requirements), STOP and ask the user before modifying the test. Do not silently change test expectations.

Blocking Rule

Each IMPL task is preceded by its TEST task. You cannot start an IMPL task until its TEST task is completed and the tests are confirmed failing. This is enforced per-task. If about to write implementation code before its test exists, STOP and write the test first. Non-negotiable.

Test Execution Rule

Run the actual test command (pytest, vitest, cargo test, go test, dotnet test, etc.) via Bash at every RED, GREEN, and REFACTOR transition. That is 3 runs minimum per TEST-IMPL cycle. Claims like "tests would pass" or "tests should fail" are never acceptable — run them and report the actual output. If the test runner is not available, report the blocker immediately.

Phase Transitions

Phases group by feature, not by test vs implementation. Each phase contains interleaved TEST-IMPL pairs. When all tasks in a phase are done, the phase is [completed] and the next phase becomes [in-progress].

Update Transaction (sacred — never skip steps)

Progress tracking is sacred (see Critical Invariant #7). Stale tracking is the single most common failure mode — it makes resume unreliable and the registry useless.

1. Edit SPEC.md (checkbox, current marker, phase marker, resume context,

TDD log entry).

1. Recompute progress directly from SPEC.md checkboxes.
2. Edit the matching registry row (status, progress, updated date).
3. Verify: Re-read both SPEC.md and registry.md to confirm the

edits are correct. If the registry progress doesn't match the SPEC.md checkbox count, fix it now.

1. If registry update fails, keep SPEC.md as source of truth and emit a

warning with exact repair action for .specs/registry.md.

If you notice you forgot to update after a previous task, stop what you're doing and update now before continuing.

Also:

• If a task is more complex than expected, split it into subtasks
• Update resume context at natural pauses
• Log non-obvious technical decisions to the Decision Log
• If implementation diverges from the spec (errors found, better approach

discovered, assumptions proved wrong), log it in the Deviations section

• Phase review: When all tasks in a phase are done, review before moving

on — re-read the phase's tasks and acceptance criteria, verify each task's implementation matches what was specified, check that the TDD Log has entries for every TEST-IMPL pair, and check for missing edge cases or spec drift. Fix issues before marking the phase complete. Log findings in the Decision Log.

Verification Gate

Before reporting any phase or spec as complete, provide evidence:

• Run the relevant test suite via the project's test runner
• Show the actual command and output — not a summary, not "tests pass"
• If tests fail, fix the issues before claiming completion
• Never use language like "should pass", "probably works", or "seems correct"

Evidence first, then assertions. The TDD log captures per-task evidence; this gate ensures phase and spec completion also have fresh verification.

Completion

When all in-scope tasks are done:

• All tasks in the spec complete:
• Run the full test suite and show the output (verification gate)
• Verify all Acceptance Criteria are checked off. If any remain unchecked,

report which ones and ask the user before marking the spec complete.

• Set all phases to [completed]
• Set spec status to completed in frontmatter and registry
• Update the updated date
• Present a summary of what was implemented, including TDD Log highlights
• Suggest next spec to activate if any are paused

• Only a phase completed (not all tasks):
• Run tests for the phase's scope and show the output (verification gate)
• Report the phase completion and remaining work
• Set the next phase to [in-progress] if applicable
• State whether the next phase is TEST or IMPL

Pausing

When the user says "pause", switches specs, or a session is ending:

1. If there is no active spec, report that there is nothing to pause and stop.
2. Capture what was happening:

• Which task was in progress
• What files were being modified (paths, function names)
• Key decisions made this session
• Any blockers or open questions
• Current TDD phase (RED, GREEN, or REFACTOR)
• Tests written but not yet satisfied by production code
• Last test run output (command and result summary)

1. Write this to the Resume Context section in SPEC.md
2. Update checkboxes to reflect actual progress
3. Move ← current marker to the right task
4. Add any session decisions to the Decision Log
5. Update status: paused in frontmatter
6. Update the updated date

Resume Context is the most important part of pausing. Write it as if briefing a colleague who will pick up tomorrow. Include specific file paths, function names, the exact next step, and the TDD state. Vague context like "was working on auth" is useless — write "implementing verifyRefreshToken() in src/auth/tokens.ts to satisfy TEST-AUTH-03. Tests in tests/auth/test_tokens.py are RED — 2 of 3 assertions failing on refresh rotation. Next step: hook up rotation logic to the /auth/refresh endpoint."

Switching Between Specs

1. Validate the target spec ID first. If missing, list available specs.
2. Confirm .specs//SPEC.md exists. If not, stop with an error.
3. If target is already active, report and stop.
4. Pause the current active spec if one exists (full pause workflow).
5. Set target status to active in frontmatter and in .specs/registry.md.
6. Resume the target spec (full resume workflow).

Embedded Companion Mode

This SKILL.md is embedded by Kluris as the specmint-tdd companion. Do not load plugin sidecar folders or slash-command files; all runtime instructions needed by Kluris users are in this file.

Spec Format

Frontmatter

YAML frontmatter with: id, title, status, created, updated, optional priority and tags.

Status values: active, paused, completed, archived

Phase Markers

[pending], [in-progress], [completed], [blocked]

Task Markers

• - [ ] [TEST-CODE-01] unchecked test task, - [x] [TEST-CODE-01] done
• - [ ] [IMPL-CODE-02] unchecked impl task, - [x] [IMPL-CODE-02] done
• Test task codes: [TEST-PREFIX-NN] — for tasks that write failing tests
• Impl task codes: [IMPL-PREFIX-NN] — for tasks that write production code

to satisfy tests. Each impl task includes -> satisfies [TEST-XX-NN] referencing the test task it makes pass.

• Task

…

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: ngvoicu
• Source: ngvoicu/kluris
• License: MIT
• Homepage: https://kluris.io

Install and usage instructions live in the source repository linked above.