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 [email protected]: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