v3.0.0 — Now available

Specs that survive the session

Turn ephemeral AI plans into persistent, resumable specs built through deep research and iterative interviews. Pick up exactly where you left off.

Get started Explore skills
Works with / Claude Code / Codex / Cursor / Windsurf / Cline / Gemini CLI / Devin / Antigravity / and others
Workflow

From idea to implementation, nothing lost along the way

Every spec goes through a disciplined research-first workflow. No guessing, no premature code, no lost context.

01

Deep Research

Exhaustive codebase analysis, library comparisons, documentation lookups, web research. A dedicated subagent reads 15-30 files and runs parallel searches.

02

Interview

Targeted questions informed by research findings. Architecture decisions, scope boundaries, acceptance criteria. Iterates until no ambiguity remains.

03

Write Spec

Structured SPEC.md with phases, tasks, architecture diagrams, library choices, testing strategy, and a decision log. Self-reviewed before presenting.

04

Implement

Task-by-task execution with live progress tracking, verification gates, and phase reviews. Resume context lets you pick up exactly where you stopped.

Skills

Four variants, one workflow

Pick your output format and your methodology. Markdown for friction-free git workflows, or rich HTML with Mermaid diagrams, syntax-highlighted code diffs, and clickable mockup library. With or without strict test-driven development.

MethodologyCore · TDD
FormatMarkdown · HTML
specmint-core
Markdown

Standard · Markdown

The research-first workflow producing SPEC.md files. Plain markdown, git-friendly diffs, opens anywhere.

  • Deep researcher subagent, library comparisons, architecture notes
  • Phase/task tracking, resume context, multi-spec switching
  • Universal skill — natural-language triggers, works in every AI tool
specmint-core-html
HTML

Standard · Rich HTML

Same workflow, SPEC.html output. Mermaid diagrams, PrismJS code diffs, wireframe and hi-fi UI mockups, click-to-zoom.

  • Mermaid flowchart, sequence, ER, state, journey, treemap
  • PrismJS diff-highlight: red/green lines with syntax color
  • Bespoke .wf-* / .ui-* mockup primitives
  • Derived progress — one data-status swap propagates
specmint-tdd TDD
Markdown

Test-Driven · Markdown

Core workflow plus strict red-green-refactor enforcement. Every task starts with a failing test.

  • Alternating TEST-IMPL task pairs per phase
  • Mandatory test runs at RED, GREEN, REFACTOR transitions
  • TDD Log audit trail; Testing Architecture in every spec
  • Language-agnostic testing reference for 6+ languages
specmint-tdd-html TDD
HTML

Test-Driven · Rich HTML

TDD discipline rendered as a 3-lane RGR swimlane log, paired TEST-IMPL task cards, click-to-zoom diagrams.

  • RED / GREEN / REFACTOR swimlane TDD log per cycle
  • Paired TEST-IMPL task cards with satisfies cross-refs
  • Current TDD phase derived live from the in-progress IMPL task
  • Same HTML rendering stack as specmint-core-html
What gets created

Real files, not ephemeral plans

Every spec lives in a .specs/ directory as plain markdown. Browse, edit, diff, commit — they're just files.

--- id: user-auth-system title: User Auth System status: active created: 2026-03-28 updated: 2026-03-30 priority: high --- # User Auth System ## Overview Add JWT-based authentication to the Express.js API. Includes registration, login, token refresh, and protected route middleware. ## Acceptance Criteria - [x] Users can register with email and password - [x] Passwords are hashed with argon2 - [ ] JWT access tokens expire after 15 minutes - [ ] Refresh token rotation on each refresh ## Phase 1: Auth Foundation [completed] - [x] [AUTH-01] Create auth middleware in src/middleware/auth.ts - [x] [AUTH-02] Create User model with Prisma schema - [x] [AUTH-03] Token generation utilities in src/auth/tokens.ts - [x] [AUTH-04] POST /auth/register endpoint ## Phase 2: Login & Refresh [in-progress] - [x] [AUTH-05] POST /auth/login with password verification - [ ] [AUTH-06] POST /auth/refresh with token rotation ← current - [ ] [AUTH-07] POST /auth/logout endpoint ## Resume Context > Implementing token refresh in src/auth/tokens.ts. > The verifyRefreshToken() function needs to check > the stored token hash and rotate on success. > Next: write the /auth/refresh route handler.
--- id: payment-processing title: Payment Processing status: active --- # Payment Processing ## Testing Architecture | Framework | Vitest 2.1 | | Isolation | Testcontainers | | Coverage | c8, target 85% | | Mocking | msw for HTTP only | ## Phase 1: Checkout [in-progress] - [x] [TEST-PAY-01] Write checkout session tests - [x] [IMPL-PAY-02] Implement checkout session → satisfies [TEST-PAY-01] - [ ] [TEST-PAY-03] Write webhook handler tests ← current - [ ] [IMPL-PAY-04] Implement webhook handler → satisfies [TEST-PAY-03] ## TDD Log | Task | Red (failing) | Green (passing) | Refactor | |----------------|---------------------------|------------------------|--------------| | [TEST-PAY-01] | 4 tests, 4 failed | — | — | | [IMPL-PAY-02] | — | 4 passed, 0 failed | Extract config| ## Resume Context > TDD phase: RED. Writing webhook handler tests in > tests/payments/webhook.test.ts. Need to test > signature verification, idempotency, and event > routing for checkout.session.completed.
# Research Notes — User Auth System ## Date: 2026-03-28 ## Project Architecture Express.js API with TypeScript, src/ directory structure, Prisma ORM with PostgreSQL. App Router pattern with controllers in src/routes/, middleware in src/middleware/. ## Relevant Code - src/routes/users.ts — existing user CRUD (no auth) - src/middleware/cors.ts — CORS setup, pattern to follow - prisma/schema.prisma — User model exists, no password field - tests/integration/ — supertest-based, Jest runner ## Library Comparison | Need | Pick | Alternative | Rationale | |---------|-------------|-------------|------------------------| | JWT | jsonwebtoken | jose | Simpler API, widely used| | Hashing | argon2 | bcrypt | GPU-resistant, OWASP | | Validation | zod | joi, yup | TypeScript-native | ## Risk Assessment - Token storage: refresh tokens in DB, not cookies - Rate limiting needed on /auth/login to prevent brute force - Password reset flow is out of scope for this spec ## Open Questions - Should refresh tokens be stored hashed or plain? - Session invalidation strategy: single device or multi?
# Interview Round 1 — User Auth System ## Date: 2026-03-28 ## Questions Asked 1. The codebase uses Express middleware pattern for CORS. Should auth follow the same pattern as a middleware? Answer: Yes, same pattern. Middleware in src/middleware/. 2. Prisma User model has no password field yet. Add it directly or create a separate Credentials model? Answer: Add passwordHash directly to User. Keep it simple. 3. Should refresh tokens be stored hashed in the database? Answer: Yes, hash them. Same risk profile as passwords. 4. What does "done" look like for this spec? Answer: Register, login, refresh, logout all working. Protected routes return 401 without valid token. Tests passing for each endpoint. ## Key Decisions - Middleware pattern, same as existing CORS setup - passwordHash on User model, no separate table - Refresh tokens hashed with argon2 ## New Research Needed - argon2 hashing for refresh tokens (same lib as passwords?)
# Spec Registry | ID | Title | Status | Priority | Progress | Updated | |----------------------|--------------------|-------------|----------|----------|------------| | user-auth-system | User Auth System | active | high | 5/7 | 2026-03-30 | | payment-processing | Payment Processing | paused | medium | 2/8 | 2026-03-29 | | notification-system | Notifications | completed | medium | 12/12 | 2026-03-27 | One file, all your specs. Quick lookup without opening each SPEC.md. SPEC.md frontmatter is authoritative — registry is a denormalized index.
Multi-Spec Workflow

