AgentSpec — A spec format AI coding agents can actually consume

Identity & intent

Title

A short, concrete name. Avoid vague verbs like "improve", "optimize".

ID (slug, auto)

Intent

An agent reads this first. If it's vague, the output will be too.

Actors (who/what interacts)

Contracts APIs, functions, or interfaces this spec implements

Acceptance scenarios Given / When / Then — these double as test cases

Invariants Must always be true

Out of scope Explicit "do NOT do" — agents wander without this

Constraints Performance, security, dependencies. Use numbers.

Existing context Files / symbols the agent should know exist

Files

Symbols

End-to-end walkthrough — Equity order entry ticket

A single stakeholder requirement travels through the full BMAD pipeline. Every agent receives a structured artifact — not English prose — from the one before it. Same spec, zero agent lock-in.

Stakeholder

Raw requirement — English, no structure

Jira Epic · OMS-201English

"Traders need to enter equity orders from the OMS UI. It should be fast, handle errors properly, and connect to our order intake API. Don't include algo orders."

Ambiguous intent, no error modes, no acceptance criteria, no scope boundary. This is what every team starts with — and what AgentSpec is designed to fix.

BA Agent

Produces feat-order-entry-ticket-v1.agentspec.yaml — committed to repo

specs/feat-order-entry-ticket-v1.agentspec.yamlYAML · repo

agentspec: "0.1" id: feat-order-entry-ticket-v1 title: "Equity order entry ticket — new order submission" intent: > Give a front-office trader a form to enter a new equity order (market or limit, buy or sell) and submit it to the OMS. Validates client-side and surfaces OMS rejections inline. Target: valid submittable order in under 5 keystrokes. out_of_scope: - "Order amendment and cancel — separate spec" - "Algo orders (TWAP, VWAP, POV) — separate spec" - "Options and futures — equities only in this spec" - "Order blotter / confirmation screen — separate spec" contracts: - name: "POST /orders" inputs: - {key: symbol, val: "string — ISIN or ticker"} - {key: side, val: "BUY | SELL"} - {key: qty, val: "integer 1..10,000,000"} - {key: order_type, val: "MARKET | LIMIT | STOP_LIMIT"} - {key: limit_price, val: "decimal | null"} - {key: tif, val: "DAY | GTC | IOC | FOK"} errors: - SYMBOL_NOT_FOUND - INSUFFICIENT_BUYING_POWER - INVALID_LOT_SIZE - OMS_UNAVAILABLE acceptance: - given: "trader enters AAPL, BUY, qty=100, MARKET, DAY" when: "they click Submit" then: "POST /orders called once, order_id shown, form resets in 500ms" - given: "LIMIT order with empty limit_price" when: "they click Submit" then: "inline validation error, POST /orders NOT called" - given: "OMS returns INSUFFICIENT_BUYING_POWER" when: "POST /orders responds" then: "inline error within 200ms, Submit re-enables, no navigation"

Version-controlled alongside the code. Every future commit referencing this spec ID is traceable to this exact artifact.

PM Agent — Linter gate

Quality score computed — objective gate decision, no gut check

CI linter outputCI check

AgentSpec Linter — feat-order-entry-ticket-v1 ────────────────────────────────────────────── Score: 94 / 100 0 errors · 1 warning · 2 info WARN intent "practiced trader" is not measurable. Suggested fix: "a trader who has submitted ≥1 order before" INFO constraints No p99 latency constraint on POST /orders. INFO context No symbol listed for account selector component. Gate decision: ✓ PASS score 94 ≥ 70 threshold · 0 hard errors Advancing to Architect with advisories attached.

✓ 0 errors 1 warning Score 94/100 Gate: PASS

PM Agent — Jira ticket

Spec compiled → Jira ticket body, pasted into OMS-247

OMS-247 · Jira description fieldJira

