specmint-core

Files (9)

• .gitignore
• AGENTS.md
• CLAUDE.md
• LICENSE
• README.md
• SKILL.md
• command-contracts.md · references/
• researcher.md · references/
• spec-format.md · references/

SKILL.md (first lines)

# 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/<id>/SPEC.md`, `.specs/<id>/research-*.md`,
     `.specs/<id>/interview-*.md`
3. **Authority rule**: `SPEC.md` frontmatter is authoritative. Registry is a
   denormalized index for quick lookup.
4. **Active-spec rule**: Target exactly one active spec at a time.
5. **Parser policy**: Use best-effort parsing with clear warnings and repair
   guidance instead of hard failure on malformed rows.
6. **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."
3. 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/<id>/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/<id>/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)
4. Read the **Resume Context** section
5. 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
   ```

6. 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
4. Update the `updated` date in YAML frontmatter
5. 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.
5. 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:

From ngvoicu/specmint-core, MIT.