Skip to main content

Frontmatter

HarnSpec uses YAML frontmatter for structured metadata at the top of each spec.

What is Frontmatter?​

Frontmatter is machine-readable metadata in YAML format:

---
status: in-progress
created: 2025-11-02
tags: [api, security]
priority: high
---

# Your Spec Title

[Spec content...]

Core Fields​

status (required)​

Current state of the spec.

Valid values:

  • planned - Not started yet
  • in-progress - Currently being worked on
  • complete - Work is finished
  • archived - Work is archived

Example:

status: in-progress

created (required)​

Date when spec was created (ISO 8601 format).

Format: YYYY-MM-DD

Example:

created: 2025-11-02

This is auto-filled when you use harnspec create.

Optional Fields​

tags​

Array of tags for categorization and filtering.

Example:

tags: [api, security, mvp]

Usage:

harnspec list --tag=api

priority​

Importance level of the work.

Valid values:

  • low
  • medium
  • high
  • critical

Example:

priority: high

Usage:

harnspec list --priority=high

completed​

Date when work was completed (auto-added).

Format: YYYY-MM-DD

Example:

completed: 2025-11-05

This is automatically added when you set status: complete.

Custom Fields​

You can define custom fields in .harnspec/config.json:

{
  "frontmatter": {
    "custom": {
      "assignee": "string",
      "reviewer": "string",
      "epic": "string",
      "sprint": "number",
      "estimate": "string"
    }
  }
}

Supported types:

  • string
  • number
  • boolean
  • array

Usage:

harnspec create feature --field assignee=alice --field sprint=42
harnspec list --field epic=PROJ-123

See Custom Fields for details.

Visual Badges​

HarnSpec auto-generates visual badges from frontmatter:

> **Status**: ⏳ In progress · **Priority**: High · **Created**: 2025-11-02 · **Tags**: api, security

Status icons:

  • 📅 Planned
  • ⏳ In progress
  • ✅ Complete
  • 📦 Archived

These badges are automatically updated when you use harnspec update.

Full Example​

---
status: in-progress
created: 2025-11-02
completed: 
tags: [api, authentication, security]
priority: high
assignee: alice
reviewer: bob
epic: PROJ-123
sprint: 42
---

# User Authentication API

> **Status**: ⏳ In progress · **Priority**: High · **Created**: 2025-11-02  
> **Tags**: api, authentication, security · **Assignee**: alice · **Reviewer**: bob

[Spec content...]

Editing Frontmatter​

Via CLI​

Recommended approach:

harnspec update 001 --status=complete --priority=critical

This updates both frontmatter and visual badges.

Manual Editing​

You can also edit frontmatter directly in the file:

  1. Open README.md in editor
  2. Modify YAML between --- markers
  3. Save file

Note: Manual edits don't auto-update visual badges. Run harnspec update to sync.

Best Practices​

Start Minimal

Begin with just status and created. Add fields only when you need them.

Use Tags Consistently

Establish tag conventions for your team. Examples: api, ui, backend, security.

Update Status Regularly

Keep status current. Use harnspec list to see what's in progress.

Don't Over-Customize

Add custom fields sparingly. Each field is overhead to maintain.

Next: Learn about Custom Fields or explore Variables.