Juggle multiple specs without losing context

Forge a spec, pause it, start another, implement a few phases, switch back. Every spec remembers exactly where you stopped.

Session 1 — Auth
auth-system
Forge
Research, interview, write spec
auth-system
Implement
Phase 1 & 2 completed
auth-system
Pause
Context saved, resume later
Session 2 — Payments
payments
Forge
New spec, fresh research
payments
Implement
Phase 1 completed
payments
Pause
Switch back to auth
auth-system
Resume
Picks up at Phase 3, AUTH-08
auth-system
Complete
All phases done, spec archived
Compare

Core vs TDD at a glance

TDD builds on Core. Everything in Core is also in TDD — the TDD column shows what it adds. The -html suffix is orthogonal: same workflow, the only thing it changes is the output format from markdown to rich HTML.

Feature Core TDD
Research → Interview → Spec → Implement ✓ ✓
Deep researcher subagent ✓ ✓
Architecture diagrams & library comparisons ✓ ✓
Resume context & registry tracking ✓ ✓
TUI progress tracking & verification gates ✓ ✓
Phase-level review & self-review checklist ✓ ✓
Cross-tool support (Codex, Cursor, Windsurf, Cline, Gemini, Devin, Antigravity, and others) ✓ ✓
Alternating TEST-IMPL task pairs per phase — ✓
Strict red-green-refactor enforcement — ✓
TDD Log audit trail — ✓
Testing Architecture section in specs — ✓
Testcontainers & isolation strategy — ✓
Language-agnostic testing reference — ✓
Install

Up and running in one command

Install as a universal skill — one command, any AI coding tool.

Markdown specs
npx skills add ngvoicu/specmint-core -g
npx skills add ngvoicu/specmint-tdd -g
Rich HTML specs
npx skills add ngvoicu/specmint-core-html -g
npx skills add ngvoicu/specmint-tdd-html -g
Usage

Speak the magic words

Talk to your AI tool in plain language. The skill recognizes the spec lifecycle and triggers the right workflow.

Action
Say this
Start a new spec
“forge a spec for user authentication”
Execute the tasks
“implement the spec”
Resume where you left off
“what was I working on”
List all specs
“list my specs”
Show progress
“spec status”
Pause with context
“pause the spec”
Switch active spec
“switch to my-feature”
Generate API docs
“generate openapi”
Pair with Kluris

The knowledge your repo can’t tell you.

Specmint reads your codebase. Kluris gives your agents the other half — tribal knowledge that never made it into comments. Decisions, constraints, past incidents, who owns what. Curated. Versioned. Queryable.

R

Grounded research

Phase 1a reads the repo. Phase 1b queries the brain. Specs land with decisions, not guesses.

M

Institutional memory

Architecture calls, migration scars, stakeholder context. Survives team turnover and agent resets.

S

Spec reuse

Harvest reusable patterns from shipped specs back into the brain. The next feature starts smarter.

phase 1b · research 
> write a spec for OAuth sign-in with GitHub —
  check the brain, the codebase, and the web

research · phase 1a · reading codebase ........ done
research · phase 1b · kluris wake-up ........... done
research · phase 1c · synthesis ............... done

> spec written to .specs/oauth-github.md — ready for interview.
One brain. Every agent.  Kluris turns a git repo into a shared knowledge graph — readable by Specmint, Claude Code, Codex, Cursor, Windsurf, and the rest of your toolchain.
pipx install kluris Explore Kluris →