Spec Engineer

spec-engineer

Start here

1. Confirm the user needs a software specification, not a PRD, implementation plan, code review, or implementation patch.
2. Distinguish draftable from handoff-ready input: readiness requires sufficient source authority, applicable accepted constraints, and a named downstream consumer.
3. Identify the parent product, system, workflow, or architecture intent the spec is meant to constrain, or label that intent as missing before drafting.
4. Inspect accepted product and architecture context, domain constraints, assumptions, criticality, and blocking ambiguity before drafting.
5. Separate observable capability from support substrate; do not let scaffolding, APIs, schemas, tests, logs, or documentation stand in for claimed behavior.
6. Do not require layers, scaffolds, config, wrappers, or future extension points unless they are necessary for the current capability or explicitly labeled substrate with a dependent capability.
7. For medium/high-risk or architecture-impacting work, inherit accepted architecture constraints and route missing or new architecture decisions instead of choosing them in the spec.
8. Before creating or recommending a persistent implementation-ready spec, API spec, workflow spec, migration spec, spike spec, or verification map, check whether the current repository defines artifact conventions and follow them when present.
9. Choose the smallest specification depth that can guide correct implementation and verification for this task.

When to use this skill

• Creating or revising a specification that will guide software implementation.
• Turning a feature request, ticket, issue, PRD section, domain rule, integration requirement, API change, migration, workflow, or function behavior into implementation-ready requirements.
• Compressing vague source material into a compact spec with scope, behavior, constraints, acceptance criteria, anti-claims, and verification intent.
• Right-sizing the spec for anything from a single function or endpoint to a subsystem or whole product slice.
• Creating vertical-slice specs or spike specs when implementation needs bounded behavior, evidence, or decision-unblocking criteria.
• Assessing or revising whether a specification is honestly ready for a named downstream consumer.

When NOT to use this skill

• Writing a product PRD where product discovery, rollout, metrics, or business scope are the main concern instead of implementation-ready behavior; if available, route that work to prd-engineer.
• Checking code against an existing spec rather than authoring or revising the spec; if available, route that work to spec-conformance-reviewer.
• Reviewing whether an implementation delivers real capability instead of only substrate; if available, route that work to concept-conformance-reviewer.
• Implementing code directly when the user did not ask for a specification and the task is already unambiguous.
• Creating heavyweight governance, lifecycle records, project-management state, or delivery tracking artifacts instead of a specification document.
• Producing formal methods artifacts as the primary deliverable unless the user explicitly asks for that level of rigor.

Overview

Create a specification that helps an AI coding agent build correct software with fewer guesses.

The spec is not a governance artifact, a product pitch, or a verbose checklist. It is a compact set of statements and representations that narrows the allowed behavior of a system enough that implementation and verification can proceed without inventing missing requirements.

Before writing requirements, place the target inside its parent product, system, workflow, or architecture intent. A locally precise spec can still be wrong when it does not advance or protect that parent capability; if the parent intent is missing, record it as an assumption, gap, or blocking question instead of inventing it.

Input contract

Acceptable input can be loose, but it must be usable. A ticket, issue, free-form request, product note, API change, code behavior description, domain rule, or migration request can support a draft when it identifies the object, intended behavior, and source material. If the object and behavior are both missing, ask before drafting.

Capability vs substrate

Use these definitions directly:

• Capability is observable behavior by a user, operator, integration, or system: actor, trigger, system response, state/effect, and continuity.
• Substrate is supporting material such as storage, APIs, queues, schemas, adapters, prompts, tests, logs, generated files, documentation, or lifecycle records.

Capability is relative to the spec consumer. A public API contract is capability when API clients are the actors, but it is substrate when the claim is end-user checkout behavior. Substrate may be necessary, but a specification must not describe substrate as completed capability unless it enables demonstrable behavior. When a requested spec is actually substrate-only, label it that way and name the capability it supports.

Capability statement template

Use this shape as the center of the spec when behavior is claimed:

Given , when  does , if ,
the system MUST , creating or preserving ,
so that  holds.

Right-sized rigor

Default to the lightest spec that prevents costly implementation mistakes:

