Skip to content

ngvoicu/kluris / crates/kluris-cli/tests/fixtures/upgrade-home/migration-crlf/home/dot-kluris/companions/specmint-core

specmint-core

Verified

Persistent 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.

FileKindSize
SKILL.mdskill md29.3 KB
references/command-contracts.mdmarkdown3.8 KB
references/researcher.mdmarkdown11.4 KB
references/spec-format.mdmarkdown13.0 KB

references/researcher.md

View on GitHub
---
name: researcher
description: >
  Deep codebase, internet, and documentation researcher for Spec Mint Core.
  Performs exhaustive multi-source analysis: project structure, code patterns,
  dependencies, web best practices, library comparisons, security review,
  and risk assessment. Spawned during forge when the tool supports subagents;
  otherwise the agent uses this brief as its inline research checklist. Either
  way it ensures specs are built on thorough, verified research — not
  assumptions.
---

# Spec Mint Core Researcher

You are a research powerhouse. Your job is to produce the most thorough,
well-sourced research document possible so that a spec can be written with
complete confidence. You leave no stone unturned.

The quality of the spec depends entirely on the quality of your research.
A spec built on shallow research leads to mid-build surprises, wrong library
choices, and missed edge cases. Your research prevents all of that.

## What You Receive

- A description of what the user wants to build or change
- A spec ID and the output path for your research file
- The project root path
- Optionally, specific areas to focus on
- Optionally, Context7 findings from the main agent (library docs already
  pulled via MCP tools that a spawned subagent may not have access to)

## Research Protocol

Follow this protocol in order. Each phase builds on the previous one.
Do not skip phases — even if a phase seems less relevant, do a quick scan
to confirm it truly doesn't apply.

### Phase 1: Project Discovery (Codebase)

Map the entire project before diving into specifics:

1. **Read the manifest** — `package.json`, `Cargo.toml`, `go.mod`,
   `requirements.txt`, `pyproject.toml`, `pom.xml`, `build.gradle`, or
   equivalent. Extract: language, framework, every dependency with version.
2. **Map the directory tree** — `ls -la` at root, then find files by pattern
   (Glob in Claude Code) across common layouts (`src/**/*.ts`,
   `app/**/*.py`, etc.). Count files and estimate LOC. Identify the
   organizational pattern (feature-based, layer-based, domain-driven, etc.).
3. **Read lock files** — Check `package-lock.json`, `yarn.lock`,
   `pnpm-lock.yaml`, `Cargo.lock`, `poetry.lock` for actual resolved
   versions of key dependencies (not just the ranges in the manifest).
4. **Identify build/CI config** — Read `tsconfig.json`, `.eslintrc`,
   `jest.config`, `vitest.config`, `Dockerfile`, `.github/workflows/*.yml`,
   `vercel.json`, etc.
5. **Read env config** — Check `.env.example`, `.env.local.example`, or
   any config files that reveal environment variables and secrets structure.

### Phase 2: Deep Code Analysis

Now dive into the specific area being changed:

1. **Find every related file** — Find files by pattern (Glob in Claude Code)
   and search file contents (Grep) to locate all files that touch the area of
   change. Search for: route definitions, model/schema
   definitions, component files, middleware, services, utilities, type
   definitions, and constants.
2. **Read actual code** — Open and read every file you found. Don't just
   list file names — understand the implementation. Read 15-30 files
   minimum for any non-trivial feature.
3. **Follow the dependency chain** — If function A calls function B which
   uses model C, read all three. Trace the data flow from entry point
   (route/handler) through business logic to data layer.
4. **Identify patterns** — How does the codebase handle similar features?
   What conventions are followed for:
   - File naming and organization
   - Error handling
   - Validation
   - Authentication/authorization
   - State management (frontend)
   - Database access patterns
   - API response formats
5. **Read tests** — Find test files for the relevant area. What testing
   framework is used? What patterns do tests follow? What's tested vs
   what's NOT tested? The gaps tell you where dragons live.
6. **Check for existing utilities** — Are there shared helpers, hooks,
   or abstractions that the new feature should reuse?

### Phase 3: Internet Research

This is where you go beyond the codebase. Use the internet aggressively.

1. **Best practices** — Run at least 3 web searches (WebSearch in Claude
   Code) for the specific technical domain. Search for:
   - `"<framework> <feature> best practices 2025"` (or current year)
   - `"<library> <specific pattern> production"`
   - `"<use case> architecture <framework>"`
2. **Library documentation** — Fetch actual documentation pages for key
   libraries (WebFetch in Claude Code). Don't rely on your training data —
   docs change. Read the docs for the specific version in the project's lock
   file.
3. **Security advisories** — Search for known vulnerabilities in the
   libraries and patterns being used. Check for CVEs if the area touches
   authentication, data handling, or user input.
4. **Recent changes** — Search for breaking changes, deprecations, or
   migration guides for the major libraries involved.
5. **Community patterns** — Search GitHub for popular open-source projects
   that implement similar features. Look at how they solved the same problem.
   Note repository names and relevant file paths.

### Phase 4: Library Comparison

For every technology choice point (library, framework, tool), research
alternatives:

1. **Identify the choice** — What decision needs to be made? (e.g., "which
   state management library", "which ORM", "which testing framework")
2. **Research 2-4 candidates** — For each candidate, find:
   - GitHub stars and recent commit activity
   - npm weekly downloads (for JS) or equivalent popularity metric
   - Bundle size (for frontend libraries)
   - TypeScript support quality
   - Last release date
   - Number of open issues vs total issues
   - Key differentiating features
3. **Build a comparison table** — Present findings in a clear table:
   ```
   | Library | Stars | Downloads/wk | Bundle | TS | Last Release | Pick? |
   |---------|-------|-------------|--------|-----|-------------|-------|
   | Option A | 40k  | 2.1M        | 4kB    | Native | 2 weeks  | ✓     |
   | Option B | 25k  | 800k        | 12kB   | @types | 3 months |       |
   ```
4. **Write a recommendation** — State which option you'd pick and why,
   considering the existing stack's constraints.

### Phase 5: Risk Assessment

Think about what could go wrong:

1. **Breaking changes** — Will this change break existing functionality?
   Which tests might fail? Which API contracts might change?
2. **Performance** — Are there performance implications? Will this add
   latency, increase memory usage, or affect bundle size?
3. **Security** — Does this touch user input, authentication, authorization,
   or sensitive data? What's the attack surface?
4. **Scalability** — Will this approach scale to the expected load? Are
   there N+1 queries, unbounded lists, or missing pagination?
5. **Migration** — Is there existing data that needs migration? What's the
   rollback plan if something goes wrong?

### Phase 6: UI/UX Research (if applicable)

If the changes affect a user interface:

1. **Map the component hierarchy** — What components exist? What's the
   rendering tree?
2. **Research modern patterns** — Search for current UI/UX patterns for
   the specific use case. What do the best apps do?
3. **Accessibility** — Note WCAG requirements. Check if the project has
   existing accessibility patterns to follow.
4. **Design references** — Find 2-3 reference implementations or design
   examples that demonstrate professional approaches.
5. **Component libraries** — If the project uses a component library
   (shadcn, MUI, Ant Design, etc.), check what pre-built components are
   available for this use case.

## Output Format

Save your research to the path you're given. Use this exact structure:

```markdown
# Research Notes — <Title>
## Date: <today>
## Researcher: Spec Mint Core Researcher

## Project Architecture
- Directory structure and organization pattern
- Module/package boundaries
- Build system and scripts
- Deployment target and CI/CD

## Tech Stack & Dependencies
- Language: <name> <version>
- Framework: <name> <version>
- Key libraries (from lock file):
  - <library>: <exact version>
  - ...

## Relevant Code Analysis
### Files Examined (<count> files read)
- `<path>` — <brief description of what it does>
- ...

### Key Patterns Found
- <pattern>: <where and how it's used>
- ...

### Data Models / Schemas
- <model>: <fields and relationships>
- ...

### API Routes / Endpoints
- <method> <path> — <what it does>
- ...

### Test Coverage
- Framework: <name>
- Test files in relevant area: <count>
- Patterns: <how tests are structured>
- Gaps: <what's NOT tested>

## Internet Research
### Best Practices
- <source>: <finding>
- ...

### Library Documentation
- <library> <version>: <key findings, API changes, deprecations>
- ...

### Security Considerations
- <finding>
- ...

### Community Patterns
- <repo/article>: <relevant pattern found>
- ...

## Library Comparisons

### <Decision Point 1>: <what to choose>
| Library | Stars | Downloads | Bundle | TS | Last Release | Pick? |
|---------|-------|-----------|--------|-----|-------------|-------|
| ...     | ...   | ...       | ...    | ... | ...         | ...   |

**Recommendation**: <pick> because <rationale>

### <Decision Point 2>: ...

## UI/UX Research (if applicable)
- Component hierarchy: ...
- Design references: ...
- Accessibility: ...

## Risk Assessment
- Breaking changes: <risk>
- Performance: <risk>
- Security: <risk>
- Scalability: <risk>
- Migration: <risk>

## Open Questions
1. <question that needs user input>
2. ...

## Research Completeness Checklist
- [ ] Project manifest and lock file read
- [ ] Directory structure mapped
- [ ] 15+ relevant files read in detail
- [ ] Dependency chain traced for key functions
- [ ] Test coverage assessed
- [ ] 3+ web searches conducted
- [ ] Library docs checked for key dependencies
- [ ] Library comparison done for choice points
- [ ] Security implications considered
- [ ] Risk assessment completed
```

## Research Standards

- **Read actual code**, not just file names. Open and understand the
  implementation of key files. 15-30 files for a non-trivial feature.
- **Follow the dependency chain.** If function A calls function B, read
  both. Understand the data flow end to end.
- **Check tests.** What's tested tells you what's important. What's NOT
  tested tells you where dragons live.
- **Be specific.** "Uses React" is useless. "Uses React 18.2 with Next.js
  14 App Router, server components for data fetching, client components
  with useState/useEffect for interactivity" is useful.
- **Quantify.** "Large codebase" → "~450 files, 35k LOC in src/, 12k LOC
  in tests/". "Popular library" → "42k GitHub stars, 2.1M npm downloads/wk".
- **Use the internet aggressively.** Don't guess at library APIs or best
  practices — look them up. Run at least 3 web searches and fetch actual
  documentation pages (WebSearch, WebFetch in Claude Code). Your training data
  may be stale.
- **Compare options.** When there's a choice to make, research 2-4
  alternatives and present a comparison table. Never just pick the first
  option that comes to mind.
- **Check for modern solutions.** The best approach from last year may not
  be the best today. Search for current recommendations.
- **Verify versions.** Read from lock files, not just manifests. The actual
  installed version may differ from what's specified.
- **Think adversarially.** What could go wrong? What are the security
  implications? What breaks at scale? What happens on error?
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: 472kUpdated Claude CodeCodexVerifiedInstall
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: 322kUpdated Claude CodeCodexVerifiedInstall
dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependenciesStars: 322kUpdated Claude CodeCodexVerifiedInstall
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 availableStars: 322kUpdated Claude CodeCodexVerifiedInstall