Template Conventions

---
name: template-conventions
description: >
  Use when working with zforge feature documentation templates,
  planning features with /plan, tracking progress with /track,
  or resuming features with /feature-resume. Provides the standard
  template structure, file ownership rules, and naming conventions.
---

# Zforge Template Conventions

## Template Structure

Features are documented in `docs/{feature_name}/` using snake_case folder names.

### Core Files

| # | File | Owner | Purpose |
|---|------|-------|---------|
| 00 | `00_design_spec.md` | /plan (interactive) | Requirements, architecture, constraints, risks |
| 01 | `01_context.md` | Planner | Feature context, key decisions, architecture overview |
| 02 | `02_plan.md` | Planner | Technical plan: schema, endpoints, phases, file structure |
| 03 | `03_integration_summary.md` | Planner | API types, mapping, frontend files (if frontend involved) |
| 04 | `04_integration_plan.md` | Planner | Step-by-step frontend integration guide |
| 05 | `05_progress_overview.md` | Planner ONLY | Phase status summary — implementation agents NEVER touch this |
| 05/ | `05_progress/05_XX_*.md` | Implementation Agent | Per-phase checklist, session log, files modified |
| 05/ | `05_progress/review.md` | Planner (append-only) | Compiled agent reviews for human reading |
| — | `session_log.md` | Planner | Session tracking — which Claude Code sessions touched this feature |
| — | `.zforge-retro/*.md` | /retro only | Plugin eval artifacts — only created when /retro is invoked |
| 06 | `06_post_deployment.md` | Planner | Smoke tests, deferred features, rollback plan |
| 07 | `07_testing_overview.md` | Planner | Testing guidance |
| 07/ | `07_testing/*.md` | Mixed | Test plan, scripts, results |
| 08 | `08_configuration.md` | Planner | Env vars, feature flags, external services |
| 09 | `09_troubleshooting.md` | Planner | Issues, solutions, debug commands |

### Refactoring Extension (10+)

When the task is a refactoring rather than a new feature, the 10+ range is used:

| # | File | Owner | Purpose |
|---|------|-------|---------|
| 10 | `10_refactor_spec.md` | Planner | Refactoring requirements, goals, scope, what's changing and why |
| 11 | `11_refactor_context.md` | Planner | Current-state audit: existing architecture, code paths, dependencies being refactored |
| 12 | `12_refactor_plan.md` | Planner | Step-by-step refactoring/migration plan, breaking changes, compatibility notes |

Further numbers (13, 14, ...) can be added as needed for the specific refactoring scope.

### Files Created by `/plan`

`/plan` always creates: `00_design_spec.md`, `01_context.md`, `02_plan.md`, `05_progress_overview.md`, `05_progress/05_00_agent_prompts_index.md`, `session_log.md`

Additional files (`03`, `04`, `06`-`10`) are created as needed during implementation.

## Ownership Rules

1. **`00_design_spec.md`** — Generated by `/plan` interactively. Agents do NOT modify unless user explicitly instructs.
2. **`05_progress_overview.md`** — ONLY the planner updates this. Implementation agents never touch it. Prevents race conditions.
3. **Phase files (`05_XX_*.md`)** — Each assigned to exactly one agent. Agent reads and writes only its own phase file.
4. **`05_progress/review.md`** — Planner appends phase reviews. Human-read only.

## Signal Protocol

Implementation agents write exactly ONE signal at the end of their phase file, including a UTC timestamp and their shell PID:

```
<!-- AGENT_SIGNAL:DONE T:2026-02-09T19:30:45Z PID:12345 -->      All checklist items complete
<!-- AGENT_SIGNAL:PAUSED T:2026-02-09T19:30:45Z PID:12345 -->    Needs input, question in ## Questions
<!-- AGENT_SIGNAL:FAILED T:2026-02-09T19:30:45Z PID:12345 -->    Unrecoverable error, in ## Errors
```

- **T:** — `date -u +%Y-%m-%dT%H:%M:%SZ` — lets the monitor ignore stale signals from previous sessions
- **PID:** — `echo $$` — lets the monitor verify the signal came from the expected agent process

Agent STOPS immediately after writing a signal.

## Naming Conventions

- Feature folders: `snake_case` (e.g., `ai_assistant/`)
- Files: numbered prefix (`01_`, `05_02_`)
- Phase files: `05_XX_description.md` (e.g., `05_01_backend_schema.md`)
- Archive: `_archive/{name}__{date}.md`

## Phase File Structure

Each `05_progress/05_XX_*.md` contains these sections:
- `## Agent Prompt` — Instructions for the assigned agent
- `## Phase Scope` — What this phase covers
- `## Checklist` — Tasks to complete (checkboxes)
- `## In Progress` / `## Completed` / `## Blocked / Issues`
- `## Files Created/Modified` — Audit trail
- `## Session Log` — Date, session #, steps, summary
- `## Review` — Agent writes summary before DONE signal
- `## Questions` — For PAUSED signal
- `## Errors` — For FAILED signal

For full template details, see `references/full-template.md`.