Skip to main content

Creating & Managing Specs

Learn the essential operations for working with HarnSpec specs: creating, updating, viewing, and managing the spec lifecycle.

Creating a New Spec​

Basic Creation​

harnspec create my-feature

This creates a new spec with:

  • Auto-generated unique ID (e.g., 042-my-feature)
  • Initialized frontmatter (status: planned, created date)
  • Basic spec template in specs/042-my-feature/README.md

Interactive Creation​

harnspec create

Without a name, you'll be prompted interactively for:

  • Spec name
  • Optional description
  • Initial status (defaults to planned)

Advanced Options​

# Create with initial status
harnspec create my-feature --status in-progress

# Create with tags
harnspec create my-feature --tags api,backend

# Create with priority
harnspec create my-feature --priority high

See also: CLI Reference: create for all options

Updating Specs​

Status Updates​

Update spec status (REQUIRED - never edit frontmatter manually):

# Move to in-progress
harnspec update 042 --status in-progress

# Mark as complete
harnspec update 042 --status complete

# Archive when done
harnspec update 042 --status archived

Available statuses: planned, in-progress, complete, archived

Priority and Tags​

# Set priority
harnspec update 042 --priority high

# Add/update tags
harnspec update 042 --tags api,backend,refactor

# Assign to someone
harnspec update 042 --assignee alice

Important: Always use harnspec update for system-managed fields. Manual edits will corrupt metadata.

See also: CLI Reference: update

Viewing Specs​

Quick View​

# View spec (formatted for reading)
harnspec view 042

# View sub-spec file
harnspec view 042/DESIGN.md

Raw Output​

# Get raw markdown (for parsing)
harnspec view 042 --raw

# Get structured JSON
harnspec view 042 --json

Open in Editor​

# Open in default editor
harnspec open 042

# Open specific sub-spec
harnspec open 042/TESTING.md

See also: CLI Reference: view

Listing Specs​

View All Specs​

# List all specs
harnspec list

# List by status
harnspec list --status in-progress

# List by tag
harnspec list --tag api

Kanban Board View​

# Visual board view
harnspec board

Shows specs grouped by status with project health metrics.

See also: Board & Stats

Managing Spec Files​

Sub-Spec Files​

For complex specs, split into multiple files:

# List all files in a spec
harnspec files 042

Common sub-spec files:

  • README.md - Main spec (required)
  • DESIGN.md - Detailed design
  • IMPLEMENTATION.md - Implementation plan
  • TESTING.md - Test strategy
  • CONFIGURATION.md - Config examples

Why? Keeps each file under 2,000 tokens (Context Economy principle).

See also: Sub-Spec Files

Viewing File List​

# Show all files in spec
harnspec files 042

Output:

📄 Files in 042-my-feature

Required:
  ✓ README.md        (234 lines)  Main spec

Documents:
  ✓ DESIGN.md        (187 lines)
  ✓ TESTING.md       (145 lines)

Total: 3 files, 566 lines

Archiving Specs​

When work is complete and you want to move spec out of active view:

# Archive completed spec
harnspec update 042 --status archived

Archived specs:

  • Don't appear in default harnspec list
  • Still searchable
  • Can be unarchived later

Dependencies and Relationships​

Declaring Dependencies​

Use harnspec link to manage dependencies (do not edit frontmatter manually):

# Add dependency (blocking)
harnspec link 042 --depends-on 041

Viewing Dependencies​

# Show dependency graph
harnspec deps 042

Output:

Dependency Graph for 042-my-feature

Depends On:
  → 041-authentication [complete]

Required By:
  ← 043-dashboard [in-progress]

See also: Dependencies

Validation​

Check spec structure and frontmatter:

# Validate all specs
harnspec validate

# Validate specific spec
harnspec validate 042

Catches:

  • Invalid frontmatter structure
  • Missing required fields
  • Dependency cycles
  • Token count warnings (>3,500 tokens reduces AI effectiveness)

See also: Validation

Find specs by content, name, or metadata:

# Search spec content
harnspec search "authentication"

# Search with filters
harnspec search "API" --status in-progress --tag backend

See also: Finding Specs

Common Workflows​

Starting New Work​

# 1. Create spec
harnspec create auth-refactor --tags security,backend

# 2. Edit spec (define problem, solution, success criteria)
harnspec open 042

# 3. Move to in-progress when ready
harnspec update 042 --status in-progress

Completing Work​

# 1. Mark complete
harnspec update 042 --status complete

# 2. Validate everything still works
harnspec validate

# 3. Optional: Archive if no longer needed
harnspec update 042 --status archived

Complex Spec Management​

# 1. Check if spec is getting too large
harnspec tokens 042

# 2. If >3,500 tokens, split into sub-specs
# Create DESIGN.md, TESTING.md, etc.

# 3. Verify structure
harnspec files 042

Best Practices​

DO:

  • ✅ Use harnspec update for status/priority/tags (never edit frontmatter)
  • ✅ Use harnspec link for relationships
  • ✅ Keep README.md focused (use sub-specs for detail)
  • ✅ Update status as work progresses
  • ✅ Archive completed specs to reduce clutter
  • ✅ Validate regularly (harnspec validate)

DON'T:

  • ❌ Manually edit system-managed frontmatter (status, priority, tags, assignee, transitions, timestamps, depends_on, related)
  • ❌ Let specs grow beyond 3,500 tokens without splitting
  • ❌ Leave specs in stale status
  • ❌ Skip validation before committing

Next Steps​

Reference: CLI Documentation for complete command reference