• a function or validation rule may need only inputs, outputs, rules, edge cases, examples, and acceptance;
• an endpoint usually needs request/response/error contracts and idempotency or retry semantics;
• a workflow usually needs states, events, guards, effects, invariants, and failure behavior;
• a system slice may need actors, entry points, interfaces, NFRs, compatibility, observability, and a verification map.
• trivial scope should use the compact 6-section template from the methodology reference.

Do not make the agent maintain process ceremony that does not improve code. Increase structure only when prose would hide ambiguity, omitted cases, contradictions, or unverifiable claims.

Criticality overrides size. A small authz rule, payment idempotency rule, data deletion path, or signing function may need invariants, multiple falsifiers, stronger verification, and explicit rollback/compatibility constraints even when the textual scope is tiny.

Workflow stages

Workflow stage: Frame the specification target

Turn vague intent into a bounded engineering target before writing requirements.

1. Identify the parent product, system, workflow, or architecture intent and state how this spec's behavior advances or protects it; if the spec is substrate-only, name the capability it supports.
2. Identify the system, subsystem, function, interface, actor, trigger, and production entry point when known.
3. State the capability claim with precondition and guard when relevant: Given , when does , if , the system MUST , creating or preserving , so that holds.
4. Apply a criticality lens: ask what the worst observable consequence is if the requirement is wrong, then increase rigor for security, money, data loss, compliance, safety, privacy, compatibility, or irreversible state.
5. Classify risk as low, medium, or high when the source material provides or implies it, and use that classification with criticality to choose spec depth.
6. List source material, authority, approval/readiness, and the named downstream consumer; resolve conflicts or mark them as open questions.
7. For medium/high-risk or architecture-impacting specs, capture linked PRD requirements, architecture constraints, ADRs, ASRs, delivery task brief, and existing conventions when available.
8. Name substrate that may be needed but is not itself the capability for this spec consumer; remember that a public API contract is capability when the API consumer is the actor.
9. Reject future-only substrate such as layers, scaffolds, config knobs, wrappers, or extension points unless a current requirement, accepted architecture constraint, or dependent capability needs it.
10. For changes to an existing system, capture the behavioral delta from current to target behavior, including compatibility, migration, and coexistence constraints.
11. Add initial anti-claims that keep the spec from implying broader behavior than requested.

Validation:

• The spec target is tied to parent intent, or missing parent intent is recorded as an assumption, gap, or blocking question.
• The target can be described without relying on implementation-only terms.
• The spec scope says what is in, what is out, and what remains unknown.
• Risk depth and inherited product, architecture, delivery, and specification context are explicit when they affect implementation.
• Source authority, readiness, named consumer, and resulting handoff status are explicit; the spec is not more ready than its inputs.
• Acceptance cannot be satisfied only by substrate when the claim is behavioral.
• Future-only substrate is absent, deferred by trigger, or explicitly labeled as support work for a named dependent capability.
• High-criticality scope has explicit invariants, stronger falsifiers, and a verification path beyond happy-path examples.

Workflow stage: Map behavior and constraints

Cover the behavior space before committing to normative statements.

1. Create a glossary before writing requirements for terms that repeat, carry roles, or are likely ambiguous.
2. Inventory main flows, alternate flows, failure paths, invalid inputs, boundary cases, permission cases, timing, retries, concurrency, ordering, idempotency, consistency, compatibility, and observability concerns that matter for the task.
3. Use systematic discovery techniques when memory is not enough, especially equivalence partitions, boundary values, state transitions, fault analysis, role/abuse cases, and concurrency probes.
4. Identify domain terms, states, events, entities, inputs, outputs, side effects, invariants, assumptions, external dependencies, and temporal promises.
5. Decide which unknowns block implementation and which can be recorded as explicit assumptions or gaps.

Validation:

• The behavior inventory includes the important non-happy paths for the scope.
• Hidden assumptions about external systems, ordering, time, roles, or persistence are explicit.
• Important invariants and failure semantics are not buried inside examples.
• Concurrency, ordering, idempotency, and consistency are treated as separate concerns when any one of them matters.

Workflow stage: Draft the compact specification

Produce a concise spec at an honest handoff status without becoming process-heavy.

