emanoeI Spec Skill
Spec does not generate code. Spec protects the decision before code exists. Spec is a mandatory decision pipeline for coding agents. Spec is not a documentation scaffold. Spec is not anti-vibecoding. Spec helps users and agents move faster with fewer avoidable mistakes.
Scale the depth to the request. Use the full pipeline for features, refactors, repairs, integrations and other changes with product or regression risk. For a small, local and reversible change, keep the same safety checks concise and do not create unnecessary task packs or long reports.
Spec is invoked inside coding agents, not as a shell command. The terminal is only for installation, diagnostics and CI checks.
Before answering any $spec, /spec or plain Spec request, inspect .spec/CONTEXT.md, .spec/PRODUCT.md and .spec/RULES.md when they exist. Read the remaining context files only when the request touches their subject. Use modules/request-depth.md to choose lightweight, standard or guarded before loading other modules.
When producing a full implementation prompt, do not finish without:
- reading
.spec/ - domain research
- work classification
- Foundation Score assessment
- Spec Score assessment
- red flag detection
- project impact analysis
- existing behavior preservation
- regression risks
- MVP slice
- decision ledger update
- agent task pack when useful
- rollback plan
- minimum test checklist
- context update suggestion
If the user needs to memorize the workflow, Spec failed.
If .spec/ does not exist, tell the user to run npx spec-skill install --all from the project root and restart the agent.
If .spec/ exists but project context is empty, run the agent-side init flow before producing implementation prompts.
Never generate a final implementation prompt without checking the Spec context first. For standard and guarded requests, never skip relevant red flags, project impact, non-regression or memory updates. For lightweight requests, cover only the focused impact and non-regression checks needed by the change.
Commands
All commands are invoked inside the active agent:
| Command | Purpose |
|---|---|
init |
Create initial .spec/ project memory from a short conversation. Read commands/init.md. |
document |
Inspect the current repository and update .spec/ memory. Read commands/document.md. |
refine |
Harden rules, risks, decisions and prompt requirements. Read commands/refine.md. |
check |
Review whether Spec context is strong enough before implementation. Read commands/check.md. |
help |
Explain Spec and its commands briefly. Read commands/help.md. |
<request> |
Run the full decision pipeline and produce a safer implementation prompt |
Accepted invocation styles:
- Codex:
$spec init,$spec build a finance SaaS - Claude/Cursor-style agents:
/spec init,/spec build a finance SaaS - If the agent receives
spec initin plain text, treat it the same way.
Agent Command Dialect
Use the command style of the active agent:
- Codex: recommend
$spec ... - Claude Code: recommend
/spec ... - Cursor: recommend
/spec ... - Generic agent: recommend
spec ... - Unknown agent: recommend the same command style the user used.
Never tell a Claude Code user to run $spec.
Never tell a Cursor user to run $spec.
Never tell a Codex user to run /spec unless they used slash commands first.
Do not tell the user to type /spec in the operating-system terminal.
Do not require spec start for normal use.
Internal Architecture
Treat Spec as this internal engine:
- Input Layer
- Context Loader
- Decision Engine
- Vibecoding Fit
- Domain Research
- Foundation Pass
- Product Gap Pass
- Protection Layer
- Foundation Score
- MVP Slicer
- Spec Score
- Decision Ledger
- Prompt Compiler
- Agent Task Pack
- Memory Writer
Mandatory Passes
For standard and guarded /spec requests, run the applicable passes below. Lightweight requests use only request depth, work classification, focused protection, acceptance criteria and tests.
Vibecoding Fit Spec should optimize scope, stack, phases and prompt shape for coding agents and novice vibecoders. It should prefer proven, incremental, testable implementation over unnecessary architecture complexity.
Foundation Pass Spec should act like a product owner and senior engineer. It should propose the safest agent-friendly stack, folder structure, boundaries, validations, client/server responsibilities and architecture baseline for the request.
Product Gap Pass Spec should use
.spec/PRODUCT.mdand the rest of.spec/to find missing flows, weak business rules, undefined statuses, risky exceptions and product gaps.Protection Pass Spec should protect the project from dangerous requests, regressions, unjustified rewrites, unsafe integrations and weak rollback planning.
Prompt Pass For standard and guarded work, only after the applicable passes above should Spec compile the final implementation prompt into
.spec/prompts/YYYY-MM-DD-short-request.md. Do not paste the full prompt body in chat when file editing is available.Score Pass Spec should estimate readiness across context, domain, rules, security, regression and tests. The score should shape the verdict, not become a long report.
Foundation Score Pass Spec should score whether the project foundation is strong enough for the requested work. If the base is weak, Spec should narrow the scope or hold the prompt instead of pretending the request is safe.
MVP Slice Pass Spec should reduce broad requests into the smallest useful Phase 1. Future work belongs in
Do not implement yet, not in the first coding-agent session.Decision Ledger Pass Spec should record important product and architecture choices in
.spec/DECISIONS.md. The goal is future-agent memory, not bureaucracy.Agent Task Pack Pass When a request is larger than one safe change, Spec should create ordered task files in
.spec/tasks/. The chat answer should point to the prompt and task directory instead of carrying the whole plan.
The user should not need to trigger these layers manually. The selected pipeline is automatic. Do not force standard or guarded artifacts onto a lightweight request.
Public Flow
- Install from terminal with
npx spec-skill install --all - Restart the coding agent
- Onboard inside the agent with that agent's command dialect.
- Use inside the agent with that agent's command dialect.
Routing
Read router.md first.
Then follow the relevant module instructions.
Output Rule
Every /spec response must stay short, direct and implementation-oriented.
Use short bullets.
Do not write a long essay.
Do not add motivational filler.
Do not dump the full implementation prompt in chat.
Lightweight requests are chat-only. Do not create prompt, task, session or memory artifacts unless the request is escalated first.
For standard and guarded requests, create a prompt file in .spec/prompts/ when it materially improves implementation and point the agent to it.
Use the output contract in output-contract.md.