Template Conventions

---
name: template-conventions
description: >
  This skill should be used when the user asks to "plan a feature", "what goes
  in the phase file", "which file owns this", "what evidence class is this",
  "how do I verify a claim no test can settle", "where should this doc go", or
  when writing, reading or updating any zforge feature document under
  docs/{feature}/. Provides the template structure, file ownership rules, the
  two-axis evidence scale for what was executed and what was judged, phase
  states, and naming conventions.
---

# Zforge Template Conventions

Features are documented in `docs/{feature_name}/`, snake_case.

## Core files

Always created by the zforge plan workflow:

| File | Owner | Purpose |
|------|-------|---------|
| `00_design_spec.md` | Planner | Problem, actors, requirements, boundary, acceptance vocabulary |
| `01_context.md` | Planner | Doc Map, key decisions, open questions with owner and method |
| `02_plan.md` | Planner | Technical plan, phase decomposition, Verification Matrix, environment assumptions, invariants |
| `discussion.md` | Planner | Reasoning generated during planning — written while thinking, not after |
| `decision_review.md` | Planner appends · user adjudicates | Decisions made without blocking, awaiting review |
| `05_progress_overview.md` | **Planner only** | Phase status, standing flags |
| `05_progress/05_XX_*.md` | One agent each | Per-phase contract, evidence, decisions, work log |
| `session_log.md` | Planner | Which sessions touched this feature, and how they ended |

Created when the feature needs them, never as empty placeholders:

| File | When |
|------|------|
| Core patterns doc | The feature changes data models, abstractions or architectural patterns. Without it agents follow the checklist and write structurally wrong code |
| `03_integration_summary.md`, `04_integration_plan.md` | The plan spans backend and frontend |
| `07_harness_conventions.md` | A phase learns something about how the project is run and observed that a later phase would otherwise pay for again |
| `05_progress/review.md` | The zforge review workflow has findings |
| `06_post_deployment.md` | At completion |
| `08_configuration.md`, `09_troubleshooting.md` | Config or gotchas emerge |
| `10_`–`12_refactor_*` | The task is a refactoring rather than a new feature |
| `.zforge-retro/*.md` | The zforge retro workflow is invoked |

## Numbering

`00`–`02` and the `05` family have fixed prefixes. **Everything else is named for what it is** and numbered by creation order in whatever slot is free — the name carries the identity, the number only sorts. Register every document in the **Doc Map** in `01_context.md` with its purpose and which phases it binds.

Running ledgers are unnumbered: `discussion.md`, `decision_review.md`, `session_log.md`. Each has a distinct job — reasoning during thinking, decisions settled, what happened when.

## Ownership

1. **`05_progress_overview.md` — planner only.** Implementation agents never write it. This is what prevents contested writes.
2. **Phase files — one agent each.** An agent reads and writes its own phase file and the source files in its declared surface.
3. **`## Acceptance` is planner-owned** even though it lives in the agent's file. The agent fills the *achieved* and *artifact* columns of `## Evidence Required`; the planner writes `## Acceptance` after independently verifying them — the acceptance report verbatim, an adjudication line and a promoted line, nothing more.
4. **`00_design_spec.md`** is not modified by agents unless the user says so.
5. **`decision_review.md`** — agents record every decision in their phase file's `## Decisions` and mark its reach; at acceptance the planner promotes the `outward` rows — the ones **reaching beyond the feature's implementation** — and does not read the rest, which stay in the phase file where phase agents already read them. The ledger is an adjudication queue for the user, not an index of everything decided.
6. **`07_harness_conventions.md` — written by whoever learns the fact, read by every phase.** The phase agent or the acceptance agent appends a row at the moment it learns how this project is run and observed; the planner binds the file into later phases' `## Required Context` and, at completion, graduates the facts still true into the project's conventions document.

## Evidence

Phases declare what class of evidence closes them, and the planner confirms it. See `references/evidence-scale.md` for the classes, how to choose one at plan time, and what happens when achieved falls short of required.

Two axes. **E0–E4** for what was executed, ranked by what each rules out — algorithm errors, integration mismatches, runtime divergence, wiring defects. **J0–J2** for what was judged: a claim no test runner settles, checked by a stated method against a named referent. Classes rank within an axis only; neither substitutes for the other.

The short version: `02_plan.md`'s Verification Matrix declares the classes per phase before work starts, each phase's `## Evidence Required` inherits its row, and acceptance verifies rather than reads — every row reconciled against the artifact it names, and what a fact forces or judgment selects re-executed.

**Rows are written when their commands run, from the artifact each command wrote**, with artifacts named per run so a re-run cannot overwrite the file an earlier row quotes. A figure presented as a measurement appears verbatim in its artifact or the row says it cannot. This is what makes the cheap half of acceptance possible at all.

Artifacts live in `/tmp/zforge/artifacts/{feature}/` — outside every repository, and dropped when the feature closes. An artifact is the smallest file that carries the figures its row quotes, one per row per run and never a directory; state a command produced stays where it was produced and is cited in place. A row cites an artifact by its full path. The docs tree carries the finding and the path; the file itself is working state that acceptance reads once.

Where achieved falls short of required, the gap is settled by materiality: a **material** shortfall becomes a standing flag in the overview and the feature is not complete while one is open, and an **immaterial** one is accepted with the reasoning recorded. Two shortfalls are never immaterial — a command that selected nothing and exited 0, and a user-reachable surface nothing reached. The achieved class is recorded as reached either way.

## Reporting

There is no signal protocol. Phase state is the `> Status:` header in the phase file; completion is delivered by the harness. An agent's final report is:

```
STATUS: DONE | PAUSED | FAILED
REASON: <only when PAUSED — the trigger that fired, or USAGE_LIMIT_95>
EVIDENCE: <one line per Evidence Required row>
DECISIONS: <count> (<n> outward)
FILES: <count>
OPEN: <count of unresolved Open Items>
```

Everything else belongs in the phase file, which is what survives the session. Before reporting, the agent writes its session-log row and sets `> Status:` to the state it reports; COMPLETED is set only by acceptance.

Legacy `<!-- AGENT_SIGNAL:... -->` comments in pre-v3 feature directories are inert history.

## Phase file sections

`## Agent Prompt` (authoritative) · `## Required Context` · `## Evidence Required` · `## Environment Assumptions` · `## Checklist` · `## Decisions` · `## Open Items` · `## Files Created/Modified` · `## Session Log` · `## Resume Point` (only when the agent stopped early) · `## Acceptance`

`## Decisions` carries a `Reach` column: `feature` by default, `outward` for a decision that reaches beyond the feature. The planner promotes the `outward` rows to `decision_review.md`. A fact about how the project is run and observed is not a decision; it goes straight into `07_harness_conventions.md`.

`## Open Items` is the single home for anything needing the planner or the user — question, error, blocker, or evidence gap — with a `kind` column distinguishing them.

## Naming

- Feature folders: `snake_case` — `ai_assistant/`
- Phase files: `05_XX_description.md` — `05_01_backend_schema.md`
- Archive: `_archive/{name}__{date}.md`

For the full file tree, ownership matrix, and per-section detail, see `references/full-template.md`.