Repo conventions template

Copy into consuming repos when applying or retrofitting work-tracking. Replace {{…}} placeholders.

hoen.yaml (machine linkage)

Ask before adding or committing. When accepted:

cp path/to/hoen-library/library/skills/work-tracking/assets/hoen.example.yaml \
  hoen.yaml
# Or assets/hoen.example.github.yaml for github_projects
# Edit work_tracking.*

Validate:

node library/skills/work-tracking/scripts/validate-hoen-yaml.mjs

See hoen-config.md and work-tracking-manifest.md.

AGENTS.md section

## Plans and work tracking

WIP plans, ADRs, and epics with high-level tracking live on the team
**[product board]({{BOARD_URL}})**
(`Component type` = **{{COMPONENT_TYPE}}** for this repo; backend from `hoen.yaml`).
Repo truth stays in `docs/planning/`, `docs/wip/`, optional `*.effort.json`, and
optional **`hoen.yaml`**; the board only mirrors [shared rollup fields]({{HOEN}}/library/skills/work-tracking/references/shared-fields.md).

**When you update a plan or record progress in the repo**, refresh the linked board
item in the same session (all surfaces — e.g. GitHub issue body *and* project fields).

| Repo change | Update |
| --- | --- |
| `*.effort.json` step/group status | Plan 👀 block, `## Tracking` if new item, board via `format-sync.mjs` |
| ADR decision status | Status + progress headline |
| Plan promoted, archived, or renamed | Plan doc URL, Plan ID |

Lookup: plan **`## Tracking`** (Plan ID, Board item). Board/repo context from
`hoen.yaml` when present. Example: `{{PLAN_ID_EXAMPLE}}`.

Effort totals: **`plan-effort-estimate`** + **`format-sync.mjs`** — never hand-calculate.

Placeholder notes

Placeholder	Example
{{BOARD_URL}}	From hoen.yaml → work_tracking.board.url
{{COMPONENT_TYPE}}	Example Website · HoEN Library
{{PLAN_ID_EXAMPLE}}	example-plan-slug, adr-001-example-topic
{{HOEN}}	Path or submodule root to hoen-library

README.md paragraph

Plan and ADR progress for this repo is mirrored on the team product board
(link in `hoen.yaml` → `work_tracking.board.url`, `Component type` = **{{COMPONENT_TYPE}}**).
When you update plan progress or ADR status in git, refresh the linked board item
in the same session — see [AGENTS.md § Plans and work tracking](AGENTS.md#plans-and-work-tracking).

CONVENTIONS.md pointer

### Plans and work tracking

When plan progress or ADR status changes in git, update the corresponding board
item (board URL in `hoen.yaml`). See [AGENTS.md § Plans and work tracking](AGENTS.md#plans-and-work-tracking).

Plan / ADR doc block (all backends)

## Tracking

| Field | Value |
| --- | --- |
| **Plan ID** | `{{PLAN_ID}}` |
| **Work type** | {{WORK_TYPE}} |
| **Board item** | [{{ITEM_LABEL}}]({{ITEM_URL}}) |

Board identity: repo-root `hoen.yaml` (when committed). Shared fields:
`format-sync.mjs`. GitHub sync: `sync-from-hoen.mjs --input {{EFFORT_JSON}} --issue {{ISSUE}}`.

Placeholder	Epic with effort	ADR
{{ITEM_LABEL}}	#123 / card title	same
{{ITEM_URL}}	issue / Notion / Jira URL	same
Sync trigger	effort or phase status changes	accepted/open decisions change