Skip to main content

Project Management

Track project health, manage dependencies, and validate spec quality with HarnSpec's project management features.

Board & Stats​

Get instant visibility into your project's health with board and stats commands.

Board Command​

Visual kanban view of your specs:

harnspec board

Shows specs organized by status columns:

  • 📅 Planned - Specs ready to start
  • ⏳ In Progress - Active work
  • ✅ Complete - Finished specs

Project Overview​

The board includes a project overview box:

  • Total specs count
  • Active vs Complete count
  • Completion percentage
  • Velocity metrics (cycle time, throughput)

Filtering​

Filter the board view:

# Show only high priority specs
harnspec board --priority high

# Show specs with specific tag
harnspec board --tag feature

# Combine filters
harnspec board --priority high --tag api

Stats Command​

Quick project metrics:

harnspec stats

Shows:

  • Overview: Total specs, active count, completion rate
  • Status: Visual bar chart of status distribution
  • Priority Focus: Breakdown by priority
  • Needs Attention: Critical/High priority specs not started
  • Velocity Summary: Cycle time and throughput

Full Analytics​

Get detailed analytics:

harnspec stats --full

Provides comprehensive project insights:

  • Detailed status metrics
  • Priority breakdown
  • Tag frequency analysis
  • Completion trends
  • Average time in each status
  • Health indicators

Example Output​

📋 Spec Kanban Board

╔════════════════════════════════════════════════════════════╗
║  Project Overview                                          ║
║  72 total · 15 active · 57 complete (79%)                  ║
║  🚀 Velocity: 0.5d avg cycle · 34.0/wk throughput          ║
╚════════════════════════════════════════════════════════════╝

📅 Planned (14)

  🔴 Critical (1)
    065-v03-planning #release #planning #milestone

  🟠 High (5)
    098-github-multi-project-integration #web #github

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

⏳ In Progress (1)

  🟡 Medium (1)
    105-docs-site-enhancements

Common Workflows​

Daily Standup:

# Quick project overview
harnspec board

# See what's in progress
harnspec board --status in-progress

# Check high priority items
harnspec board --priority high

Sprint Planning:

# Review project health
harnspec stats --full

# See what's ready to start
harnspec board --status planned

# Check capacity
harnspec stats

Weekly Review:

# Overall project metrics
harnspec stats --full

# Review completed work
harnspec board --status complete

# Identify bottlenecks
harnspec board --status in-progress

Project Health Indicators​

The board and stats commands help identify:

⚠️ Warning Signs:

  • Too many in-progress specs (focus issues)
  • Old specs without updates (stale work)
  • High percentage of planned specs (execution gap)
  • Specs with unmet dependencies (check with harnspec deps)

✅ Healthy Signals:

  • Steady completion rate
  • Balanced status distribution
  • Active recent updates
  • Clear priority focus

Dependencies​

Manage relationships between specs with dependency tracking.

Relationship Types​

HarnSpec has two types of relationships:

related - Bidirectional Soft Reference​

  • Meaning: Informational relationship (specs are connected/related)
  • Behavior: Automatically shown from both sides
  • Symbol: ⟷ (bidirectional arrow)

depends_on - Directional Blocking Dependency​

  • Meaning: Hard dependency - spec cannot start until dependencies complete
  • Behavior: Directional only (shows differently from each side)
  • Symbol: → (depends on) and ← (blocks)

Blocking Dependencies​

Use depends_on for hard dependencies:

# Spec A depends on Spec B
harnspec link spec-a --depends-on spec-b

# Spec A depends on multiple specs
harnspec link spec-a --depends-on spec-b spec-c

Shows differently from each side:

$ harnspec deps spec-a
Depends On:
  → spec-b [in-progress]  # A depends on B

$ harnspec deps spec-b
Required By:
  ← spec-a [planned]  # B is required by A

Use when:

  • Spec truly cannot start until another completes
  • There's a clear dependency chain
  • Work must be done in specific order

Deps Command​

View all relationships for a spec:

harnspec deps <spec>

Shows:

  • Specs this depends on (→)
  • Specs that depend on this (←)

Example Output:

📦 Dependencies for 042-api-gateway

Depends On:
  → 041-authentication [complete]
  → 038-database-setup [complete]

Required By:
  ← 044-integration-test [planned]
  ← 045-documentation [planned]

Best Practices​

1. Use depends_on Judiciously

Only for true blockers where work order matters:

# ✅ Good - Authentication needed before API gateway
harnspec link api-gateway --depends-on authentication

# ❌ Overuse - Documentation doesn't block implementation
# Instead: Document the relationship in the spec content

2. Avoid Circular Dependencies

# ❌ Bad - Circular dependency
harnspec link spec-a --depends-on spec-b
harnspec link spec-b --depends-on spec-a

HarnSpec will warn about circular dependencies.

3. Document Loosely Coupled Relationships

For specs that share context but don't block each other, document the connection in the spec content rather than using metadata. This keeps the dependency graph focused on true blockers.

Dependency Workflows​

Before Starting Work:

Check dependencies:

harnspec deps <spec>

Ensure all depends_on specs are complete before starting.

During Planning:

Map dependencies:

# View dependency tree
harnspec deps feature-spec

# Check what's blocked
harnspec board --status planned

Identifying Bottlenecks:

Find specs blocking others:

# Check what depends on this
harnspec deps <in-progress-spec>

# Look for "Required By" items

Dependency Patterns​

Sequential Work:

# Phase 2 depends on Phase 1
harnspec link phase-2 --depends-on phase-1

# Phase 3 depends on Phase 2
harnspec link phase-3 --depends-on phase-2

Parallel Work:

Features can be implemented in parallel. Document connections in spec content if coordination is needed.

Integration Point:

# Tests blocked until feature done
harnspec link tests --depends-on core-feature

Managing Changes​

Adding Dependencies:

# Add dependency
harnspec link my-spec --depends-on prerequisite-spec

Removing Dependencies:

When a dependency is no longer needed:

# Remove dependency
harnspec unlink my-spec --depends-on old-requirement

Best Practices​

Board & Stats​

  1. Check daily - Start your day with harnspec board
  2. Review weekly - Use harnspec stats --full for trends
  3. Limit WIP - Keep in-progress specs under control
  4. Update regularly - Keep status current with harnspec update
  5. Use priorities - Focus on high-priority work first

Dependencies​

  1. Use depends_on for true blockers - Only when work order matters
  2. Check before starting - Ensure dependencies are met
  3. Avoid circular deps - Keep dependency chains simple
  4. Document context in content - For loosely coupled specs, mention relationships in the spec text rather than metadata
  5. Use CLI commands - harnspec link/unlink, not manual edits

Next Steps​