## Equity order entry ticket — new order submission **Spec ID:** `feat-order-entry-ticket-v1` · AgentSpec v0.1 --- ### Intent Give a front-office trader a form to enter a new equity order and submit it to the OMS. Validates client-side, surfaces OMS rejections inline. ### Out of Scope > The following are explicitly not part of this ticket. - Order amendment and cancel — separate spec - Algo orders (TWAP, VWAP, POV) — separate spec - Options and futures — equities only in this spec ### Acceptance Criteria **Scenario 1** - **Given:** trader enters AAPL, BUY, qty=100, MARKET, DAY - **When:** they click Submit - **Then:** POST /orders called once, order_id shown, form resets in 500ms **Scenario 2** - **Given:** LIMIT order with empty limit_price - **When:** they click Submit - **Then:** inline validation error, POST /orders NOT called **Scenario 3** - **Given:** OMS returns INSUFFICIENT_BUYING_POWER - **When:** POST /orders responds - **Then:** inline error within 200ms, Submit re-enables, no navigation ### Error Codes — all must be handled - `SYMBOL_NOT_FOUND` · `INSUFFICIENT_BUYING_POWER` - `INVALID_LOT_SIZE` · `OMS_UNAVAILABLE` --- *Generated by AgentSpec · Spec: `feat-order-entry-ticket-v1`* *YAML source of truth: specs/feat-order-entry-ticket-v1.agentspec.yaml*

Commit convention: feat/[OMS-247][feat-order-entry-ticket-v1]: implement order entry form — links commit → Jira ticket → YAML spec in one chain.

Architect Agent

Spec enriched with technical context — same schema, more precision

Architect enrichment notesenrichment

## Architect review — feat-order-entry-ticket-v1 CONSTRAINT ADDED post_orders_p99: "< 300ms at OMS API boundary" (PM advisory resolved) CONTEXT ENRICHED AccountPicker exists at src/components/AccountPicker/index.tsx → account_id field MUST reuse AccountPicker. Do not build a new selector. CONTEXT ENRICHED useDebounce exists at src/hooks/useDebounce.ts (200ms default) → useSymbolSearch must compose useDebounce. Do not write a new timer. CONTEXT ENRICHED Auth handled by axios interceptor in src/api/client.ts (Bearer + 401→SESSION_EXPIRED) → Component does not manage auth headers directly. INVARIANT ADDED "Form must not render if useSessionGuard returns isExpired=true — redirect to /login, preserve draft in sessionStorage key: order_entry_draft" Score after enrichment: 98 / 100 (0 errors, 0 warnings) Advancing to Developer Agent.

The Architect adds precision — not scope. Same AgentSpec schema, enriched with file paths, symbol anchors, and resolved constraints from PM advisories.

Developer Agent — Claude Code / Cursor / Aider

Receives compiled brief — implements exactly this, nothing more

Compiled Claude Code prompt briefClaude Code

You are implementing the following AgentSpec. Treat each section as a hard constraint. # Title Equity order entry ticket — new order submission # Intent Give a front-office trader a form to enter a new equity order and submit it to the OMS. Validates client-side, surfaces OMS rejections inline. Target: a trader who has submitted ≥1 order before reaches a valid submittable order in under 5 keystrokes from a blank form. # Out of scope (do NOT implement — tracked under separate specs) - Order amendment and cancel - Algo orders (TWAP, VWAP, POV) - Options and futures — equities only - Order blotter / confirmation screen # Contracts ## POST /orders Inputs: symbol · side · qty · order_type · limit_price · tif · account_id Outputs: order_id (UUID) · status · timestamp (ISO 8601) Errors (handle all by name): SYMBOL_NOT_FOUND · INSUFFICIENT_BUYING_POWER INVALID_LOT_SIZE · OMS_UNAVAILABLE # Invariants (must hold across all execution paths) - limit_price hidden and cleared when order_type is MARKET - Submit disabled while POST /orders is in flight — no double-submit - All error codes surfaced inline — no silent failures, no generic messages - Form must not render if useSessionGuard returns isExpired=true # Acceptance — all must pass before reporting done 1. Given AAPL/BUY/100/MARKET/DAY → Submit pressed Then POST /orders called once, order_id shown, form resets in 500ms 2. Given LIMIT with empty limit_price → Submit pressed Then inline error on limit_price, POST /orders NOT called 3. Given OMS returns INSUFFICIENT_BUYING_POWER Then inline error within 200ms, Submit re-enables, no navigation # Constraints - post_orders_p99: < 300ms at OMS API boundary - bundle_size: < 15 KB gzipped added to main bundle - accessibility: keyboard-navigable, aria-label on all inputs, errors are aria-live # Existing context (use — do not reimplement) Files: src/components/AccountPicker/index.tsx ← reuse for account_id src/api/orders.ts · src/api/client.ts ← axios interceptor handles auth src/hooks/useSymbolSearch.ts src/hooks/useDebounce.ts ← compose this, no new timer Symbols: ordersApi.submit · AccountPicker useDebounce · useSessionGuard # Process 1. Read every section before writing any code. 2. Implement contracts to satisfy acceptance scenarios verbatim. 3. Do not extend into anything listed under Out of scope. 4. All acceptance scenarios must pass before reporting done.

