@pilotspace/add 1.0.0

package/tooling/templates/CONVENTIONS.md.tmpl

@@ -0,0 +1,8 @@
+# CONVENTIONS  (survivor layer — set once, kept for the whole project)
+
+Language/framework: <e.g. Python 3.12 / FastAPI>
+Folders: .add/tasks/<slug>/{TASK.md, tests/, src/}
+Naming: <file case>, <type case>, verbs for functions
+Lint/format: <tools>, enforced in CI
+Errors: machine-readable error codes (string enums), never free text
+Architecture: <layering and dependency rules>

package/tooling/templates/GLOSSARY.md.tmpl

@@ -0,0 +1,3 @@
+# GLOSSARY  (one name per concept — used everywhere: specs, contracts, code)
+
+<term>: <definition>

package/tooling/templates/MILESTONE.md.tmpl

@@ -0,0 +1,25 @@
+# MILESTONE: {{title}}
+
+goal: {{goal}}
+stage: {{stage}} · status: active · created: {{date}}
+
+> SDD living doc for this milestone. Keep it THIN: breadth, shared decisions, and
+> exit criteria only — per-task detail lives in each `.add/tasks/<slug>/TASK.md`,
+> written just-in-time. Update this doc whenever a task reveals a milestone gap.
+
+## Scope
+In:  <what this milestone delivers>
+Out: <explicitly deferred — the anti-scope-creep list>
+
+## Shared decisions & glossary deltas   (living — every task must honor these)
+- <cross-cutting rule, named from GLOSSARY.md>
+
+## Shared / risky contracts (freeze these first)
+- <contract name> -> owning task <slug>
+
+## Tasks (breadth-first decomposition; detail lives in each TASK.md)
+- [ ] <slug>   depends-on: none     — <one line>
+- [ ] <slug>   depends-on: <slug>   — <one line>
+
+## Exit criteria (observable; map each to the task that delivers it)
+- [ ] User can <observable behavior>        (← <slug>)

package/tooling/templates/MODEL_REGISTRY.md.tmpl

@@ -0,0 +1,6 @@
+# MODEL_REGISTRY  (which AI wrote this project — for reproducibility & audit)
+
+Model: <name>
+Version: <version/date>
+Adopted: {{date}}
+Notes: re-run the playbook golden-cases before changing this.

package/tooling/templates/PROJECT.md.tmpl

@@ -0,0 +1,42 @@
+# PROJECT — survivor layer (cross-milestone context)
+
+> The durable foundation that outlives every milestone and feeds context into each
+> TDD⇄ADD loop. Read this FIRST in any session. Keep it lean — one screen, not a
+> manual. Map to the AIDD diagram: Domain = DDD · Spec = SDD (living document) ·
+> UI/UX = UDD. When a loop reveals a gap here, come back and update this file —
+> that is the re-entrant arrow from the engine down to the foundation.
+
+slug: {{project}} · stage: {{stage}} · updated: {{date}}
+
+---
+
+## Domain (DDD) — the language and the boundaries
+<!-- One name per concept (the GLOSSARY holds the full term list). What are the
+     core entities, the bounded contexts/modules, and the invariants that MUST
+     always hold? This is the ubiquitous language the spec and code share. -->
+- Core concepts:
+- Bounded contexts / modules:
+- Invariants that must always hold:
+
+## Spec / Living Document (SDD) — what we are building, now
+<!-- The spec is a living document, not a frozen plan. This section POINTS to the
+     active milestone + frozen contracts; it does not duplicate them. -->
+- Active milestone → `.add/milestones/<slug>/MILESTONE.md`  (see `add.py status`)
+- Frozen contracts (survivor): the contracts other work builds against.
+- Settled vs still open:
+
+## Users (UDD) — UI/UX: design before code
+<!-- UI/UX-Driven Development: users use the interface, not the spec. Capture the
+     experience BEFORE code. Per-feature design detail lives in a DESIGN.md /
+     clickable prototype; keep here the cross-cutting UX stance + the source of truth.
+     For a no-UI project (CLI / library / service), say so and keep this short —
+     the "interface" is the command surface, API shape, or output it produces. -->
+- Primary users & the jobs they hire the product for:
+- Core user flows (happy + key alternative paths):
+- UI states every screen handles: loading · empty · error · success
+- Design source of truth → DESIGN.md / design system / clickable prototype
+
+## Key Decisions (append-only)
+| date | decision | why | outcome |
+|------|----------|-----|---------|
+| {{date}} | (first decision) | | |

package/tooling/templates/TASK.md.tmpl

