Spec first delivery
Skill jpantsjoha/ai-native-developer-experience/.agents/skills/spec-first-delivery
Force plan, HLD, ADRs, and constraints to exist BEFORE any code is generated. Trigger when starting a new feature, epic, or significant change.From its SKILL.md
npx -y skills add jpantsjoha/ai-native-developer-experience --skill spec-first-deliveryAssembled from the repository path, not quoted from the project. Check it against their README if it does not work.
One thing to look at
- 11 stars11 stars. Stars are a popularity signal and not a quality one, but at this level it is likely that nobody has read this closely except its author, and you would be relying on your own review.
SKILL.md
3.3 KB, 726 tokens by cl100k_base, as published. Nobody here has run it
Spec-First Delivery
Review the spec harder than the code. The cheapest place to be wrong is the spec.
The harness runs in this order: spec → plan → tasks → code. Skipping the spec is not faster — it is a deferred rewrite.
When to use
- Any new feature or epic with more than ~1 day of effort
- Infrastructure or architectural changes
- Anything involving a new external dependency, data boundary, or API contract
- Any time an agent offers to "just start coding"
Procedure
- Establish the vision artifact — confirm the project's vision document exists and is current (e.g.
docs/VISION.mdor equivalent per project structure). If not, create or update it before proceeding. - Write the feature spec — document: what, why, who (user/actor), constraints, acceptance criteria, and out-of-scope. Reject vague specs ("improve performance") in favour of measurable ones ("p99 latency < 200 ms under 1k rps").
- Author or reference the HLD — a high-level design covering: components affected, data flows, integration points, and failure modes. Diagrams preferred (C4 or sequence).
- Create or update ADRs — one ADR per significant technical decision. Format: Context → Decision → Consequences (trade-offs). Number sequentially (
ADR-NNN). - Document constraints up front — security requirements, data residency, budget ceiling, compliance scope, team skill set. Constraints missed here surface as blockers late.
- Validate spec completeness — the spec is done when: acceptance criteria are testable, the failure mode is named, rollback is considered, and cost impact is estimated.
- Only then: generate the implementation plan and tasks. Hand the spec (not a prompt) to the agent.
Outputs
requirements/FEATURE_SPEC.md(or equivalent per project structure)architecture/decisions/ADR-NNN-<short-title>.md(one per decision)architecture/HLD-<feature>.md(if not already covered)- Updated project roadmap (e.g.
docs/ROADMAP.mdor equivalent per project structure) with new tasks or milestones
Guardrails
- No code without a spec. If an agent begins generating code before a spec exists, stop it and invoke this skill.
- Loose spec = confident but wrong output. A vague spec produces plausible-looking, wrong code. Tighten the spec first.
- Spec is not a prompt. The spec is a structured document with testable criteria; a prompt is a hint. Do not substitute one for the other.
- Context efficiency: Evaluate whether full spec documents are needed, or whether ADRs + plan mode provide sufficient context. Overhead should be proportional to risk.
Anti-rationalization table
| Excuse the agent makes | Counter |
|---|---|
| "I have enough context to start coding" | No spec = no acceptance criteria = no way to know if the output is correct. Write the spec. |
| "The spec will slow us down" | A missing spec causes rewrites. Rewrites cost more than specs. |
| "The requirements are obvious" | Obvious requirements are the ones most often wrong. Write them down and verify. |
| "We can spec it after the prototype" | Prototypes become production. Spec it now. |
What ships with it
Read from the repository
Just SKILL.md. No reference files, no scripts.
Gives 0 of the 12 instructions most plan spec skills give in 726 tokens
Counted across 1,360 of the 2,617 authors here whose files we hold, read 2026-09-06
- Ask one question at a timein 73 of 1360
- Write the spec using the templatein 22 of 1360
- Ask clarifying questions if neededin 19 of 1360, across 18 files
- Wait for user confirmation before proceedingin 19 of 1360
- Save plans to the plans directoryin 17 of 1360, across 13 files
- Check for product marketing context firstin 16 of 1360, across 5 files
- Read the plan file completelyin 16 of 1360
- Order tasks by dependencyin 16 of 1360
- Gather context from the conversationin 15 of 1360, across 9 files
- Explore the codebase instead of askingin 15 of 1360, across 13 files
- Wait for explicit user approvalin 14 of 1360, across 13 files
- Quiz the user on the breakdownin 13 of 1360, across 7 files
Said here and by no other author read
- Confirm the vision document exists and is current
- Write the feature spec with measurable criteria
- Author or reference the high level design
- Create or update architecture decision records
- Document constraints up front
- Stop agents generating code before a spec exists
Grouped from the skills themselves: near-identical wordings counted once, and counted by distinct author, so one author publishing three of these counts once. Length counted with cl100k_base; the agent that loads this file may tokenize it differently.