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/command-contracts.md
View on GitHub# Command Contracts
This file defines functional contracts for the `SKILL.md` skill behavior. Use
it as a review checklist before releases.
## Global Contracts
1. `SPEC.md` frontmatter is authoritative; registry is denormalized.
2. Exactly one active spec should exist after any write operation.
3. All write workflows update `SPEC.md` first, then recompute/update registry.
4. Forge workflow never writes application code.
5. Phase markers use `[pending]`, `[in-progress]`, `[completed]`, `[blocked]`.
Task lines use checkboxes and `← current`; tasks are not tagged `[blocked]`.
6. **Progress tracking is sacred.** After every task completion: update SPEC.md
(checkbox, current marker, phase marker), update registry (progress, date),
then re-read both files to verify consistency. Never skip this.
7. **Acceptance criteria are required for feature specs.** Forge must include
an `## Acceptance Criteria` section with testable checkbox conditions.
Implement must check off criteria as they are satisfied and verify all are
met before marking a spec complete.
## Command Contracts
### Forge
1. Resolve `<spec-id>` before research output paths are referenced.
2. Collision-check existing spec IDs before creating new files.
3. Forge must not run in plan mode; if plan mode is active, require exit before
continuing.
4. Output scope is `.specs/` artifacts only (`research-*.md`, `interview-*.md`,
`SPEC.md`, `registry.md` updates).
5. After approval, hand off to the implement workflow instead of implementing
inside forge.
6. Interview must ask about acceptance criteria ("What does 'done' look like?").
7. SPEC.md must include `## Acceptance Criteria` with testable checkboxes.
### Implement
1. Supports scope parsing: current flow, phase-specific, all phases, task code.
2. For each completed task: checkbox + current marker + phase markers +
frontmatter `updated` + registry progress/date. Then re-read both files
to verify consistency.
3. At phase completion, review and check off satisfied acceptance criteria.
4. At spec completion, verify all acceptance criteria are checked before
marking complete.
5. Blocked handling:
- Keep blocked tasks unchecked.
- Mark phase `[blocked]` only when the phase is blocked.
- Record blocker context in Resume Context/Decision Log/Deviations as needed.
### Resume
1. If no active spec exists, list specs and request target.
2. Include progress, current phase/task, and Resume Context in output.
### Pause
1. If no active spec exists, report no-op and stop.
2. Persist detailed Resume Context with concrete file/function references.
3. Set status `paused` and sync registry.
### Switch
1. Validate target ID and target `SPEC.md` existence before pausing current spec.
2. If target already active, report and stop.
3. Pause current (if any), activate target, resume target, sync registry.
### List
1. Handle missing registry gracefully.
2. Group by status in order: active, paused, completed, archived.
3. If `SPEC.md` missing for a row, keep row visible and flag it.
### Status
1. Show detailed phase/task breakdown for active spec.
2. If no active spec, guide to activate one.
### OpenAPI
1. Generate/update `.openapi/openapi.yaml` and `.openapi/endpoints/*.md`.
2. Preserve manual additions when updating existing files.
3. Report endpoint/schema/security counts and manual-review candidates.
## Universal Skill Contract
1. `SKILL.md` must include cross-tool behavior for all declared triggers.
2. If `generate openapi` is listed as a trigger, OpenAPI workflow behavior must
be defined in `SKILL.md`.
3. Command-specific docs can specialize behavior but cannot violate critical
invariants from `SKILL.md`.
## Release Checklist
1. Paths referenced in docs and templates exist (excluding placeholder paths).
2. Command contracts in this file still match `SKILL.md`.
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: 471k | 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 |