@@ -0,0 +1,111 @@
+# TASK: {{title}}
+
+slug: {{slug}} · created: {{date}} · stage: {{stage}}
+phase: specify   <!-- specify -> scenarios -> contract -> tests -> build -> verify -> observe -> done -->
+
+> One file = one task. Fill sections top-to-bottom; the `add` skill drives each phase.
+> When a phase is unclear, read its book chapter in `.add/docs/` (linked per section).
+> The phase marker above is the single source of truth — keep it in sync via `add.py phase`.
+
+---
+
+## 1 · SPECIFY — the rules ▸ docs/03-step-1-specify.md
+
+Feature: <name>
+Framings weighed: <chosen> (chosen) · <alternative> · <alternative>
+Must:
+  - <required behavior>
+Reject:
+  - <bad input / situation> -> "<error_code>"
+After:
+  - <state that is true once it succeeds>
+Assumptions — least-sure first:
+  ⚠ <the one assumption most likely to be wrong> — least sure because <why>; if wrong: <cost>
+  - [ ] <next assumption, ranked> — confirm or deny; never carry an open one forward
+
+<!-- EXIT: every rule stated, every rejection named; assumptions ranked least-sure first, the top one or two ⚠-flagged with why + cost (or, for trivial scope, an honest "none material" that still names the single biggest risk). -->
+
+---
+
+## 2 · SCENARIOS — pass/fail cases ▸ docs/04-step-2-scenarios.md
+
+```gherkin
+Scenario: <short name>
+  Given <starting situation>
+  When <action>
+  Then <expected result>
+  And <what must remain unchanged>   # required for every rejection
+```
+
+<!-- EXIT: one scenario per Must AND per Reject; each result is observable. -->
+
+---
+
+## 3 · CONTRACT — freeze the shape ▸ docs/05-step-3-contract.md
+
+```
+<METHOD> <path>   body: { <fields> }
+  200 -> { <success fields> }
+  4xx -> { error: "<code>" | "<code>" }
+Schema: <tables/fields touched, and access pattern>
+```
+
+Status: DRAFT   <!-- becomes: FROZEN @ v1 once approved. Changing a frozen contract = change request back to SPECIFY. -->
+<!-- The freeze IS the one approval. Lead it with the bundle's least-sure flag: the 1–2 points
+     most likely wrong across the whole bundle, tagged [spec|scenario|contract|test], with why + cost.
+     The §1 ⚠ assumptions are its first feeder; a flag may point at a scenario or the contract too. See run.md. -->
+
+<!-- EXIT: frozen + every spec rejection has a contracted response + names match GLOSSARY + the bundle's least-sure flag was surfaced at the freeze (or an honest "none material"). -->
+
+---
+
+## 4 · TESTS — red safety net ▸ docs/06-step-4-tests.md
+
+Coverage target: <e.g. 90%>
+Plan (one test per scenario, asserting behavior not internals):
+  - test_<scenario>: arrange <Given> / act <When> / assert <Then> + assert <unchanged>
+
+Tests live in: `./tests/` · MUST run red (missing implementation) before Build.
+
+<!-- EXIT: one test per scenario; suite red for the RIGHT reason; target recorded. -->
+
+---
+
+## 5 · BUILD — AI writes code ▸ docs/07-step-5-build.md
+
+Safety rule (feature-specific): <e.g. debit+credit in one atomic transaction>
+Code lives in: `./src/`
+Constraints: do NOT change any test or the contract; allow-list packages only; ask if unclear.
+
+<!-- EXIT: all green; coverage held; no test/contract touched; no unlisted dependency. -->
+
+---
+
+## 6 · VERIFY — evidence + blind-spot checks ▸ docs/08-step-6-verify.md
+
+- [ ] all tests pass
+- [ ] coverage did not decrease
+- [ ] no test or contract was altered during build
+- [ ] concurrency / timing of the risky operation is safe
+- [ ] no exposed secrets, injection openings, or unexpected dependencies
+- [ ] layering & dependencies follow CONVENTIONS.md
+- [ ] a person reviewed and approved the change
+
+### GATE RECORD
+Outcome: <PASS | RISK-ACCEPTED | HARD-STOP>
+If RISK-ACCEPTED -> owner: <name> · ticket: <link> · expires: <date>   (never for a security gap)
+Reviewed by: <name> · date: <date>
+
+<!-- A security finding is ALWAYS HARD-STOP. Record exactly one outcome — no silent pass. -->
+
+---
+
+## 7 · OBSERVE — feed the next loop ▸ docs/09-the-loop.md
+
+Watch (reuse scenarios as monitors): <error rate / per-rejection rate / latency>
+Spec delta for the next loop: <what production taught you>
+
+### Competency deltas
+What did this loop teach the foundation? One line each, tagged by competency
+(`DDD · SDD · UDD · TDD · ADD`), status `open`, with evidence. See the `add` skill's `deltas.md`.
+<!-- e.g.  - [DDD · open] the model missed multi-tenancy (evidence: scenario_x failed) -->

package/tooling/templates/dependencies.allowlist.tmpl

@@ -0,0 +1,2 @@
+# dependencies.allowlist — one package per line; CI rejects anything not listed.
+# Defeats the AI "invented a plausible package name" supply-chain risk.