AI Spec Frameworks

Research and implementation of specification frameworks for autonomous agent implementation. This project validates the Kiro 3-file specification model and implements a complete pipeline for agent-ready specs.

Status

Phase 1 + 2 Complete (P1.A → P2.E): Research findings, marketplace skills, design conventions, and bridge design implemented.

See PROGRESS.md for detailed implementation status.

What's Inside

Core Artifacts

• artifacts/spec-critique/ — Spec review skill with embedded research context and verification enforcement
• artifacts/agent-context-framework/ — Design.md convention for architectural documentation
• spec-to-context-bridge.md — Design for bridging /spec/ markdown specs to .context/spec.json

Scripts

• scripts/deploy.sh — Deploy artifacts to target locations (~/.agents/skills/spec-critique, agent-context-framework/docs)
• scripts/install-skills.sh — Install marketplace spec pipeline skills (create-specification, requirements-analysis, etc.)
• scripts/spec-md-to-json.js — Convert /spec/ markdown to .context/spec.json (P2.E implementation)

Documentation

• PROGRESS.md — Detailed progress tracking and key insights
• research/RESEARCH_PLAN.md — Full research findings and implementation plan
• .context/ — Agent-context-framework bootstrap with Kiro 3-file model support

Quick Start

Deploy artifacts to local system

bash scripts/deploy.sh

This copies:

• Spec-critique research requirements → ~/.agents/skills/spec-critique/references/
• Updated SKILL.md with verification enforcement → ~/.agents/skills/spec-critique/
• Design.md convention → agent-context-framework/docs/

Install marketplace spec skills

bash scripts/install-skills.sh

Installs:

• /create-specification — Generate 11-section EARS-formatted specs
• /requirements-analysis — Interview and validate requirements (RA0→RA5)
• /update-specification — Keep specs current during implementation
• /create-github-issues-for-unmet-specification-requirements — Track spec gaps

Convert spec markdown to JSON

node scripts/spec-md-to-json.js \
  --spec spec/spec-example.md \
  --track-id 04 \
  --track-dir .context/live/tracks/04-example \
  [--dry-run]

Key Concepts

The Kiro 3-File Model

Three complementary spec documents for complete coverage:

1. requirements.md — EARS-formatted acceptance criteria ("WHEN X THEN Y")
2. design.md — Architecture, interfaces, sequence diagrams, test strategy
3. tasks.md — Atomic implementation tasks with explicit dependencies

Maps to agent-context-framework:

• spec.json ← requirements.md (acceptance_criteria[])
• design.md ← optional companion (NEW convention)
• plan.json ← tasks.md

Six Quality Pillars for Agent-Ready Specs

1. Verifiability — Every criterion includes test inputs/outputs
2. Ambiguity elimination — EARS notation (WHEN X THEN Y)
3. Constraint enumeration — Explicit out_of_scope, forbidden patterns
4. Code grounding — References actual file paths, not patterns
5. Atomic task decomposition — Tasks fit one context window
6. Progressive disclosure — <500 lines main spec, details in appendices

EARS Notation

Format: WHEN [trigger] THEN [behavior]

Examples:

• WHEN user submits form THEN system validates email
• IF user has admin role THEN WHEN accessing reports THEN system includes PII fields
• WHILE processing transaction MAINTAIN data integrity
• WHERE feature requires encryption USE TLS 1.3

Architecture

Agent Implementation Pipeline
├── /requirements-analysis
│   └── Interview mode (RA0 → RA5 validation)
├── /create-specification
│   └── Generate 11-section spec.md (EARS format)
├── /spec-critique (with research context)
│   └── Deep Opus-level review + verification enforcement
├── spec-md-to-json bridge
│   └── Extract criteria → .context/spec.json
└── /create-architectural-decision-record
    └── Document design rationale

Next Phases

• P2.E.1 — Implement Node.js bridge script (✅ in progress)
• P3.E — EARS notation enforcement in spec-critique (proposed)
• P3.F — Cross-project spec index via Memory MCP (proposed)

Files

• Plan: research/RESEARCH_PLAN.md
• Progress: PROGRESS.md
• Bridge Design: spec-to-context-bridge.md
• Skill Configuration: artifacts/spec-critique/SKILL.md
• Design Convention: artifacts/agent-context-framework/docs/DESIGN_CONVENTION.md
• Research Context: artifacts/spec-critique/references/research-requirements.md

Why This Matters

"Agent failures are context failures, not model failures." — HuggingFace Context Engineering

Autonomous agents need:

• Unambiguous specs (EARS notation)
• Complete specs (all criteria, constraints, edge cases)
• Verifiable specs (concrete test commands + expected outputs)
• Grounded specs (real file paths, not patterns)
• Architectural context (design rationale, interfaces)

This project delivers a battle-tested pipeline for creating specs that meet these requirements.

References

• Kiro Specification Framework — The 3-file model inspiration
• agent-context-framework — Framework integration
• spec-critique skill — Deep spec review
• Context Engineering (HuggingFace blog)