docs/
├── README.md              # Overview and rules
├── plan/
│   ├── README.md          # Plan guidelines
│   └── template.plan.md   # Plan template
└── spec/
    ├── README.md          # Spec guidelines
    └── template.spec.md   # Spec template

plan (Draft) → plan (In Review) → plan (Accepted) → spec

# [Plan Title]

| Field | Value |
|-------|-------|
| Status | Draft / In Review / Accepted / Rejected |
| Owner | @username |
| Created | YYYY-MM-DD |
| Related | #issue, #pr |

## Problem Statement

What problem does this solve? Why does it matter?

## Goals

What this plan aims to achieve.

## Non-Goals

What is explicitly out of scope.

## Proposal

High-level approach to solving the problem.

## Detailed Design

Technical blueprint: architecture, data flow, component interactions.

## Milestones

| Milestone | Description | Target |
|-----------|-------------|--------|
| M1 | ... | ... |

## Rollout Plan

How this will be deployed/released. Phasing, feature flags, migration steps.

## Risks and Mitigations

| Risk | Likelihood | Impact | Mitigation |
|------|------------|--------|------------|
| ... | ... | ... | ... |

## Alternatives Considered

Other approaches evaluated and why they were not chosen.

## Open Questions

- [ ] Question 1
- [ ] Question 2

# [Spec Title]

| Field | Value |
|-------|-------|
| Decision Status | Draft / Accepted / Deprecated / Superseded |
| Implementation Status | Not Implemented / In Progress / Partial / Implemented / Blocked |
| Last Updated | YYYY-MM-DD |
| Plan | [link to plan] |
| Issues | #issue |
| PRs | #pr |

## Summary

Brief description of what this spec defines.

## Definitions

Key terms and their meanings within this spec.

## Requirements

### Functional

What the system must do.

### Non-Functional

Performance, security, reliability, and other quality attributes.

## Behavior

Expected system behavior under normal and edge conditions.

## Interfaces

### API

Endpoints, methods, request/response formats.

### Data Model

Schemas, entities, relationships.

## Edge Cases

How the system handles boundary conditions and error states.

## Observability

Logging, metrics, alerts, and debugging support.

## Test Plan

How compliance with this spec is verified.

## Implementation Notes

Links to PRs, technical decisions made during implementation.

## Changelog

| Date | Change | Author |
|------|--------|--------|
| YYYY-MM-DD | Initial spec | @username |

# Documentation System

This directory contains the in-repo planning and specification system.

## Concepts

**Plan** — A proposal, blueprint, or work-in-progress design. Plans live in `docs/plan/`.

**Spec** — An accepted contract and source of truth. Specs live in `docs/spec/`.

## Promotion Flow

plan (Draft) → plan (In Review) → plan (Accepted) → spec

## Rules

1. Plans are not contracts. They may be messy or exploratory.
2. Specs are contracts. They must remain accurate.
3. Specs may describe future behavior only when Decision Status = Accepted.
4. Status fields are authoritative. Update them as work progresses.

# Plans

Plans are blueprints and proposals. They are allowed to be messy and iterative, may contain open questions, and are not authoritative contracts.

When a plan is accepted, it is promoted into `docs/spec/`.

## Creating a Plan

1. Copy `template.plan.md` to a new file
2. Fill in the sections
3. Set Status to Draft
4. Submit for review when ready

# Specifications

Specs are accepted contracts and reference behavior. They are the source of truth for implementation and tests. Specs must remain accurate over time.

Specs may describe not-yet-implemented behavior only when explicitly marked with Decision Status = Accepted.

## Status Tracking

Specs track two independent dimensions:

**Decision Status**: Draft, Accepted, Deprecated, Superseded

**Implementation Status**: Not Implemented, In Progress, Partial, Implemented, Blocked