self/specs/framework/TEMPLATES.md

Spec Templates

Three copy-paste templates plus the execution-model rule. Pick the one that matches what you're writing.

Template	When to use	Output file
Project Overview	One per project. System-level architecture. Changes rarely.	specs/<project>/OVERVIEW.md
Workstream Spec	Durable workstream context, invariants, backlog, active plan index.	workstreams/<scope>/SPEC.md
PR Plan	One PR-sized execution handoff. Self-contained pickup after session loss.	workstreams/<scope>/plans/<BACKLOG-ID>-<slug>.md

---

Project Overview Template

[Project Name] — Architecture Specification

Last updated: date Owner: [name/team] Status: [Draft | Active | Complete]

North Star

• [Business/product goal — why this exists]
• [Success metric — measurable outcome]
• [Key constraint — the non-negotiable]

Status Checklist

• Architecture finalized
• [Milestone]
• [Milestone]
• Integration: [target]

Architecture Diagram

[diagram]

Design Principles

1. [Principle]. [Explanation.]
2. [Principle]. [Explanation.]
3. [Principle]. [Explanation.]

Module Table

Module	Location	Language	What It Does	Status	% Done	Action Needed
[Name]	path/	[lang]	[one sentence]	[state]	X%	[action or "None"]

Decision Matrix

Capability	Must be native?	Platform A	Platform B	Web Fallback
[thing]	YES / NO	KEEP / BUILD / DELETE	KEEP / BUILD / DELETE	[fallback or "None"]

Impact Summary

Metric	Current	After	Saved
[metric]	[value]	[value]	[delta]

Shared Contracts / Protocols

Workstreams

Person 1 — [Scope]   -> workstreams/<scope>/SPEC.md
|- [deliverable]
|- [deliverable]
'- [deliverable]

Person 2 — [Scope]   -> workstreams/<scope>/SPEC.md
|- [deliverable]
'- [deliverable]

Input / Output — System Level

Input:

[Example: API call, SDK launch call, user action that kicks off the system]

Output:

[Example: callback result, UI state, observable outcome]

Migration Path

1. Phase 1 (Now): [what's happening]
2. Phase 2: [what comes next and what triggers it]
3. Phase 3: [end state]

Glossary

Term	Definition
[term]	[definition]

---

Workstream Spec Template

[Workstream Name]

Last updated: date Owner: [name/team] Parent: ../../OVERVIEW.md Status: [Draft | Active | Complete]

Purpose

• [What this workstream owns]
• [Why it exists]
• [High-level definition of done]

Scope

• [in scope]
• [in scope]

Out of Scope

• [out of scope]
• [out of scope]

Invariants

• [rule that must remain true]
• [security or contract boundary]

Dependencies

Depends On	Type	Status	Notes
[scope/package]	Upstream / Downstream	[state]	[note]

Ownership Boundaries

Area	Owner	Notes
path/or/module	[team/person]	[why]

Backlog

ID	Title	Status	Priority	Depends On	Plan	PR
[ID]	[title]	Ready	High	-	-	-

Allowed statuses:

• Ready
• In Progress
• Blocked
• Deferred
• Done

Active Plans

Plan	IDs	Status
plans/<BACKLOG-ID>-<slug>.md	[ID]	In Progress

Completion Checklist

• Backlog reflects reality
• Active plan links are current
• Done items are marked done
• Cross-workstream dependencies updated

---

PR Plan Template

[Plan Title]

Last updated: date Status: [Draft | Active | Complete]

• Workstream: [scope]
• Backlog IDs: [ID]
• Owner: [name/team]
• Branch: [branch or TBD]
• PR: [url or TBD]

Why

• [why now]
• [user/system impact]
• [important constraint]

Scope

• [deliverable]
• [deliverable]

Out of Scope

• [not included]
• [not included]

Files to Modify

• path
• path

Files Not to Modify

• path
• path

Preconditions

• [must already be true]
• [upstream dependency]

Implementation Notes

• [critical constraint]
• [contract note]
• [edge case]

Validation

[command]

Definition of Done

• Code changes complete
• Validation passes
• Backlog row updated
• Plan status updated
• PR linked

Status Log

• date: Scope changed because ...

1. [Principle]. [Why.]
2. [Principle]. [Why.]

Definition of Done

Done when: [statement]

Scope of Work

1. [Task Name — Modify Existing]

file/path.ts — Lines X-Y

// BEFORE
[exact current code]

// AFTER
[exact target code]

Input / Output

Input:

[concrete example]

Expected Output:

[concrete example]

Edge case — [description]:

Input:  [edge case]
Output: [expected result]

---

2. [Task Name — Create New]

Create: src/path/to/new-file.ts

Implements: [InterfaceName] from src/types/[file].ts

// SKELETON
[exports, function signatures, key types — enough to show the shape]

Input / Output

Input:

[concrete example]

Expected Output:

[concrete example]

Error case — [description]:

Input:  [error scenario]
Output: [expected error behavior]

---

Files You Will Modify

File	Change	Risk
src/foo.ts	[what changes]	High/Med/Low — [why]

Files You Will NOT Modify

File	Why
src/bar.ts	[out of scope / owned by another workstream / etc.]

Chunking Guide

Chunk [ID]: [Name] — [S/M/L ~Xk tokens]

Goal: [One sentence.]

Steps:

1. [Concrete step]
2. [Concrete step]
3. Validate: [specific command or check]

Input / Output — Chunk Validation

Input:

[concrete test: CLI command, function call, etc.]

Expected Output:

[what you should see]

Tests

Test	Type	What it validates
[test name/description]	Unit / Integration / Build gate	[one sentence]

---

Chunk [ID]: [Name] — [S/M/L ~Xk tokens]

Depends on: Chunk [ID]

Goal: [One sentence.]

Steps:

1. [step]
2. [step]
3. Validate: [check]

Input / Output — Chunk Validation

Input:

[test]

Expected Output:

[result]

Tests

Test	Type	What it validates
[test]	[type]	[validates]

---

Dependency Graph

Chunk A (no deps)
  |---> Chunk B (after A)
  |       '---> Chunk D (after B)
  |---> Chunk C (after A)
  '---> Chunk E (after A, optional)

Completion Status

Chunk	Description	Size	Status
[ID]	[name]	S/M/L	Pending / In Progress / Done / Skipped

Validation Plan

# After every chunk (must pass):
[type-check command]
[test command]

# After all chunks:
[integration check command]

Key Reference Files

File	What to Look At
path/to/file.ts	[what's relevant]

---

What Was Built

Architecture (brief)

Deviations from Spec

Spec said	We did	Why
[original plan]	[actual implementation]	[reason]

Key Files (final)

File	Role
src/thing.ts	[what it does]

Lessons / Gotchas

• [One-liner that would help the next person]

---

Follow-Up (Out of Scope)

Item	Discovered during	Suggested spec
[thing]	Chunk [ID]	[new or existing spec]