Skip to content

TEMPLATES.md

Latest commit

 

History

History
541 lines (352 loc) · 12.1 KB

TEMPLATES.md

File metadata and controls

541 lines (352 loc) · 12.1 KB

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]