ngvoicu/kluris / crates/kluris-cli/tests/fixtures/upgrade-home/migration-crlf/home/dot-kluris/companions/specmint-core
specmint-core
VerifiedPersistent spec management for AI coding workflows. Use this skill when the user explicitly mentions specs, forging, or structured planning: says "forge", "forge a spec", "write a spec for X", "create a spec", "plan X as a spec", "resume", "what was I working on", "spec list/status/pause/switch/activate", "implement the spec", "implement phase N", "implement all phases", "generate openapi", or exits plan mode (offer to save as a spec). Also trigger when a `.specs/` directory exists at session start. Do NOT trigger on general feature requests, coding tasks, or questions that don't mention specs or forging — those are normal coding tasks, not spec management.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 29.3 KB |
| references/command-contracts.md | markdown | 3.8 KB |
| references/researcher.md | markdown | 11.4 KB |
| references/spec-format.md | markdown | 13.0 KB |
references/spec-format.md
View on GitHub# SPEC.md Format Reference
This is the complete format specification for spec documents. Use this as
the template when creating new specs.
## Full Template
```markdown
---
id: <spec-id>
title: <Human Readable Title>
status: active | paused | completed | archived
created: <YYYY-MM-DD>
updated: <YYYY-MM-DD>
priority: high | medium | low
tags: [<tag1>, <tag2>]
---
# <Title>
## Overview
<2-4 sentences describing what this spec accomplishes and why. Include
enough context that someone resuming cold can understand the goal without
reading the full conversation history.>
## Acceptance Criteria
- [ ] <When X happens, the system does Y>
- [ ] <The Z component returns W with status code N>
- [ ] <Users can perform action A and see result B>
- [ ] [NEEDS CLARIFICATION] <Ambiguous criterion that needs discussion>
Testable conditions that define when the spec is "done". Each criterion
is a checkbox — checked off during implementation as it becomes satisfied.
Be specific and verifiable: "returns 401 with error body" not "handles
errors correctly". At spec completion, all criteria must be checked.
Skip for trivial bug fixes, but features always need them — they prevent
scope creep and make verification unambiguous.
## Architecture
<Include at least one diagram showing the system design. Use ASCII art for
simple flows and Mermaid for complex relationships.>
### System Diagram
```
Client → API Gateway → Auth Middleware → Route Handler → Database
↓
Cache Layer
```
<Or use Mermaid for more complex diagrams:>
```mermaid
graph TD
A[Client] --> B[API Gateway]
B --> C{Auth Middleware}
C -->|Authenticated| D[Route Handler]
C -->|Unauthorized| E[401 Response]
D --> F[(Database)]
D --> G[Cache]
```
<For data models, use ER diagrams:>
```mermaid
erDiagram
USER ||--o{ ORDER : places
ORDER ||--|{ LINE_ITEM : contains
PRODUCT ||--o{ LINE_ITEM : "ordered in"
```
<For state machines and workflows:>
```mermaid
stateDiagram-v2
[*] --> Draft
Draft --> Review
Review --> Approved
Review --> Rejected
Approved --> Published
Rejected --> Draft
```
## Library Choices
| Need | Library | Version | Alternatives Considered | Rationale |
|------|---------|---------|------------------------|-----------|
| <need> | <chosen> | <ver> | <alt1>, <alt2> | <why this one> |
## Phase 1: <Phase Name> [in-progress]
- [x] [ID-01] <Completed task description>
- [ ] [ID-02] <Current task description> ← current
- [ ] [ID-03] <Future task description>
- [ ] [ID-04] <Future task description>
## Phase 2: <Phase Name> [pending]
- [ ] [ID-05] <Task description>
- [ ] [ID-06] <Task description>
- [ ] [ID-07] <Task description>
## Phase 3: <Phase Name> [pending]
- [ ] [ID-08] <Task description>
- [ ] [ID-09] <Task description>
## Testing Strategy
### Unit Tests
- `tests/unit/<area>.test.ts` — <what it tests>
- Framework: <Jest/Vitest/pytest/etc.>
### Integration Tests
- `tests/integration/<flow>.test.ts` — <what flows it tests>
- Database/API interaction tests
### End-to-End Tests
- `tests/e2e/<scenario>.spec.ts` — <user flows tested>
- Framework: <Playwright/Cypress/etc.>
### Edge Case Tests
- Boundary conditions: <list>
- Error scenarios: <list>
- Concurrent access: <list>
---
## Resume Context
> <Detailed description of where you left off. Include:>
> - What was just completed
> - What's currently in progress
> - Specific file paths and function/component names
> - The exact next step to take
> - Any blockers or open questions
>
> Write this as if briefing a colleague picking up your work tomorrow.
## Decision Log
| Date | Decision | Rationale |
|------|----------|-----------|
| <YYYY-MM-DD> | <What was decided> | <Why this choice was made> |
## Deviations
| Task | Spec Said | Actually Did | Why |
|------|-----------|-------------|-----|
| <Task name> | <What was planned> | <What was implemented> | <Reason for the change> |
```
## Field Definitions
### Frontmatter Fields
| Field | Required | Description |
|-------|----------|-------------|
| `id` | Yes | URL-safe identifier, lowercase hyphenated (e.g., `user-auth-system`) |
| `title` | Yes | Human-readable name |
| `status` | Yes | One of: `active`, `paused`, `completed`, `archived` |
| `created` | Yes | ISO date when spec was created |
| `updated` | Yes | ISO date of last modification |
| `priority` | No | `high`, `medium`, or `low` (default: medium) |
| `tags` | No | YAML array of categorization tags |
### Phase Status Markers
Phase headings include a status marker in square brackets:
| Marker | Meaning |
|--------|---------|
| `[pending]` | Not started yet |
| `[in-progress]` | Currently being worked on |
| `[completed]` | All tasks done |
| `[blocked]` | Waiting on something external |
Only **one phase** should be `[in-progress]` at a time (though this isn't
strictly enforced — sometimes parallel phases make sense).
### Task Format
Tasks use markdown checkboxes with a task code prefix:
```markdown
- [ ] [AUTH-01] Unchecked task (not done)
- [x] [AUTH-02] Checked task (done)
- [ ] [AUTH-03] Current task ← current
```
**Task codes** use the format `<PREFIX>-<NN>`:
- **Prefix**: A short (2-4 letter) uppercase abbreviation of the spec.
Pick the most recognizable word or use initials:
- `user-auth-system` → `AUTH`
- `api-refactor` → `API`
- `fix-upload-bug` → `UPL`
- `real-time-collab` → `RTC`
- `ci-pipeline` → `CI`
- **Number**: Two-digit, auto-incrementing across all phases (not per-phase).
Start at `01`.
The `← current` marker indicates which task the AI should work on next.
Only one task should have this marker at a time.
**Task granularity**: Each task should represent roughly one focused work
session (30 min to 2 hours of work). If a task feels like it would take a
full day, break it into subtasks.
### Uncertainty Markers
Use `[NEEDS CLARIFICATION]` for any requirement or task where ambiguity
remains after interviews:
```markdown
- [ ] [AUTH-05] [NEEDS CLARIFICATION] Handle rate limiting for uploads
```
These markers signal that the task needs more discussion before
implementation. Don't start a task with this marker — resolve it first
(run another interview round or ask the user directly).
### Resume Context
The Resume Context section is freeform markdown inside a blockquote. It
should answer these questions:
1. **What just happened?** — What was completed in the last session
2. **What's the current state?** — Which files changed, what works, what doesn't
3. **What's next?** — The specific next action to take
4. **Where exactly?** — File paths, function names, line ranges
5. **Any gotchas?** — Blockers, open questions, things that didn't work
**Good example:**
```markdown
> Finished implementing the JWT token generation in `src/auth/tokens.ts`.
> The `generateAccessToken()` and `generateRefreshToken()` functions are
> working and tested. Moved on to the refresh endpoint but hit an issue:
> the `POST /auth/refresh` handler in `src/routes/auth.ts` needs to
> validate the refresh token AND rotate it (issue new refresh token on
> each use). The validation part works but rotation isn't implemented.
>
> Next step: Add `rotateRefreshToken()` to `src/auth/tokens.ts` that
> invalidates the old token and issues a new one. Then wire it into the
> route handler. See the TODO comment at line 47 of `src/routes/auth.ts`.
```
**Bad example:**
```markdown
> Was working on authentication. Made some progress on tokens.
```
### Decision Log
Track non-obvious technical decisions so you (or another AI session) can
understand why things are the way they are:
```markdown
| Date | Decision | Rationale |
|------|----------|-----------|
| 2026-02-10 | JWT over sessions | Stateless auth scales better for our microservice architecture |
| 2026-02-10 | Refresh token rotation | Security best practice — limits window if a token is stolen |
| 2026-02-11 | argon2 over bcrypt | Better resistance to GPU attacks, recommended by OWASP |
```
Good decisions to log:
- Library/framework choices
- Architecture patterns
- API design decisions
- Trade-offs made (performance vs readability, etc.)
- Things you tried and rejected (and why)
### Deviations
Track cases where implementation diverged from the original spec. This
happens when errors are found, assumptions prove wrong, or a better
approach is discovered during coding:
```markdown
| Task | Spec Said | Actually Did | Why |
|------|-----------|-------------|-----|
| OAuth callback | Use passport.js | Direct HTTP calls to provider | passport.js added complexity with no benefit for just 2 providers |
| Rate limiting | Redis-based limiter | In-memory with `express-rate-limit` | No Redis in the stack; in-memory is fine for single-instance |
```
Good deviations to log:
- Tasks where the approach changed during implementation
- API signatures that differ from what was planned
- Libraries swapped for alternatives
- Tasks skipped because they turned out unnecessary
- Extra tasks added to handle discovered edge cases
**Don't log minor adjustments** (renamed a variable, reordered parameters).
Only log changes that would surprise someone reading the spec and comparing
it to the code.
## Minimal Spec Example
For small tasks, a spec can be much simpler:
```markdown
---
id: fix-upload-bug
title: Fix File Upload Bug
status: active
created: 2026-02-10
updated: 2026-02-10
priority: high
---
# Fix File Upload Bug
## Overview
Files over 10MB fail silently on upload. The multipart parser truncates
the stream. Need to fix the size limit and add proper error handling.
## Phase 1: Fix and Test [in-progress]
- [ ] [UPL-01] Reproduce the bug with a 15MB file ← current
- [ ] [UPL-02] Fix multipart parser size limit in `src/upload/parser.ts`
- [ ] [UPL-03] Add proper error response for oversized files
- [ ] [UPL-04] Write test for boundary conditions (exactly 10MB, 10.1MB, 100MB)
- [ ] [UPL-05] Test in staging
---
## Resume Context
> Haven't started yet. Bug report is in issue #342. The upload handler
> is in `src/upload/parser.ts` and uses `busboy` for multipart parsing.
> Suspect the `limits.fileSize` option is set too low.
```
## Complex Spec Example
For larger features with multiple phases:
```markdown
---
id: real-time-collab
title: Real-Time Collaboration
status: active
created: 2026-02-01
updated: 2026-02-10
priority: high
tags: [feature, websocket, collaboration]
---
# Real-Time Collaboration
## Overview
Add real-time collaborative editing to the document editor. Multiple
users should see each other's cursors and edits in real time, with
conflict resolution handled via CRDTs.
## Phase 1: WebSocket Infrastructure [completed]
- [x] [RTC-01] Set up WebSocket server with Socket.io
- [x] [RTC-02] Implement room-based connections (one room per document)
- [x] [RTC-03] Add authentication middleware for WS connections
- [x] [RTC-04] Handle reconnection and connection state
## Phase 2: CRDT Integration [in-progress]
- [x] [RTC-05] Integrate Yjs as the CRDT library
- [x] [RTC-06] Create document sync provider
- [ ] [RTC-07] Implement awareness protocol (cursors, selections) ← current
- [ ] [RTC-08] Add undo/redo manager that works with CRDTs
## Phase 3: UI Layer [pending]
- [ ] [RTC-09] Render remote cursors with user colors/names
- [ ] [RTC-10] Show selection highlights for other users
- [ ] [RTC-11] Add presence indicator (who's viewing)
- [ ] [RTC-12] Handle offline state gracefully in UI
## Phase 4: Edge Cases and Polish [pending]
- [ ] [RTC-13] Test with 10+ simultaneous users
- [ ] [RTC-14] Handle large document performance
- [ ] [RTC-15] Add rate limiting for rapid edits
- [ ] [RTC-16] Write integration tests for conflict scenarios
---
## Resume Context
> Phase 2 is in progress. Yjs is integrated and basic document sync
> works between two browser tabs. Currently implementing the awareness
> protocol which handles cursor positions and user presence.
>
> The awareness provider is partially built in
> `src/collab/awareness-provider.ts`. The local cursor state broadcasts
> correctly but remote cursor state isn't being applied to the editor
> yet. Need to hook into CodeMirror's decoration system to render
> remote cursors.
>
> Key file: `src/collab/awareness-provider.ts` (the provider)
> Key file: `src/editor/remote-cursors.ts` (needs to be created)
> Reference: Yjs awareness docs at https://docs.yjs.dev/api/about-awareness
## Decision Log
| Date | Decision | Rationale |
|------|----------|-----------|
| 2026-02-01 | Socket.io over raw WS | Built-in reconnection, rooms, and fallback to polling |
| 2026-02-03 | Yjs over Automerge | Better editor integration (ProseMirror/CodeMirror bindings) |
| 2026-02-05 | Room-per-document | Simpler than multiplexing, isolates failure domains |
| 2026-02-08 | Awareness as separate protocol | Cursor positions need higher update frequency than doc edits |
## Deviations
| Task | Spec Said | Actually Did | Why |
|------|-----------|-------------|-----|
| WS authentication | JWT in query params | JWT in first message after connect | Query params are logged by proxies — security risk |
```
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis. | Stars: 472k | Updated | Claude CodeCodex | Verified | Install |
| diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness. | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependencies | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is available | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |