Skip to main content

Large Project with Multiple Features

As projects grow beyond a handful of specs, you need better tools to maintain visibility and coordinate work. Learn the essential project management commands for working at scale.

Time: 15 minutes
Outcome: Master project management tools for large codebases

For Advanced Users

This tutorial assumes you're comfortable with basic HarnSpec workflows. If you're new, start with Your First Spec with AI.

Real-World Example​

Want to see these tools in action? Check out the HarnSpec project itself—a live example with 100+ specs showing real dependencies, numbering conventions, and project organization.

Try It Yourself

For the best learning experience, clone the HarnSpec repo locally and explore in visual mode:

git clone https://github.com/harnspec/harnspec.git
cd harnspec
npx @HarnSpec/cli ui

This gives you interactive access to the dependency graph, filtering, and all PM tools.

Throughout this tutorial, we'll reference actual specs from the HarnSpec codebase to show how these patterns work in practice.

Essential PM Tools​

HarnSpec provides five key tools for managing large projects:

  1. harnspec board - Kanban view of project status
  2. harnspec deps <spec> - Dependency analysis
  3. harnspec stats - Project health metrics
  4. harnspec list --tags <tags> - Filter by team/feature
  5. harnspec search <query> - Semantic search across specs

Let's explore each one.

1. Board View - Project Overview​

The board gives you instant visibility into what's happening across your entire project:

harnspec board

Shows all specs organized by status columns: Planned → In Progress → Complete → Archived

Example from HarnSpec project:

  • Planned: 15 specs (new features, enhancements)
  • In Progress: 0 specs (nothing actively being worked on)
  • Complete: 64 specs (shipped features)
  • Archived: 0 specs

The board also shows project health metrics:

  • Completion rate
  • Number of blocked specs (waiting on dependencies)
  • Recent activity

Use when: Starting your day, sprint planning, standup meetings

Pro tip: Specs with unmet depends_on relationships are flagged as "blocked"

2. Dependency Analysis​

Understand how specs relate before making changes:

harnspec deps <spec> --mode complete

Shows three types of relationships:

  • Dependencies (depends_on): What this spec needs before starting
  • Dependents (required_by): What specs need this one
  • Related: Contextually connected specs

Real example from HarnSpec:

harnspec deps 114  # Example Projects Scaffold

Shows:

  • Related to: 113 (Tutorial Simplification)
  • Both specs work together to improve the tutorial experience

Impact Analysis​

Before refactoring, check the blast radius:

harnspec deps <spec> --mode impact

Shows:

  • Direct dependents (specs that directly depend on this)
  • Transitive dependents (specs affected downstream)
  • Total impact count

Use when: Planning refactors, breaking changes, architectural decisions

Pro tip: --mode upstream shows only dependencies, --mode downstream shows only dependents

3. Project Statistics​

Get health metrics for your entire project:

harnspec stats

Shows:

  • Status distribution: How many specs in each state
  • Priority breakdown: Critical vs. nice-to-have work
  • Top tags: Most common categories
  • Recent activity: Latest spec updates

Use when: Sprint reviews, quarterly planning, tracking velocity

Watch for these red flags:

  • Too many "planned" specs (nothing shipping)
  • Too many "in-progress" specs (work not completing)
  • No recent activity (project stagnant)

4. Filtering and Organization​

By Tags​

Organize specs by team, feature area, or technology:

# See all specs for a team
harnspec list --tags team-frontend

# See all specs for a feature area
harnspec list --tags documentation

# See all specs for a milestone
harnspec list --tags v0.3.0

Real HarnSpec tags:

  • web, cli, http, docs - Component areas
  • ux, dx, performance - Quality attributes
  • v0.2.0, v0.3.0 - Release milestones

By Priority​

Focus on critical work:

harnspec list --priority critical
harnspec list --priority high

By Status​

Track work in specific states:

harnspec list --status planned      # Ready to start
harnspec list --status in-progress  # Currently active
harnspec list --status complete     # Shipped

Find specs by content, not just name:

harnspec search "authentication"
harnspec search "performance optimization"
harnspec search "dependency graph"

Search uses semantic matching—it understands context and finds relevant specs even without exact keywords.

Use when: Looking for similar patterns, finding related work, discovering existing solutions

Organization Patterns​

Numbering Conventions​

HarnSpec uses number ranges to group related work:

  • 010-029: Project setup and tooling
  • 040-059: Core features and workflows
  • 060-079: Advanced features and integrations
  • 080-099: Infrastructure and architecture
  • 100+: Ongoing improvements and polish

Benefits:

  • See feature area at a glance
  • Easy to insert new specs in logical places
  • Maintains chronological order within areas

Tagging Strategy​

Effective tags organize work across multiple dimensions:

# Component tags
web, cli, http, docs

# Quality attribute tags
ux, dx, performance, security

# Release milestone tags
v0.2.0, v0.3.0, v0.4.0

# Team/ownership tags (if multi-team)
team-frontend, team-backend, team-infra

Pro tip: Keep tags consistent across your project. Document your tagging conventions in your README.

Working with Dependencies​

Creating Dependencies​

Link specs when one blocks another:

# Spec B depends on Spec A completing first
harnspec link B --depends-on A

# Spec C depends on both A and B
harnspec link C --depends-on A,B

Clean up outdated dependencies:

harnspec unlink A --depends-on B    # Remove dependency

Live Example: HarnSpec Web UI​

See all these tools in action at harnspec.gitub.io—the HarnSpec project's own spec dashboard.

You'll see:

  • 100+ specs organized by status
  • Real dependency networks (e.g., spec 114 depends on 113)
  • Actual tagging patterns (docs, cli, http, web)
  • Priority distributions across the project
  • How numbering conventions work in practice

This is exactly what your project dashboard can look like.

Tips for Success​

Start Simple​

Don't over-organize from day one:

  1. Start with basic status tracking
  2. Add priority when you need to focus work
  3. Add tags when you need better filtering
  4. Add dependencies when work starts blocking

Regular Maintenance​

Keep your specs healthy:

  • Daily: Update status for active work
  • Weekly: Review board in standup/planning
  • Monthly: Check for stale specs, update priorities
  • Quarterly: Archive completed work, audit tags

Communication Patterns​

Use specs for async coordination:

  • Check harnspec deps before starting work
  • Run harnspec board in standups
  • Share harnspec stats in sprint reviews
  • Use harnspec search to find context before asking

What You Learned​

You now know how to:

✅ Use harnspec board for project visibility
✅ Analyze dependencies with harnspec deps
✅ Track health with harnspec stats
✅ Filter specs by tags, priority, and status
✅ Search semantically with harnspec search
✅ Organize specs with numbering and tagging conventions
✅ Manage dependencies without creating bottlenecks

Next Steps​

Apply to your project:

  • Run harnspec board in your next standup
  • Set up a tagging convention in your README
  • Check dependencies before starting new work
  • Review harnspec stats monthly for health checks

Explore advanced features:

Need help? Check FAQ or file an issue.