# openspec

Per-batch documentation convention adopted v1.13.15-openspec.

**Agent entry point:** `AGENTS.md` at repo root. **Architecture diagram:** `docs/ARCHITECTURE.md`.

Lift source: Fission-AI/OpenSpec directory layout. **No CLI dependency** — just
the folder shape. Full OpenSpec lifecycle adoption is a future v1.14+ batch.

## Layout

```
openspec/
  changes/
    <slug>/                          # one folder per shipped or planned batch
      proposal.md                    # Why + scope summary
      tasks.md                       # implementation step list
      design.md                      # architecture / data-model decisions (optional)
      specs/                         # reserved for future OpenSpec CLI adoption
    archived/                        # snapshots of pre-v1.13.15 batch docs
      <original-filename>.md
  specs/                             # global specs, future v1.14+ use
```

## Conventions

- Slugs are lowercase-hyphenated derived from the batch title
  (e.g. `v1-13-10-per-tool-cost`, `file-attachments-v3-5`).
- Already-shipped pre-v1.13.15 batches live in `changes/archived/` as
  single-file snapshots. They were not split into proposal/tasks because
  the work was already complete; archiving preserves git history.
- New v1.13.15+ batches should land directly in
  `changes/<slug>/proposal.md` (+ tasks.md, + design.md when applicable).
- `proposal.md` carries the "Why" and scope. `tasks.md` is the action list
  (numbered or checkbox). `design.md` is for non-trivial architectural
  decisions worth recording separately.
- A canonical dispatch brief (matching the v1.13.9 / v1.13.10 format)
  is most naturally split as proposal.md (Where we are, Why this matters,
  rationale sections) + tasks.md (Scope items, Build + smoke) + design.md
  (Attribution model, Filtering, Canonical mapping).