Template: templates/frame.architecture.md

# {{title}}

_The overarching shape of the product as a built system. When the detail outgrows a single file, expand into an optional `Arch/` folder and keep this doc as the map that points into it._

## Shape

_The system in one breath: the major pieces and how they fit. A paragraph or a simple sketch. Enough that a newcomer can hold the whole in their head before reading any spec._

## Components

_The named parts and what each is responsible for. One line to a short paragraph each. Boundaries matter more than internals here; this is the map, not the territory._

## Data and flow

_What moves through the system and where it lives. The path a request, a record, or an event takes from edge to store and back._

## Boundaries and dependencies

_Where this system ends and others begin. Outside services, platforms, and integrations it leans on. The seams where it could break or be swapped._

Template: templates/frame.audience.md

# {{title}}

_Who the product is for, and how each kind of person interacts with it differently. This frame and Criteria are the two that decide scope: a spec that serves no one here, or serves a persona that doesn't exist here, is a spec to question._

## Audience

_Who uses this product, in a paragraph or two. The whole population it is built for, described plainly. Not segmented yet, just the answer to "who is this for."_

## Personas

_How each kind of person interacts differently. One short block of prose per persona, never a table or a headshot-and-demographics card. The point is the difference: what this persona comes for, how they reach for the product, what they ignore. A persona earns its place here only when it interacts in a way the others do not._

### Persona name

_What this person is here to do and how they go about it._

### Persona name

_The next persona, described by how it differs from the one above._

Template: templates/frame.criteria.md

# {{title}}

_The frame that decides and audits scope: what the product can afford, what it is trying to be, and by when. When scope creeps, it creeps past this doc._

## Budget

_How the work gets financed and what that buys. The rough money or resource envelope: funded how, spending against what, for how long the runway lasts. Enough to tell whether a given spec is affordable._

## Scope Objectives

_What the product is aiming to be at this level: a prototype, an MVP, a production product, a platform. The objective sets the ceiling on scope. State it plainly so specs can be checked against it._

## Timeline

_The limits time imposes. Hard dates, milestones, or seasons that bound the work. What must exist by when, and what that forces to wait._

## Parameters & Variables

_The large-scale factors that move scope — the things that, if they change, change what is feasible or sensible to build. An integration going live, a development partner coming on or dropping off, a funding milestone, a platform deadline, a key hire. Name each one and what it would change._

Template: templates/frame.market.md

# {{title}}

_Where the product sits in its marketplace, why it is not just another one of many, and how it is intended to make money._

## Landscape

_The market this product enters: the category it lives in, and the substitutes people reach for today. An honest picture of how crowded it is._

## Competitors

_The specific products and alternatives you are up against — named. For each, a line on what it does well and where it leaves a gap. Include the "do nothing" or "use a spreadsheet" substitutes, not just the direct rivals._

## Positioning & Differentiators

_Where this product sits, and the specific thing that makes it not interchangeable with the rest. Not a slogan: the concrete difference a user would feel. If you cannot name it, that is the most important thing this doc has surfaced._

## Who it is for and against

_The slice of the market this product wins, and the competitors it wins it from. The customer it serves better than anyone, stated plainly._

## Earning Capabilities

_How the product is intended to make money. The revenue model: what is charged, to whom, on what cadence. Where the money comes from, and what has to be true for it to work._

Template: templates/spec.full.md

# {{title}}

## Intent

_Why this exists — the problem and who has it. One or two paragraphs. This is the stable part: if Intent changes substantially, you probably have a different spec, not an edit to this one._

### Assumptions

_The assumptions you're proceeding on — what you're taking as given about the problem or the world, not yet confirmed. Nested under Intent because they frame it. Surface them so a guess doesn't slip into Behaviors as if it were settled._

### Implementation Notes

_Optional, nested under Intent. The intent of the implementation — the approach you mean to take and why. Direction, not status: how you intend to build it (e.g. "reuse the existing queue"), never how far along it is. Delete if the approach is obvious or undecided._

## Open Questions

_Unresolved questions — what you don't yet know and still need answered. Kept high, right after Intent, so uncertainty is seen rather than buried. When one is settled it graduates into an Assumption, a Behavior, or a Decision._

## Behaviors & Acceptance Criteria

_What it does, as observable outcomes — the "this is what you're getting" section. If a behavior isn't listed here, it isn't promised. Label each criterion **AC1:**, **AC2:**, … (bold, unique within this spec). Group them under the requirement categories that apply as `###` sub-headings; the categories are suggestive — use what fits, AC numbers running continuously across them. Keep each AC short and checkable; push rich detail into a table or sub-section it points to. Evolves freely._

### Functional

- **AC1:** <!-- features, behaviors, business rules -->

### Performance

- **AC2:** <!-- speed, throughput, response time, capacity, concurrent users -->

### Design

- **AC3:** <!-- mandated tech, standards, regulatory rules, platform limits -->

### External interface

- **AC4:** <!-- how it connects to users, hardware, other software, networks: UI, APIs, protocols -->

### Quality attributes

- **AC5:** <!-- the other -ilities: reliability, security, usability, maintainability, scalability, portability -->

## Out of Scope

_Explicit non-goals — the section the standard leans on hardest, because this is where scope is held. A spec without it is rarely finished; it's the first thing to add when a spec feels thin._

## Dependencies

_Anything this needs to build or run: services, libraries, teams, data, other specs. The `depends_on` property at the top is the spec-only subset of this, as links. Reference other specs as markdown links — `[Session Management](../identity/session-management.md)` — never bare names._

## Testing

_How this is verified: the testing approach and the key cases that prove the behaviors hold. Reference AC labels where useful (e.g. "AC1–AC3 covered by the sign-in suite")._

## Constraints & Decisions

_Two things under one header. **Constraints**: non-functional boundaries and hard limits the build must respect — not the architecture itself. **Decisions**: an append-only log, one line each, with an optional but recommended date._

<!-- 2026-06-17: Dropped SMS fallback, carrier cost. (Brenton) -->

Template: templates/spec.micro.md

# {{title}}

## Intent

_Why this exists — the problem and who has it. One or two paragraphs. This is the stable part: if Intent changes substantially, you probably have a different spec, not an edit to this one._

### Assumptions

_The assumptions you're proceeding on — what you're taking as given, not yet confirmed. Nested under Intent because they frame it. A micro spec almost always has some; surfacing them is half the point of writing one early._

## Open Questions

_Unresolved questions — what you don't yet know and still need answered. Kept high, right after Intent, so uncertainty is seen rather than buried; when one is settled it graduates into an Assumption, a Behavior, or a Decision._

## Behaviors & Acceptance Criteria

_What it does, as observable outcomes — the "this is what you're getting" section. If a behavior isn't listed here, it isn't promised. Label each criterion **AC1:**, **AC2:**, … (bold, unique within this spec). Keep each short and checkable; push rich detail into a table or sub-section it points to._

- **AC1:** <!-- the first observable outcome -->

## Out of Scope

_Explicit non-goals — the section the standard leans on hardest, because this is where scope is held. A micro spec carries it too; it's the first thing to write, not the last._