spec-first-delivery

Estrelas10

Forks4

Atualizado20 de julho de 2026 às 10:28

Force plan, HLD, ADRs, and constraints to exist BEFORE any code is generated. Trigger when starting a new feature, epic, or significant change.

Instalação

Instalar com Codex ou Claude Copie este prompt, cole no Codex, Claude ou outro assistente e deixe que ele revise a página da skill e instale para você.

Fonte

jpantsjoha

jpantsjoha/ai-native-developer-experience

Abrir repositório GitHub Ver repositórios do creator

Download

Ocupações relacionadasSOC

Baseado na classificação ocupacional SOC

Desenvolvedores de softwareInformática e Matemática·SOC 15-1252

SKILL.md

readonly

name	spec-first-delivery
description	Force plan, HLD, ADRs, and constraints to exist BEFORE any code is generated. Trigger when starting a new feature, epic, or significant change.

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.md or 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.md or 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.

Mais deste repositório

mesmo repositório

operating-model-bootstrap

jpantsjoha/ai-native-developer-experience

Bootstrap or harden a project's operating model for mixed human and AI delivery teams. Use when starting a repository, adopting an agent harness, defining authority and risk tiers, coordinating parallel agents safely, binding evidence and review to an exact candidate, or correcting fragmented rules that prevent coherent, consistent, complete delivery.

2026-07-2310

the-architect

jpantsjoha/ai-native-developer-experience

Architecture decisions, trade-off analysis, and ADR authoring. Trigger when a significant technical decision needs to be made, documented, and owned — not when an implementation detail needs a choice.

2026-07-2310

delivery-orchestrator

jpantsjoha/ai-native-developer-experience

Decompose an epic into atomic parallelizable tasks and route each task to the right skill. Use this as a meta-router when you have more than one skill available and need to decide which applies. Trigger at the start of any multi-track epic or when the skill count in your harness exceeds ~12.

2026-07-2310

governance-guardrail

jpantsjoha/ai-native-developer-experience

Check proposed stack, data flows, cloud choices, and delivery controls against declared enterprise policies, compliance frameworks, and security controls. Trigger at R2/R3 risk classification, before locking architecture decisions, or when the operating profile names a governance pointer.

2026-07-2310

release-manager

jpantsjoha/ai-native-developer-experience

Govern the SemVer release process — versioning discipline, tag-based GitHub releases, changelog hygiene, and the ADR that confirms the release strategy is agreed. Trigger when setting up a release process, before a first public release, or when release practice has become inconsistent. Owned by delivery-orchestrator.

2026-07-2310

using-the-harness

jpantsjoha/ai-native-developer-experience

Session-start orientation for this team harness. Load first, before any work. Explains the operating contract, when each skill triggers, and how installed companion plugins supply agent-craft capabilities while this harness supplies the team contract. Trigger at the start of every session and whenever unsure which skill applies.

2026-07-2310

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.md or 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.md or 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.