docs/delivery-specs/index.md

# Delivery Specs

This directory contains delivery specifications that define *how* to build features for engineering handoff.

## What is a Delivery Spec?

Delivery specs translate validated ideas into engineering requirements. They answer:
- What are the functional requirements?
- What files need to be created/modified?
- What are the acceptance criteria?
- What agent instructions apply?

## When to Use

| Complexity | Discovery? | Delivery Spec? | Notes |
|------------|------------|----------------|-------|
| **Simple** (CRUD) | Skip | Skip | Go directly to `autocode-implementation-planner` |
| **Standard** (feature) | Recommended | Optional | Discovery provides enough context |
| **Complex** (system) | Required | Required | Full pipeline for alignment |

## File Format

Each feature has one file:
- `{feature}.md` — Structured delivery spec with requirements, file manifest, agent instructions

## Delivery Specs Index

| Feature | Status | Date |
|---------|--------|------|
| *None yet* | | |

## Relationship to Other Docs

```
discovery/        →  Validate + Taste (OST, PR/FAQ)
    ↓
delivery-specs/   →  Engineering handoff (YOU ARE HERE)
    ↓
design-docs/      →  Technical approach (ADR-style)
    ↓
FEATURES.json     →  Links docs to implementation
    ↓
specs/            →  Implementation specs (autocode)
```

## Creating Delivery Specs

Use the `delivery-spec` skill for structured delivery specs:

```
skill({ name: "delivery-spec" })
```

The skill guides you through:
1. **Problem context** — References discovery doc
2. **Functional requirements** — What the system must do
3. **File manifest** — Files to create/modify
4. **Agent instructions** — Patterns, constraints, anti-patterns
5. **Acceptance criteria** — Definition of done

## Integration with Discovery

Delivery specs read from discovery JSON:
- Pull `taste.delights` as success criteria context
- Pull `taste.frustrations` as anti-patterns
- Pull `scope.out_of_scope` as explicit boundaries