PRD: @agentspec/core — Framework-Agnostic Agent Specification via TypeSpec #511

PRD: @agentspec/core — Framework-Agnostic Agent Specification via TypeSpec

Author: Dina's Squad (Flight, EECOM, CONTROL, RETRO, FIDO, PAO)
Status: Team-reviewed (v2, all 29 blockers addressed)
Related: #485 (Agent Spec and Validation), #332 (A2A Protocol), #481 (StorageProvider)

The pitch

No portable, typed agent specification exists today. Each framework (M365 Copilot, AutoGen, CrewAI, Semantic Kernel, Squad) defines agents differently. @agentspec/core is the OpenAPI equivalent for agent definitions — a TypeSpec library + emitter that defines universal agent primitives and produces a canonical agent manifest.

Two phases

Phase 1: @agentspec/core — The open standard (~1.5 weeks)

• TypeSpec library defining 12 universal decorators: @agent, @role, @instruction, @capability, @boundary, @tool, @knowledge, @conversationStarter, @memory, @version, @inputMode, @outputMode
• Emitter producing agent-manifest.json (canonical format) + agent-manifest.schema.json (JSON Schema for validation without TypeSpec)
• model AgentManifest TypeSpec type as single source of truth
• Security: @instruction omitted from A2A cards by default, PII compiler diagnostics, sensitivity field
• Package: @agentspec/core on npm (2FA + provenance attestation required)

Phase 2: Squad emitters (~2.5 weeks)

• @bradygaster/typespec-squad — Squad extensions (@casting, @routing, @ceremony) → charter.md, team.md, routing.md, registry.json
• @bradygaster/typespec-squad-copilot — Copilot SDK extensions (@model) → squad.config.ts, copilot-instructions.md
• Parallel path to existing squad build (not a replacement)
• Generates AgentDefinition TypeScript type from TypeSpec into builders/generated/types.ts

The layer architecture

@agentspec/core <- open standard (12 decorators) | +-- @bradygaster/typespec-squad <- Squad extensions | +-- @bradygaster/typespec-squad-copilot <- Copilot SDK target | +-- @bradygaster/typespec-squad-mcp <- MCP server scaffolding (future) | +-- @bradygaster/typespec-squad-a2a <- A2A protocol types (future) | +-- (community emitters for AutoGen, CrewAI, Semantic Kernel, etc.)

Prerequisites (do now)

• Register agentspec npm org (before someone else takes it)
• Confirm TypeSpec team is aware and supportive

Key decisions made by team review

• Casting stays in Squad layer (not base) — it is implementation flavor, not universal
• @model is Copilot-specific (not base)
• TypeSpec peer dep minor-locked (>=0.60.0 <0.62.0)
• Emitter uses program.host.writeFile only (no raw fs)
• AgentDefinition.name maps to manifest id via translation table
• Phase 2 effort includes sub-emitter split and squad.config.ts codegen complexity

Competitive position

No one has done this. Microsoft's @microsoft/typespec-m365-copilot is M365-locked. Oracle Agent Spec is YAML. OASF is JSON. A TypeSpec-based portable agent spec that compiles to any framework is unoccupied territory.

Full PRD

The complete PRD v2 (~500 lines, all 29 review items addressed) is at .squad/decisions/inbox/pao-agentspec-typespec-prd-v2.md on the dev branch.

squad obo dina — this PRD was produced by Flight (Lead), reviewed by EECOM, CONTROL, RETRO, FIDO, written by PAO, revised by Flight after 4 rejection reviews with 29 blockers fixed.