# Spec-Driven Development (SDD) Conventions

> **If you are an AI coding agent, you MUST FOLLOW THESE CONVENTIONS. This is PROJECT-SPECIFIC, so NO NEGOTIATION!**

## ONLY 3 Core Principles

- The spec is the SOURCE OF TRUTH for a feature, not the code
- Specs describe PROBLEM, PLAN, and PROGRESS
- Every feature MUST have a spec folder

---

## Spec Structure

All specs live in a specs folder. The path can be configured in your project's `AGENTS.md` file (or similar project configuration). If not specified, the default location is `.specs/` at the project root.

**Configuration Example (in AGENTS.md):**
```markdown
## Spec-Driven Development (SDD) Directory

Specs are located at: `docs/specs/`
```

Each feature gets its own subfolder inside the specs directory.

### Folder Naming Pattern

```
{YYYY-MM-DD}--{kebab-case-title}
```

- `YYYY-MM-DD`: creation date (ISO format), fixed at the time the spec was created
- `title`: kebab-case feature name
- Separators: double dashes `--`

Examples:

- `2026-03-01--user-authentication`
- `2026-03-05--billing-integration`
- `2026-03-15--dark-mode-toggle`

### Folder Structure

```
project-root/
├── {specs-dir}/               ← Configurable path (default: .specs/)
│   ├── 2026-03-01--user-authentication/
│   │   ├── README.md          📋 Status, owner, original prompt
│   │   ├── plan.md            🗺️ Agent-generated implementation plan
│   │   └── work-logs.md       📝 Timeline & change history (optional)
│   │
│   ├── 2026-03-05--billing-integration/
│       └── ...
│
├── src/                        ← your codebase (untouched by this convention)
└── ...
```

---

## Files Inside Each Feature Folder

### README.md (required) - strongly intended for humans, but AI agents should read it as well.

This is the feature's identity card. Short, scannable, no fluff.

MUST contain:

- **Status**: one of `draft`, `in-progress`, `completed`, `on-hold`, `deprecated`
- **Owner**: who is responsible for this feature
- **Created**: creation date (same as folder name)
- **Last Updated**: date of last modification
- **Original prompt/requirement**: the exact prompt or requirement that initiated this feature. This is the most important field in the entire spec. It preserves original intent. MUST NOT be edited or paraphrased. **It MUST be written in English** — if the prompt was given in another language (e.g. Vietnamese), translate it faithfully to English without changing the meaning, intent, or scope.
- **Summary**: 2-3 sentences max describing what this feature does and why it exists

Template:

```markdown
# Feature: [Name]

| Field            | Value                                                    |
| ---------------- | -------------------------------------------------------- |
| **Status**       | status                                                   |
| **Owner**        | @developer                                               |
| **Issue**        | [#issue-number](link-to-issue) or N/A                    |
| **Branch**       | `type/spec-name`                                         |
| **Created**      | YYYY-MM-DD                                               |
| **Last Updated** | YYYY-MM-DD                                               |

## Original Prompt

> [Paste the exact original prompt or requirement here. Do not edit or paraphrase.]

## Summary

[2-3 sentences. What this feature does and why it exists.]
```

### Branch Naming Convention

The branch name MUST follow the pattern `type/spec-name`, where:

- **type**: the kind of work being done
- **spec-name**: kebab-case name derived from the spec folder title

Common types:

| Type       | Use when                                      |
| ---------- | --------------------------------------------- |
| `feat`     | Adding new functionality                      |
| `fix`       | Fixing a bug or error                         |
| `update`   | Enhancing or changing existing features       |
| `cleanup`  | Removing unused code, refactoring             |
| `docs`     | Documentation-only changes                    |

Examples:
- `feat/build-abc`
- `fix/error-on-checkout`
- `cleanup/remove-legacy-api`
- `update/change-abc-features`

### plan.md (required)

Generated by the dev's preferred agent, framework, or workflow (Cursor, Claude Code, BMAD, spec-kit, superpowers...). The convention does NOT dictate format. Each dev uses whatever planning tool they prefer.

**IMPORTANT**: `plan.md` does NOT contain status, created date, or other metadata - those live in `README.md`.

The plan MUST meet these constraints:

- MUST be under 500 lines
- MUST include a section listing all files and folders this feature touches, so other agents know the scope

### work-logs.md (optional)

A timeline of work done on this feature. Useful when:

- The feature spans multiple days or sessions
- Multiple devs contribute to the same feature
- You want to track what was tried, what failed, what changed

Append-only format:

```markdown
# Work Logs

## YYYY-MM-DD — @developer
- What was done
- Decisions made
- Blockers encountered

## YYYY-MM-DD — @other-developer
- Continued from previous session
- Updated plan to reflect new approach
```

---

## Rules

1. **New feature?** Create a spec folder following the convention above before writing any code.
2. **Existing feature?** Read the spec first. Update it if your changes affect the plan, status, or scope.