# Spec Create > Turns a stated task or captured brief into a spec's requirements when no tracker item covers it, then hands to spec-plan. Tracker intake is spec-pull. - Skill: `ainova-systems/spec-create` (Agent Skill) - Install (CLI): `npx skillmds@latest add ainova-systems/spec-create` - Raw SKILL.md: https://api.skillmd.com/api/skills/ainova-systems/spec-create/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Productivity - Author: ainova-systems (https://skillmd.com/u/ainova-systems) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/ainova-systems/spec-create --- # Create a Spec The manual intake, for a change no tracker item covers: something settled in a conversation, a decision from a call, a defect found in passing. Ambiguous scope triggers a grill - a relentless, checkpointed interview. When a tracker item exists or could be made, `spec-pull` is the intake instead - it carries provenance and drift keys this path cannot, so say that out loud before proceeding. It produces `NNN-requirements.md` and hands to `spec-plan`, which writes the plan beside it - the same second half `spec-pull` hands to, so the chain reads identically whichever intake ran. This skill both **creates** a new spec and **updates** an existing one (re-scope when requirements change): in update-mode, re-read the current requirements, apply the delta, and keep a one-line history note. ## Resolve the docs structure (profile, then learn, then default) 1. Profile pins it: `specs_dir`, `features_dir`, `spec_grouping` (`flat` | `quarterly`) in `dev-project-profile.md`. 2. Else learn from the project: locate the existing spec/plan area and read the most recent shipped spec end-to-end - it is the structural template. 3. Greenfield default: `docs/specs/NNN-/` with `NNN-requirements.md` + `NNN-plan.md` - both files carry the folder's number (`spec-discipline`); `quarterly` grouping nests as `docs/specs/-Q/NNN-/`. If the project has no docs substrate yet (no `model.md` / `features/` / `specs/`), run `spec-init` first to scaffold it - this skill writes one change spec into an existing structure, it does not bootstrap the whole tree. ## Steps 1. **Deep learning first.** Read the feature doc for the touched area (`features_dir`), the project rules, the decision records, and the closest shipped sibling spec end-to-end. Note rules the request might contradict - rules win; flag conflicts now. 2. **Grill the owner (when scope is ambiguous).** Interview relentlessly until shared understanding - one question at a time, in the `spec-discipline` question shape: sourced options with a recommended answer inferred from code and docs, an explicit "keep it open", and room for the owner's own answer. Walk the decision tree dependencies-first. Grill rules: - A question the codebase or docs can answer is answered there, never asked. - Sharpen fuzzy terms against the project's glossary/domain model; surface code-vs-statement contradictions immediately. - Stress-test domain relationships with concrete edge-case scenarios that force precise boundaries. - **Checkpoint after every answer** into the spec draft files - the spec, not the conversation, is the source of truth. - Unanswerable item - record it under `## Open questions` with its owner and move on; don't stall. - Clear, small scope - skip the grill and say so. 3. **Write `NNN-requirements.md`.** Acceptance criteria in EARS form (`WHEN THE SYSTEM SHALL `), narrowed to this change. Durable behavior stays in the feature doc; this file holds only the delta. **Keep the source verbatim under `## Source as captured`**: a board task can be re-read, a chat cannot, and a summary there is a spec whose requirements can never be traced back. 4. **Cross-link.** Requirements point to the feature-doc section they narrow. Open business questions stay in the feature doc; the spec tracks only this change. Decisions that crystallised during the grill and pass the ADR gate go to `spec-decision`. 5. **Hand to `spec-plan`.** Quality pass first: no class names or code in requirements, criteria testable, every grill answer persisted in the file rather than left in the conversation. Then state the requirements path plus a short summary, leading with any open questions, and continue into `spec-plan` - the requirements alone are not executable, and `spec-execute` refuses without a plan. ## Verify - The spec folder holds `NNN-requirements.md` carrying the folder's number; every criterion is testable and traceable to the captured source; open questions use the three-part shape; the run ends by naming `spec-plan` as the next step. ## Scope / hand-off - Intake from a tracker item - `spec-pull`. Writing the plan - `spec-plan`. Plan fact-checking - `spec-validate`. Resolving open questions - `spec-answer`. - Code, branches, PRs - out of scope: `spec-execute` owns execution. - Decisions made while grilling - `spec-decision`. ## Constraints - A spec is required only past the threshold (multi-module, contract change, migration risk, new feature). For a small clear task, say so and offer direct execution. - Never invent structure: the closest shipped sibling spec is the template. No sibling and no profile - use the default and say so. - Never start implementation in this skill, even the "obvious" parts.