1. Use the compact 6-section structure from the methodology reference for trivial scope; use the fuller structure only when the task needs it.
2. Include Architecture Context only when risk or affected boundaries make it useful for implementation correctness.
3. For spike specs, specify the question, hypothesis, validation harness, success/failure criteria, output evidence, and next decision instead of pretending the spike delivers product behavior.
4. Write a scope statement, parent intent or supported capability, glossary, capability or behavior statement, assumptions, and anti-claims.
5. Write atomic normative requirements with source trace, explicit subject, modality, action, object, condition, and measurable constraint where relevant.
6. Use the representation-fit table from the methodology reference; prefer invariants for always-true properties, and use contracts, tables, state models, NFRs, and examples only where they materially reduce ambiguity.
7. Add positive acceptance criteria, negative criteria, falsifiers, and a verification map for each important requirement.
8. Define requirement lifecycle status when revising an existing spec: new, changed, superseded, deprecated, or removed.
9. Record open questions and gaps without letting non-blocking gaps stop useful specification work.

Validation:

• Every important requirement is falsifiable by demonstration, inspection, analysis, contract validation, schema validation, property-based checks, example-based tests, or another explicit method.
• If a requirement can produce two independently verifiable acceptance criteria, it has been split.
• Acceptance criteria prove real behavior and include at least one negative or falsifier for self-deception risk.
• Anti-claims prevent scope inflation and make clear what the spec does not promise.

Workflow stage: Audit and right-size

Improve precision without adding ceremony that distracts from building correct code.

1. Run the Quality audit checklist from the methodology reference before reporting done.
2. Check whether the spec discovered architecture drift; stop for blocking drift or record an architecture delta needed when implementation can safely proceed.
3. Scan for ambiguous terms, vague adjectives, compound requirements, hidden implementation decisions, duplicate rules, missing failure behavior, missing invalid inputs, and examples that contradict rules.
4. Check self-deception patterns such as tautological acceptance, mock-driven success, single-actor blindness, hidden retroactive scope, and completion bias.
5. Remove sections, tables, or process language that do not constrain implementation or verification.
6. Strengthen under-specified NFRs with metric, threshold, measurement object, and measurement window.
7. Apply the Stop rules before finalizing.

Validation:

• The final spec is as small as possible while still reducing implementation guesses.
• The spec has no known contradictions between prose, rules, examples, tables, schemas, or state transitions.
• Architecture constraints are inherited or routed; they are not silently invented.
• Remaining risks are visible as assumptions, gaps, anti-claims, or open questions.

Interop priority

• product scope, users, scenarios, success criteria, and product acceptance framing: prd-engineer. prd-engineer owns product intent and gaps; this skill consumes accepted product basis when producing implementation-ready behavior.
• architecture boundaries, ASRs, pattern decisions, ADRs, quality scenarios, and architecture drift: architecture-engineer. architecture-engineer owns architecture decisions and handoff; this skill inherits those constraints and routes drift back instead of deciding architecture inside a spec.
• vertical slices, task briefs, sequencing, dependencies, and risk routing: delivery-planner. delivery-planner owns decomposition and sequencing; this skill may specify a slice or task but does not create the delivery plan.
• checking implementation evidence against an existing spec: spec-conformance-reviewer. spec-conformance-reviewer owns conformance review after a spec exists; this skill owns authoring or revising the spec.
• independent design-time concept alignment and false-capability risk: concept-conformance-reviewer. concept-conformance-reviewer owns the independent verdict; this skill owns repairing the specification requirements and acceptance criteria.
• framework, security, data, financial, regulatory, infrastructure, or other specialized technical facts: the relevant domain skill. domain skills own specialized facts and constraints; this skill records accepted facts without inventing them.

Gotchas

• high — A spec is useful only if it constrains observable behavior; a template, section list, or artifact path is substrate until the requirements are precise and falsifiable.
• high — Do not let acceptance criteria pass through mocks, generated docs, schemas, wrappers, or tests alone when the claim is user-, operator-, integration-, or system-observable behavior.
• high — Do not make a locally precise spec that drifts from the parent product, system, workflow, or architecture intent without calling out the conflict.
• high — Do not force every section onto small tasks; use the smallest structure that removes implementation ambigui

…

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: kostysh
• Source: kostysh/skills
• License: MIT

Install and usage instructions live in the source repository linked above.