absolute-spec
Lightweight standalone design spec for AI coding agents: codebase scan → bounded clarify pass (3–5 questions, not a grill) → reviewed design doc written to docs/plans/ → independent scored review → stop. No task board, no build. Use when you want a spec to discuss, hand off, or review before committing to implementation. Chains into absolute-work when ready to build. Triggers on "absolute spec", "write a spec", "spec out this feature", "draft a design doc", "I want a spec to hand off / review, don't build it yet".
maddhruv · 已有 AI 审核记录
安装与使用
运行命令前先阅读来源与依赖说明。复制命令不会自动安装或执行。
npx skills add maddhruv/absolute --skill absolute-spec技能说明
name: absolute-spec version: 0.5.0 description: > Lightweight standalone design spec for AI coding agents: codebase scan → bounded clarify pass (3–5 questions, not a grill) → reviewed design doc written to docs/plans/ → independent scored review → stop. No task board, no build. Use when you want a spec to discuss, hand off, or review before committing to implementation. Chains into absolute-work when ready to build. Triggers on "absolute spec", "write a spec", "spec out this feature", "draft a design doc", "I want a spec to hand off / review, don't build it yet". category: workflow tags:
- workflow
- spec
- specification
- planning
- design platforms:
- claude-code
- gemini-cli
- openai-codex
- mcp user-invocable: true argument-hint: "[target]" license: MIT maintainers:
- github: maddhruv
Start your first response with the 📋 emoji.
Absolute Spec
Absolute Spec turns a fuzzy intent into a reviewed design-spec document — then
stops. It is the planning artifact of work, lifted out of the full lifecycle: scan
the codebase, ask only the questions the code can't answer, write the spec, run an
independent scored review, and hand back a doc you can discuss, hand off, or feed into
/absolute work to build.
It is deliberately lightweight. No relentless interview, no task board, no decompose, no execution. One deliverable: a spec good enough that an unfamiliar developer could build from it.
When to use this command
Use spec when:
- You want a design spec to discuss, review, or hand off — not build right now.
- You need to think a feature through on paper before committing to implementation.
- A teammate or another agent will do the building from your spec.
- You want a fast, reviewed design doc without the full phase-gated lifecycle.
Do NOT use spec when:
- You want to design AND build in one flow → use
/absolute work(spec is its Phase 2, followed by decompose + safe-wave execution). - You're documenting code that already exists / already shipped → use
/absolute docs(reference/explanation docs, not a forward design). - The change is a one-line obvious fix needing no design.
The line vs work: spec produces a doc and stops; work produces a doc and then
builds it. If you're unsure whether you'll build it now, start with spec — you can
chain into work afterward and it will pick the spec up.
Key Principles
- Codebase before questions. Read what exists first; ask only what code can't answer.
- Bounded, not relentless. A short clarify pass (3–5 questions), not the depth-first
grill
workruns. Batching questions is fine. - The spec is the deliverable. Quality matters more here than anywhere — keep the independent scored review.
- Reuse, don't reinvent. Template, scaling rules, and review rubric come from
absolute-work'sreferences/spec-writing.md. This command is the thin flow around them. - Stop after review. No code, no board, no execution. Hand off cleanly.
- Never auto-commit. Write the spec file and report; the user commits.
The Flow
SCAN ─→ CLARIFY ─→ WRITE ─→ REVIEW ─→ HANDOFF
No hard gates between steps (that's work). The one checkpoint is the clarify pass —
ask, get answers, then proceed straight through to a reviewed spec.
Step 1 — SCAN
Ground the spec in reality before asking anything.
- Convention detection — read cached config first: if
.absolute.config.jsonor~/.absolute/config.jsonexists (from/absolute init), resolve the effective config (project file → globalprojects["<cwd>"]→ globaldefaults) and use itsconventions, detecting only what's missing. No config → soft-suggestinitand runwork's Codebase Convention Detection table (package manager, language/runtime, test runner, linter, build system, directory conventions; seeabsolute-work's SKILL.md under Codebase Convention Detection). The spec must speak the project's real stack, scripts, and paths. - Deep context scan — read what exists:
docs/(README first), rootREADME.md,CLAUDE.md,CONTRIBUTING.md,docs/plans/(overlapping/related designs), recent commits (last 10–20), package manifests, and the directories the feature touches. - Synthesize — state what you learned in 2–4 lines (stack, relevant existing code, any overlapping prior design). Do not dump a file listing.
Detect the work type (feature / refactor / greenfield / migration) only enough to
shape the spec — spec does not run the full per-type question banks.
Step 2 — CLARIFY (bounded pass)
Ask only the questions the codebase genuinely cannot answer — the preference and
scope forks. Cap at 3–5 questions; batching is allowed (one AskUserQuestion call
with multiple questions where available).
Good questions to ask (when code can't answer them):
- Scope boundary — what's in v1 vs explicitly deferred.
- Behavior forks — real-time vs batch, sync vs async, the genuine "which way" decisions.
- Data/contract shape — only where the design hinges on it and code gives no signal.
- Non-goals — what this explicitly will NOT do.
Do NOT ask: anything a config, manifest, test file, or existing pattern already states. When the code answers it, say so in the spec instead of asking.
If the user said "no questions, just draft it" — skip to WRITE and capture every guess
in an ## Open Questions / assumptions section instead.
Step 3 — WRITE
Write the spec to <specDir>/YYYY-MM-DD-<topic>-design.md (<topic> = short kebab-case
slug). <specDir> is preferences.specDir from config when present, else docs/plans.
Use the template, section-scaling rules, writing style, and Decision Log format
from absolute-work's references/spec-writing.md — that file is the single source of truth;
do not restate it here, load it. In particular:
- Pick th