Spec

Spec (Spec-Driven Development)

Overview

Create a stable “source of truth” for agents and humans: write specs with testable acceptance criteria and keep them aligned with implementation.

This skill treats specs as operational tooling: they prevent scope drift, enforce invariants, and make AI iteration converge.

Core Idea

• Specs define what must be true (contracts, scenarios, invariants, NFRs), not “how we coded it”.
• Plans/tasks define how we’ll get there (phases, work breakdown, acceptance per task).
• Code + tests are the proof.

Where Specs Live (Opinionated)

Use one (or both) of these:

• System specs: specs/*.md for cross-service rules and shared constraints (auth, observability, eventing, product scope).
• Decision records: specs/decisions/*.md for significant choices (trade-offs, migrations, taxonomy, compatibility).
• Service spec bundle: apps//spec/ for service-local truth:
• spec.md: requirements and acceptance scenarios
• contracts/: OpenAPI/proto/WS message contracts
• data-model.md: domain entities + storage boundaries
• plan.md: phases and wiring/structure
• tasks.md: checklist-style backlog with acceptance criteria
• quickstart.md: how to run/verify the service in dev

Chooser (What Spec Artifact To Write)

• Cross-service rule or shared constraint (auth, observability, eventing, product scope): write/update a system spec (specs/NNN-.md).
• Significant trade-off or migration decision: write a decision record (specs/decisions/NNN-.md).
• New or changed service behavior: write/update the service spec bundle (apps//spec/).
• API/contract change (new endpoint, changed schema, new event): update contracts (contracts/: OpenAPI/proto/WS docs) in the spec bundle.
• Task breakdown for implementation: update tasks.md in the spec bundle (or specs/tasks.md for repo-level backlog).
• Minor behavior tweak within existing contracts: update acceptance scenarios in the existing spec; no new artifacts needed.

Inputs / Outputs

Inputs: Plan output — objective function, scope (optional); archobs JSON — cluster boundaries, risk scores; forecast lifecycle data (if pinning external dependency contract). Outputs: Spec artifacts (service spec, API contracts, ADRs, task lists). Consumed by testing (acceptance scenarios as test sources), plan (task breakdown), finish (intent artifact check).

Clarifying Questions

• Is this change scoped to one service or does it cross service boundaries?
• Does it change externally visible behavior (API shapes, error codes, event schemas, auth rules)?
• Are there existing specs/contracts that should be updated vs creating new ones?
• Who are the consumers of this contract (other services, clients, external partners)?
• Is backward compatibility required, or can we make breaking changes?

Workflow

1. Load archobs data (before spec writing begins):

``bash archobs show clusters --format json archobs show risks --format json ``

Use in spec writing:

• Ensure spec contracts honor existing cluster boundaries. If the spec introduces a new boundary that cuts across a cluster with cohesion > 0.60, flag the conflict — the spec is fighting natural structure.
• Files with risk > 0.5 in the spec's scope warrant stricter acceptance criteria and testing requirements.
• Clusters with leakage > 0.20 that the spec touches may need explicit boundary contracts (interface types, Facade).

If archobs artifacts are missing: run archobs report or note as a gap. Do not block spec writing on archobs — the spec can be amended when data becomes available.

0b. Versioning guidance from forecast (conditional — run when the spec pins an external dependency contract such as an API version, SDK, or protocol):

``bash intel forecast # lifecycle phase for the dependency ``

Decision mapping: See [Lifecycle Decision Mapping — Spec: Versioning Strategy](../references/lifecycle-decision-mapping.md#spec-versioning-strategy) for lifecycle phase → versioning strategy table.

1. Decide the scope:

• One service? write/update the service spec bundle.
• Cross-service or product-wide? write/update a system spec.

1. Write the objective function up front:

• goal, constraints, anti-goals
• boundary (in/out) and time horizon

1. Externalize the system sketch:

• actors + incentives
• key flows (work/data/risk)
• top constraints/bottlenecks

1. Write acceptance-first:

• user story + “independent test”
• acceptance scenarios (Given/When/Then)
• edge cases and invariants (“constitution requirements”)

1. Lock down contracts:

• HTTP/gRPC schemas, message types, error codes, idempotency keys
• versioning rules and backward compatibility expectations

1. Add non-functional requirements (NFRs) that matter:

• latency budgets, concurrency, durability, audit, privacy
• observability and resilience requirements (trace/log/metrics, timeouts/retries/idempotency)

1. Add a compact decision table:

• options considered (include baseline/no-change)
• what is optimized vs knowingly worsened
• kill criteria / reversal trigger

1. Stress-test the decision (if 2+ viable approaches exist; skip for single viable approach):

• Assumptions: What are facts vs assumptions? Which assumption is least certain — how will we validate it? Cross-reference with archobs data from step 0 and versioning guidance from step 0b (if applicable). (attach to decision table)
• Second-Order Effects: What happens next week / next quarter / next year? What new load, toil, coupling, or failure mode does this create? If this fails in 6-12 months, what likely caused failure? Cross-reference with archobs data from step 0 and versioning guidance from step 0b (if applicable). (attach to decision table)
• Opportunity Cost: What are we saying "no" to? Are we favoring this due to sunk cost, familiarity, or novelty? (attach to decision table)
• If probe output already exists from an earlier Define-stage skill in this flow (including workflow orchestration), refine it instead of re-running.

1. Add a measurement ladder:

• decision being measured
• leading indicators (early signal)
• lagging outcomes (business/ops)
• instrumentation sources + review ritual (owner/cadence/action trigger)

1. Break it into tasks with acceptance:

• keep tasks small and orderable
• each task has an observable acceptance check

1. Implement and keep docs honest:

• if implementation forces a change in behavior, update specs first
• keep quickstarts and contracts current

Minimum viable execution

When context or time is constrained, these are the load-bearing steps:

1. Decide scope (step 1) — one service vs cross-service.
2. Write acceptance scenarios (step 4) — Given/When/Then with edge cases and invariants.
3. Lock down contracts (step 5) — HTTP/gRPC schemas, error codes, versioning rules.
4. Break into tasks with acceptance (step 10) — each task must be verifiable.

Steps that can be cut under pressure: system sketch (step 3), NFRs (step 6), decision table (step 7), measurement ladder (step 9).

Guardrails

• “No spec, no change”: don’t implement major behavior without updating the spec surface.
• Don’t hide requirements in code; put them in spec.md where agents can find them.
• Keep contracts stable; prefer additive changes and version explicitly when you can’t.
• Write down non-goals to stop scope creep.
• For non-trivial decisions, record opportunity cost explicitly to avoid accidental scope drift.
• No metric without a named decision and review ritual.
• If a design cannot be measured cheaply enough to guide weekly decisions, treat that as a constraint and simplify.

Common failure modes

• Writes the spec after implementation — the spec becomes documentation of what was built, not a source of truth that guides what to build.
• Over-specifies implementation details instead of boundary contracts — specs should define what must be true (response shapes, error codes, invariants), not how to code it.
• Doesn't version contracts when making breaking changes — consumers break silently because the contract didn't signal the incompatibility.
• Spec doesn't match actual code — spec drift accumulates when implementation changes aren't reflected back to specs.

References

• Templates: [references/templates.md](references/templates.md)
• Spec quality checklist: [references/checklists.md](references/checklists.md)
• Structured-thinking probes + templates: [../references/](../references/) (checklists for inline probes, templates for escalation)
• Architecture choices: [architecture](../architecture/SKILL.md)
• In-process pattern choices: [design](../design/SKILL.md)
• Typed boundaries/errors/lifetimes: [typescript](../typescript/SKILL.md)
• Consumer-visible tests: [testing](../testing/SKILL.md)

Output Template

When using this skill, return:

• Scope + objective: boundary, constraints, anti-goals.
• Artifacts created/updated: exact spec files (and contracts/ADRs when relevant).
• Decision summary: options considered, selected option, trade-offs, kill criteria, and assumptions (facts vs assumptions, opportunity costs).
• Measurement ladder: leading + lagging indicators, owner/cadence/action trigger.
• Verification plan: concrete checks/commands that prove acceptance scenarios and failure expectations.
• Next implementation tasks: ordered checklist with observable acceptance per task.

Source & license

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

• Author: bricerising
• Source: bricerising/enterprise-software-playbook
• License: Apache-2.0
• Homepage: https://bricerising.github.io/enterprise-software-playbook/

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