Specmint Core

Spec Mint Core

Turn ephemeral plans into structured, persistent specs built through deep research and iterative interviews. Specs have phases, tasks, acceptance criteria, a registry, resume context, a decision 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. Progress tracking is sacred: After completing any task, immediately

update SPEC.md (checkbox, ← current marker, phase marker) 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: Implement Google OAuth callback handler Context: Token exchange is working. Need to handle the callback URL parsing and store refresh tokens in the user model. Next file: src/auth/oauth/google.ts ``

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

Implementing

After completing each task, immediately edit the SPEC.md file to record progress. Do not wait until the end of a session or until asked — update the spec as you go. This is sacred (see Critical Invariant #6).

1. Check off the completed task: - [ ] -> - [x]
2. Move ← current to the next unchecked task
3. When all tasks in a phase are done:

• Phase status: [in-progress] -> [completed]
• Next phase: [pending] -> [in-progress]
• Review Acceptance Criteria — check off any that are now satisfied

1. Update the updated date in YAML frontmatter
2. Update progress (X/Y) and updated date in .specs/registry.md

Update transaction (required order — never skip steps):

1. Edit SPEC.md (checkbox, current marker, phase marker, resume context).
2. Recompute progress directly from SPEC.md checkboxes.
3. Edit the matching registry row (status, progress, updated date).
4. 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. Stale tracking is the single most common failure mode — it makes resume unreliable and the registry useless.

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

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

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, and the exact next step. Vague context like "was working on auth" is useless — write "implementing verifyRefreshToken() in src/auth/tokens.ts, the JWT verification works but refresh rotation isn't hooked up to the /auth/refresh endpoint yet."

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-core 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

• - [ ] [CODE-01] unchecked, - [x] [CODE-01] done
• Task codes: - — prefix is a short (2-4 letter) uppercase

abbreviation of the spec (e.g., user-auth-system → AUTH). Numbers auto-increment across all phases starting at 01

• ← current after the task text marks the active task
• [NEEDS CLARIFICATION] after the task code on unclear tasks

Acceptance Criteria

Testable conditions that define when the spec is "done". Written during forge, verified after each phase completes. Format: checkboxes with specific, verifiable statements — not vague goals.

## Acceptance Criteria

- [ ] Users can sign in with Google OAuth and receive a JWT
- [ ] Expired tokens return 401 with `{"error": "token_expired"}`
- [ ] Refresh tokens rotate on each use (old token is invalidated)
- [ ] Rate limiting returns 429 after 100 requests per minute

Check off criteria as they are satisfied during implementation. At phase completion, review which acceptance criteria are now met. At spec completion, all criteria must be checked — if any remain unchecked, the spec is not done.

Resume Context

Blockquote section with specific file paths, function names, and exact next step. This is what makes cross-session continuity work.

Decision Log

Markdown table with date, decision, and rationale columns. Log non-obvious technical choices (library selection, architecture pattern, API design).

Deviations

Markdown table tracking where implementation diverged from the spec: task, what the spec said, what was actually done, and why. Only log changes that would surprise someone comparing the spec to the code.

Use the Spec Format section in this file as the canonical SPEC.md template.

Forging Specs

When asked to forge, plan, spec out, or "write a spec for X", follow the full forge workflow: setup, research deeply, interview the user, iterate until clear, then write the spec.

If the environment is in read-only plan mode, do not run forge in that mode. Ask the user to exit plan mode (Shift+Tab) and rerun /specmint-core:forge.

The forge workflow never produces application code. Its outputs are only .specs/ files: research notes, interview notes, and the SPEC.md. If the user says "write a spec", that means write a SPEC.md — not implement the feature. Implementation happens separately, after the user reviews and approves the spec.

Step 1: Setup

1. Generate a spec ID from the title (lowercase, hyphenated):

"User Auth System" -> user-auth-system

1. Collision check: If .specs//SPEC.md already exists or the ID

appears in .specs/registry.md, warn the user and ask:

• Resume the existing spec
• Rename the new spec (suggest -v2 or ask for a new title)
• Archive the old spec and create a new one in its place

Do not proceed until the user chooses.

1. Initialize directories:

``bash mkdir -p .specs/ ``

1. If .specs/registry.md doesn't exist, initialize it:

```markdown # Spec Registry

| ID | Title | Status | Priority | Progress | Updated | |----|-------|--------|----------|----------|---------| ```

Step 2: Deep Research

Research is the foundation of a good spec. Be exhaustive — use every available resource. The goal is to gather enough context that the spec won't need revision mid-build.

Research runs on two parallel tracks to maximize thoroughness and speed:

Track A: Spawn the Researcher Agent

Always spawn the specmint-core:researcher agent for codebase + internet research. Don't skip this — the researcher is purpose-built for exhaustive multi-source analysis and runs in parallel so it doesn't slow down the workflow.

Spawn it with the Task tool, providing:

• The user's request (what they want to build/change)
• The spec ID and output path: .specs//research-01.md
• Any Context7 findings you've already gathered (Track B)
• Specific areas to focus on, if known

The researcher will:

• Map the full project architecture (read manifests, lock files, directory tree)
• Read 15-30 relevant code files and trace dependency chains
• Run 3+ web searches for best practices and current patterns
• Compare 2-4 library candidates for every choice point
• Assess security risks and performance implications
• Produce a structured research document with a completeness checklist

Track B: Context7 & Cross-Skill Research (in parallel)

While the researcher runs, do these yourself — they use MCP tools that the researcher agent doesn't have access to:

• Context7: If available (resolve-library-id / query-docs tools), pull

up-to-date documentation for every key library involved. Check API changes, deprecated features, and recommended patterns for the specific versions in use. Do this for 2-5 key libraries — the ones central to the feature being built.

• Cross-skill loading: Load other available skills when relevant:
• frontend-design: For UI-heavy specs — creative, professional design
• datasmith-pg: For database specs — schema design, migrations, indexing
• webapp-testing: For testing strategy — Playwright patterns
• vercel-react-best-practices: For Next.js/React performance
• Any other relevant skill that's available
• UI research (if applicable): Take screenshots, map component hierarchy,

research modern UI patterns, note accessibility requirements

Merging Research

When the researcher agent completes, read its output at .specs//research-01.md. Merge your Context7 and cross-skill findings into the research notes — either append to the file or keep them in mind for the interview. The combined research should cover: architecture, relevant code, tech stack, library comparisons, internet research, Context7 docs, UI research (if applicable), risk assessment, and open questions.

Step 3: Interview Round 1

Present your research findings and ask targeted questions. Your research should inform specific questions, not generic ones.

1. Summarize findings (2-3 paragraphs — not a wall of text)
2. State assumptions — "Based on the codebase, I'm assuming we'll use X

pattern because that's what similar features use. Correct?"

1. Ask 3-6 targeted questions that research couldn't answer:

• Architecture decisions ("New module or extend existing one?")
• Scope boundaries ("Should this handle X edge case?")
• Technical choices ("Stick with Library A or try Library B?")
• User-facing behavior ("What should happen when X fails?")
• Acceptance criteria ("What does 'done' look like? Any specific

conditions that must be true when this is complete?")

1. Propose a rough approach and ask for reactions

STOP after presenting questions. Wait for the user to answer before proceeding. Do not answer your own questions, do not assume answers, and do not continue to Step 4 or Step 5 until the user has responded. The interview is a conversation — the user's answers shape the spec. If you skip this, the spec will be based on guesses instead of decisions.

Save to .specs//interview-01.md with: questions asked, user answers, key decisions, and any new research needed.

Step 4: Deeper Research + Interview Loop

Based on the user's answers, do another round of research — explore the specific paths they chose, check feasibility, find potential issues. Save to .specs//research-02.md.

Then present deeper findings and ask about trade-offs, edge cases, implementation sequence, and scope refinement. Save each interview round to interview-02.md, interview-03.md, etc.

Repeat research-then-interview until:

• You have enough clarity to write a spec with no ambiguous tasks
• The user is satisfied with the direction
• Every task can be described concretely (not "figure out X")

Two rounds is typical. Don't rush it — but don't drag it out either.

Step 5: Write the Spec

Synthesize all research notes, interview answers, and decisions into a comprehensive SPEC.md using the Spec Format section in this file.

The spec should be thorough and detailed — someone reading it should be able to implement the feature without guessing. Include:

• YAML frontmatter (id, title, status, created, updated, priority, tags)
• Overview (2-4 sentences — what's being built and why)
• Acceptance Criteria — Testable conditions defining "done". Checkbox

format so they can be checked off during implementation. Each criterion should be specific and verifiable, not vague ("works correctly").

• **Arch

…

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.