FEATURES.md

Why FEATURES.md?

As AI coding agents become more prevalent, projects need a standardized way to communicate feature requirements and status. FEATURES.md bridges the gap between human documentation and machine-readable specifications.

🧪 Testable Properties

Every feature property should be verifiable. Clear acceptance criteria mean better implementations.

📊 Stability Levels

Know at a glance what's production-ready, in development, or planned for the future.

🤖 Agent Friendly

Structured format that AI agents can parse to understand requirements and make informed decisions.

👁️ Human Readable

Clean markdown that developers can read, write, and maintain without special tooling.

Stability Levels

Every feature in FEATURES.md must declare its stability status:

stable Production ready

in-progress Currently building

planned On the roadmap

Quick Start

Add a FEATURES.md file to your project root:

FEATURES.md

# My Project - Features

## Features

### User Authentication
- **Stability**: stable
- **Description**: Secure login system with JWT tokens
- **Properties**:
  - Passwords are hashed with bcrypt (salt rounds >= 10)
  - Session tokens expire after 24 hours
  - Failed logins rate-limited to 5 per minute
- **Test Criteria**:
  - [x] Valid credentials return JWT token
  - [x] Invalid credentials return 401
  - [x] Rate limiting blocks excessive attempts

### Real-time Notifications
- **Stability**: in-progress
- **Description**: Push notifications via WebSocket
- **Properties**:
  - Messages delivered within 100ms
  - Reconnection with exponential backoff
- **Test Criteria**:
  - [x] WebSocket connection established
  - [ ] Offline queue syncs on reconnect

### AI Suggestions
- **Stability**: planned
- **Description**: AI-powered recommendations
- **Properties**:
  - Analyzes user patterns
  - Provides ranked suggestions
- **Test Criteria**:
  - [ ] Endpoint returns suggestions
  - [ ] Feedback updates model

How It Works

Create FEATURES.md

Add a FEATURES.md file at your project root with your feature specifications.

Define Testable Properties

For each feature, list properties that can be verified through tests or observation.

Set Stability Levels

Mark features as stable, in-progress, or planned so everyone knows what's ready.

Keep It Updated

Update your FEATURES.md as features evolve. It's a living document.

Works With

FEATURES.md complements your existing documentation:

README.md

High-level project overview and getting started guide.

AGENTS.md

Instructions for AI coding agents working on your project.

CHANGELOG.md

Version history and release notes.

CONTRIBUTING.md

Guidelines for contributing to the project.

Collaborate

We'd love your input on improving the FEATURES.md specification!

💬 Signal: pierce.403

🐙 GitHub: Open an issue or PR