template-conventions

Zforge Template Conventions

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

Core files

Always created by /plan:

| File | Owner | Purpose | |------|-------|---------| | 00_design_spec.md | /plan | 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 | | 05_progress/review.md | /zforge:review 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 | /zforge:retro 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 column of ## Evidence Required; the planner writes ## Acceptance after independently re-running the commands.
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; at acceptance the planner promotes only the ones reaching beyond the feature's implementation. The rest 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.

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 means re-running the named commands and re-walking the named methods rather than reading the agent's account of them. An unmet class becomes a standing flag in the overview and the feature is not complete while one is open.

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>
FILES: <count>
OPEN: <count of unresolved Open Items>

Everything else belongs in the phase file, which is what survives the session.

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

## 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.