Skip to main content

Built-in Metadata

HarnSpec specs store a small set of system-managed fields in frontmatter so humans, dashboards, and AI agents share the same truth. Keep these fields accurate—automation, Kanban boards, and CLI-powered workflows all rely on them.

Status Lifecycle​

  1. planned — intent captured, implementation not started.
  2. in-progress — work is actively happening.
  3. blocked — external dependency is preventing progress.
  4. complete — implementation finished and validated.
  5. archived — historical reference only.

Update status the moment implementation starts or stops; status tracks the work, not the spec writing process. Use harnspec update <spec> --status <value> so every tool (and AI agent) sees the same state.

Relationships​

HarnSpec uses depends_on to capture blocking dependencies:

  • depends_on — Directional dependency. Spec A cannot start until Spec B is complete. 
    depends_on:
      - 082
    Appears as → in harnspec deps and automatically adds a "Required By" entry on the dependency.

Use depends_on when work truly must be done in a specific order. For loosely related specs that share context but don't block each other, document the relationship in the spec content instead.

Priority & Tags​

These fields make specs filterable and keep planning lightweight.

  • priority communicates urgency or impact. Typical values: low, medium, high, critical.
  • tags provide fast slicing across the portfolio. Stick to a shared vocabulary (for example frontend, backend, docs, infra). 
    priority: high
    tags: [api, backend, security]

Aim for 2-4 tags per spec. Too many tags reduce signal and make search noisy.

Example Frontmatter​

---
status: in-progress
priority: high
tags: [api, backend]
depends_on: [082]
created: '2025-11-16'
---

Why Metadata Discipline Matters​

  • Projects stay honest — Boards, burndown charts, and roadmap exports use these fields directly.
  • AI stays aligned — Agents decide whether to edit a spec or start implementation based on status, priority, and dependencies.
  • Context sharing improves — Tags, relationships, and status transitions tell newcomers where to plug in without another meeting.

Treat the frontmatter like code: update it as soon as reality changes and validate with harnspec validate before merging.