EARS Spec Engine

EARS Spec-Driven Development — generate requirements in EARS (Easy Approach to Requirements Syntax) notation, design documents, and dependency-tracked tasks directly inside pi. Inspired by Amazon Kiro Spec-Driven Development.

pi install npm:ears-spec-engine

Features

This extension adds three LLM-callable tools and six user commands for a complete SDD workflow:

🛠️ Tools (LLM)

Tool	Purpose
ears_validate	EARS grammar validation against the 5 canonical patterns (Ubiquitous, Event-Driven, State-Driven, Optional, Complex)
ears_analyze	Analyze requirements for logical conflicts, ambiguous language, and incompleteness (missing edge cases)
ears_analyze_deps	Analyze task dependencies, build execution waves, and compute the critical path

⌨️ Commands (user)

Command	Purpose
/ears:quick-plan	Fast-track: clarifying questions + generate all 3 documents in one pass
/ears:spec	Phase 1: generate EARS requirements from a feature description
/ears:analyze	Analyze existing requirements (from file or session state)
/ears:design	Phase 2: generate a design document
/ears:tasks	Phase 3: generate a task breakdown with dependency analysis
/ears:status	Show current spec engine state (detects files on disk automatically)

🧩 Nested Skill

The extension automatically registers the ears-spec skill, accessible via /ears-spec.

Installation

# Global install
pi install npm:ears-spec-engine

# Project-local install
pi install -l npm:ears-spec-engine

Usage

Quick Start (all phases in one pass)

/ears:quick-plan <feature description>

Note: The AI automatically picks a short English kebab-case directory name (e.g. open-file-in-browser) for your spec, regardless of the language of your input. You can describe features in any language.

Step-by-Step Mode

1. Requirements: /ears:spec <feature description> — generates user stories + EARS acceptance criteria
2. Design: /ears:design — architecture, data models, API contracts, error handling
3. Tasks: /ears:tasks — task breakdown with dependencies and execution waves

Check Status

/ears:status

/ears:status automatically discovers your spec directory and checks which files exist on disk. It reports status for requirements, design, and tasks — even across session restarts.

Example

Running /ears:spec user authentication produces this structure:

.ears-spec/user-authentication/
├── requirements.md    # User stories + EARS acceptance criteria
├── design.md          # Architecture, data flow, diagrams
└── tasks.md           # Implementation tasks with dependencies

The Five EARS Patterns

Pattern	Template	Example
Ubiquitous	THE SYSTEM SHALL <response>	THE SYSTEM SHALL hash passwords using bcrypt with cost factor 12.
Event-Driven	WHEN <trigger>, THE SYSTEM SHALL <response>	WHEN a payment webhook is received, THE SYSTEM SHALL verify the HMAC signature.
State-Driven	WHILE <state>, THE SYSTEM SHALL <response>	WHILE the system is in maintenance mode, THE SYSTEM SHALL return HTTP 503.
Optional	WHERE <feature>, THE SYSTEM SHALL <response>	WHERE the enterprise SSO module is enabled, THE SYSTEM SHALL validate tokens against SAML IdP.
Complex	<condition>, THE SYSTEM SHALL <response>	WITHIN 500ms of receiving a query, THE SYSTEM SHALL return ranked results.

Grammar Rules

• ✅ SHALL is mandatory (not should, will, must)
• ✅ UPPERCASE keywords: WHEN, WHILE, WHERE, WITHIN, THE SYSTEM SHALL
• ❌ Banned ambiguous terms: appropriate, timely, efficient, user-friendly, properly, various

Development

# Clone
git clone git@github.com:XpycT/ears-spec-engine.git
cd ears-spec-engine

# Install dependencies
npm install

# Run tests
npm test

# Type check
npm run type-check

All tests use Node's built-in node:test runner via tsx:

npm test
# 67 tests — 12 suites, all pass

Code Style

• Tabs for indentation (4-width), spaces for JSON/YAML
• .editorconfig enforces consistent formatting
• Run npm run type-check for TypeScript validation

Architecture

ears-spec-engine/
├── index.ts           # Extension entry point (tool and command registration)
├── lib/
│   ├── types.ts        # TypeScript type definitions
│   ├── ears.ts         # EARS validation, conflict detection, analysis
│   └── templates.ts    # Document rendering and dependency graph analysis
├── skills/
│   └── ears-spec/
│       └── SKILL.md    # Nested skill definition
├── .editorconfig
├── LICENSE             # MIT
├── package.json
├── tsconfig.json
└── README.md

Why

Spec-Driven Development with EARS notation enables:

1. Testable requirements — formal grammar eliminates ambiguity
2. Automated quality checks — tools validate grammar, detect conflicts, and find gaps
3. Implementation planning — tasks with explicit dependencies and execution waves
4. Requirement traceability — every task links back to a requirement ID

License

MIT