✓ Scope fenced by out_of_scope ✓ No agent lock-in — same spec compiles to Cursor or Aider ✓ Commit → Jira OMS-247 → YAML spec fully traceable

AgentSpec v0.1 — Schema reference

AgentSpec is a small, opinionated schema for describing a unit of work that an AI coding agent will implement. It deliberately requires fields that English specs leave out — explicit out-of-scope, measurable acceptance, named error modes — because those are the things agents miss.

Fields

required. Stable slug. Used in commit messages, PR titles, and audit logs. Auto-derived from title if omitted.

title

required. Short concrete name. Avoid weasel verbs ("improve", "optimize", "fix").

intent

required. 2–3 sentences. What are we building and why does a user care? Read first by every agent.

actors

recommended. Who or what interacts with the surface this spec describes. Often a user role, a calling service, or an external system.

contracts

required. The interfaces this spec implements — endpoints, functions, exported APIs. Each contract has name, inputs, outputs, and errors. Errors must be enumerated, not implied.

invariants

recommended. Properties that must always hold across all execution paths. Often security, data-integrity, or auditing rules.

acceptance

required. Given / when / then scenarios. Doubles as a test plan. Each "then" must be measurable.

context

recommended. Existing files and symbols the agent should be aware of. Prevents hallucinated re-implementations.

constraints

recommended. Performance, security, dependency, and operational limits. Use numbers. "p99 < 100ms" not "fast".

out_of_scope

recommended. The single most underused field in human-written specs. Without explicit fences, agents extend into adjacent features and you spend your review budget pruning.

Compatibility — no agent lock-in

AgentSpec is agent-agnostic by design. The agent landscape shifts every quarter. Your spec library should not have to change when it does. The same source spec compiles to:

A Claude Code prompt brief — structured, with explicit out-of-scope and acceptance up front
A Markdown spec for human review or Jira ticket body
Canonical YAML / JSON for storage in your repo, CI lint, or audit trail

Switching from Claude Code to Cursor to Aider means changing the compiler target, not rewriting the spec. In a BMAD pipeline, each agent stage can independently swap its runtime — the spec is the contract, the agent is the runtime.

Jira integration

AgentSpec and Jira are complementary, not competing. Each layer owns what it's good at:

.agentspec.yaml

Source of truth. Lives in your repo alongside the code. Linted in CI. Version-controlled. The audit-grade artifact — every commit can be traced back to the spec that authorized it.

Jira ticket

Workflow handle. Who owns it, what sprint it's in, current status, priority. Things the YAML doesn't model and shouldn't.

Jira output (this tab)

The bridge. Compile your AgentSpec to a Jira-ready Markdown body — paste it into the ticket description. Acceptance criteria, out-of-scope, contracts, and invariants all render as structured sections. The Spec ID in the footer links the ticket back to the YAML.

Recommended flow: BA agent produces the .agentspec.yaml → linter clears it → compile to Jira → paste into ticket description → Spec ID becomes part of the commit message convention (feat/[PROJ-123][feat-order-entry-v1]).

BMAD pipeline mapping

AgentSpec is the native contract format for BMAD (Business · Manager · Architect · Developer) multi-agent workflows. Each field maps directly to a BMAD stage:

id · title · intent

