Skip to main content

What is HarnSpec?

Ship faster with higher quality. Lean specs that both humans and AI understand.

HarnSpec brings agile principles to SDD (Spec-Driven Development)—small, focused documents (<2,000 tokens) that keep you and your AI aligned.

Think of it as "Markdown for Project Management": Simple, structured, and machine-readable.

Quick Start​

# Try with a tutorial project
npx harnspec init --example dark-theme
cd dark-theme && npm install && npm start

# Or add to your existing project
npm install -g harnspec && harnspec init

Visualize your project:

harnspec board    # Kanban view
harnspec stats    # Project metrics
harnspec ui       # Web UI at localhost:3000

Next: Your First Spec with AI (10 min tutorial)

Why HarnSpec?​

High velocity + High quality. Other SDD frameworks add process overhead (multi-step workflows, rigid templates). Vibe coding is fast but chaotic (no shared understanding). HarnSpec hits the sweet spot:

  • Fast iteration - Living documents that grow with your code
  • AI performance - Small specs = better AI output (context rot is real)
  • Always current - Lightweight enough that you actually update them

📖 Compare with Spec Kit, OpenSpec, Kiro →

Features​

FeatureDescription
📊 Kanban Boardharnspec board - visual project tracking
🔍 Smart Searchharnspec search - find specs by content or metadata
🔗 DependenciesTrack spec relationships with depends_on and related
🎨 Web UIharnspec ui - browser-based dashboard
📈 Project Statsharnspec stats - health metrics and bottleneck detection
🤖 AI-NativeCLI toolset designed for AI assistants

AI Integration​

Works with any AI coding assistant via CLI commands or Agent Skills:

# AI Agent Instructions
## Project: [Project Name]
- Use `harnspec board` to see project state
- Use `harnspec search` to find relevant context
- Use `harnspec create` for new specs

Compatible with: VS Code Copilot, Claude Code, Gemini CLI, Cursor, Windsurf, Kiro CLI, Kimi CLI, Qodo CLI, Amp, Trae Agent, Qwen Code, Droid, and more.

📖 Full AI integration guide →

What You Get​

  • Core CLI: Manage specs, track status, and visualize dependencies.
  • Agent Skills: Project-specific guidance for AI agents.
  • Visual Mode: A beautiful web interface for browsing your project's spec graph.

A Simple Example​

A HarnSpec is just a Markdown file with frontmatter:

./specs/001-user-auth-api/README.md
---
status: in-progress
created: 2025-11-07
priority: high
tags: [api, auth]
---

# User Authentication API

## Goal
Enable secure user login and session management for the mobile app.

## Key Scenarios
1. User logs in with email/password → receives JWT token
2. User accesses protected endpoint with token → gets data
3. User token expires → receives 401, must re-authenticate

## Acceptance Criteria
- [ ] Login endpoint returns valid JWT on success
- [ ] JWT includes user ID and expiration
- [ ] Protected endpoints verify JWT signature

## Non-Goals
- Social login (future feature)
- Password reset (separate spec)

Documentation​

📖 Full Documentation · CLI Reference · First Principles · FAQ

Community​

💬 Discussions · 🐛 Issues · 🤝 Contributing

Next Steps​