PRD: Agent Specification & Validation Framework

@bradygaster

PRD: Agent Specification & Validation

@bradygaster — Dina's team put together a comprehensive PRD for adding formal agent specification and pre-deployment validation to Squad. This fills a significant gap: skills have a spec and 80+ tests; agents have neither.

Why this matters

No framework in the ecosystem (including Microsoft's own agent-framework, autogen, and the new Agent-Pex) does pre-deployment structural validation of agent definitions
Squad's markdown-first charter format is genuinely novel — richer than any YAML/JSON spec
This is an opportunity to own unoccupied territory

What's in the PRD

Phase	Scope	Effort
Phase 1	Charter spec — YAML frontmatter + 4 required markdown sections	1.5 days
Phase 2	`squad doctor` validation — 10 checks (6 fail / 4 warn), 3 tiers	2 days
Phase 3	Test fixtures — 80+ tests matching skills test patterns	1.5 days
Phase 4	Registry enhancement — version, skills[], tools, handoffs fields	1 day (deferred)

Strategic positioning

The PRD includes a "Design for Export" analysis — start internal, architect so the spec CAN become an open standard later (like Oracle did with Agent Spec, Anthropic did with MCP). Key differentiator: narrative charter + persistent history + pre-deployment validation — no other framework combines all three.

Industry research included

8 emerging standards analyzed (Oracle Agent Spec, OAF, A2A Agent Card, CrewAI, OpenAI SDK, AutoGen, OASF, Moca ADL)
Microsoft ecosystem gap confirmed (agent-framework, autogen, Agent-Pex — none do structural validation)
NIST AI Agent Standards Initiative tracked
Team review: 4/4 approved with notes

Full PRD

The complete PRD (~35 KB) is in the project management repo. Key sections:

Executive Summary + industry context
Strategic Positioning (internal vs open standard — 3 options analyzed)
Microsoft Ecosystem Gap Analysis
4 implementation phases with acceptance criteria and TDD work items
Visual verification checklist
Risk analysis and success metrics

Let me know if you'd like me to paste the full PRD here or if you want to review it in the management repo.

PRD authored by Dina Berry's team. Research includes codebase investigation, architecture scoping, GitHub search across 6+ Microsoft orgs, and web research on 8 agent specification standards.

🏗️ Flight triage: Agent specification framework is a core architectural initiative that establishes new contract patterns for the ecosystem. Routing: Flight (architecture + decision ownership) + Procedures (formal specification structure).

📋 Assigned to Flight (Lead)

Issue: #485 — PRD: Agent Specification & Validation Framework

Flight will pick this up in the next Copilot session.

For Copilot coding agent: If enabled, this issue will be worked automatically.
Otherwise, start a Copilot session and say:
Flight, work on issue #485

🏗️ Squad Triage — Flight (Lead)

Issue: #485 — PRD: Agent Specification & Validation Framework
Assigned to: FIDO (Quality Owner)
Reason: Issue relates to testing/quality work

@copilot evaluation: 🔴 Not suitable — issue involves work outside the coding agent's capability profile.

Team roster:

Flight (Lead) → label: squad:flight
Procedures (Prompt Engineer) → label: squad:procedures
EECOM (Core Dev) → label: squad:eecom
FIDO (Quality Owner) → label: squad:fido
PAO (DevRel) → label: squad:pao
CAPCOM (SDK Expert) → label: squad:capcom
CONTROL (TypeScript Engineer) → label: squad:control
Surgeon (Release Manager) → label: squad:surgeon
Booster (CI/CD Engineer) → label: squad:booster
GNC (Node.js Runtime) → label: squad:gnc
Network (Distribution) → label: squad:network
RETRO (Security) → label: squad:retro
INCO (CLI UX & Visual Design) → label: squad:inco
GUIDO (VS Code Extension) → label: squad:guido
Telemetry (Aspire & Observability) → label: squad:telemetry
VOX (REPL & Interactive Shell) → label: squad:vox
DSKY (TUI Engineer) → label: squad:dsky
Sims (E2E Test Engineer) → label: squad:sims
Handbook (SDK Usability) → label: squad:handbook
Ralph (Work Monitor) → label: squad:ralph
@copilot (Coding Agent) → label: squad:copilot

To reassign, remove the current squad:* label and add the correct one.

📋 Assigned to Procedures (Prompt Engineer)

Issue: #485 — PRD: Agent Specification & Validation Framework

Procedures will pick this up in the next Copilot session.

For Copilot coding agent: If enabled, this issue will be worked automatically.
Otherwise, start a Copilot session and say:
Procedures, work on issue #485

Closing — superseded by StorageProvider (#481) and TypeSpec repos

The validation framework part of this PRD is now addressed by:

StorageProvider (PRD: Squad State — Typed StorageProvider Interface with Contract Conformance #481) — typed interfaces with contract conformance testing (Wave 1 starting)
diberry/typespec-agent — the agentspec-core TypeSpec library (moved to its own repo with its own squad)

The Zod runtime validation story can be revisited once the StorageProvider foundation is in place — it depends on having typed interfaces to validate against.

squad obo dina

test: human journey — Talk to a specific agent (github#394) (github#485)

Navigation Menu

Repository navigation

PRD: Agent Specification & Validation Framework #485