Written by the BA agent. Anchors every downstream agent's understanding of scope. A vague title here propagates vague code four stages later.

score (linter)

The PM agent's quality gate. Configurable threshold (e.g. reject if errors > 0 or score < 70). Machine-readable, no human interpretation required.

contracts · context · constraints

Read and enriched by the Architect agent. The architect adds file paths, symbol anchors, and performance thresholds — all in the same AgentSpec schema.

out_of_scope · acceptance

Consumed first by the Developer agent. The compiled Claude Code brief places these sections at the top of context so they set the boundary before any implementation begins.

id (hash)

Audit trail. The spec id is recorded in every commit message and PR description, linking production code back to the spec that authorized it. Required for regulated BMAD deployments.

Why AgentSpec

AI coding agents (Claude Code, Cursor, Aider, Cline) all read English specs and produce wildly different code from the same brief. The variance is not the model — it's the spec. English is ambiguous, ticket descriptions skip the boring parts, and the most important field of all — what NOT to do — is almost never written down.

AgentSpec is the smallest opinionated structure I could define that fixes this. Write it in a browser, lint it, then compile to whichever agent your team uses today. The format itself doesn't care which agent runs.

No lock-in to any specific agent. This is a deliberate design principle. The agent landscape shifts every quarter — Claude Code today, Cursor tomorrow, something new next year. AgentSpec sits above that churn. Your specs, your linter rules, your acceptance criteria, your audit trail stay stable regardless of which agent executes them. Switching agents means changing the compiler target, not rewriting your entire spec library.

In a BMAD pipeline, this means each stage (BA, PM, Architect, Developer) can independently adopt a different agent without breaking the handoff contract. The spec is the contract. The agent is the runtime.

Built by Umesh Kumar K V while delivering a broker-dealer trading platform via agentic SDLC. 20+ years across FIS, Caesars Sportsbook, and Wissen Technology. Anthropic-certified in MCP and Claude Code.

Roadmap

· Cursor .cursorrules and Aider system-prompt adapters

· VS Code extension with inline linting on .agentspec.yaml files

· GitHub Action: lint AgentSpec files in PRs, block on errors

· Spec-to-PR provenance — every PR commit links to the spec hash that produced it

· Test scaffolding — generate Jest/pytest skeletons from acceptance scenarios

· Enterprise governance edition: shared spec libraries, custom linter rules, audit trails (the paid tier)

AgentSpec in the BMAD Pipeline

BMAD (Business · Manager · Architect · Developer) is a multi-agent orchestration pattern where specialized AI agents hand work down a chain. AgentSpec is the inter-agent contract — the structured artifact each stage produces and consumes. Without it, every handoff is lossy English prose and the agent at the end of the chain guesses what the one at the start intended.

① Business Analyst

Produces the spec

Linter blocks bad output

→

② PM / Manager

Quality gate

Score ≥ threshold?

→

③ Architect

Reads & enriches

contracts · context · constraints

→

④ Developer

Compiles → ships

Claude Code / Cursor / Aider

What AgentSpec does at each stage

BA Agent

Produces a .agentspec.yaml instead of a vague English ticket. The linter fires before the handoff — a spec that scores below your threshold never reaches the next agent.

PM Agent

Validates the quality score (0–100). Machine-readable gate: reject if errors > 0, flag if score < 70. No human gut-check required, no ambiguity about what "good enough" means.

Architect Agent

Reads contracts, context.files, and context.symbols as anchors. Adds or refines constraints. Returns enriched spec in the same format — same schema, deeper detail.

Developer Agent

Receives the compiled prompt brief with out_of_scope and acceptance placed first in context. Stops exactly where the fence says to stop. Load the BMAD sample in the editor to see a real broker-dealer example.

Why this matters for regulated deployments

In banking, brokerage, and healthcare, every agent handoff needs an audit trail. The spec id links every commit back to the spec that authorized it — your compliance officer can answer "which spec produced this code?" for any line in production. That's not a feature you can retrofit onto an English ticket workflow.

Enterprise governance tier (shared spec libraries, custom linter rules, audit trail, on-prem) is in development. DM on LinkedIn if you'd buy this today.