Skip to main content

Migrating to HarnSpec

This guide helps you migrate from existing SDD tools and documentation systems to HarnSpec.

Quick Overview​

HarnSpec migration focuses on two main areas:

  1. Metadata/Frontmatter (PRIMARY) - Use harnspec backfill to extract from git history
  2. Folder Organization (VARIES) - Depends on your source tool

Good news: HarnSpec is flexible about content format—you can keep your existing writing style!

Migration by Source Tool​

OpenSpec​

Source: openspec/specs/ + openspec/changes/archive/

OpenSpec is currently the most widely adopted SDD tool. Migration requires merging separate directories.

Quick migration with --auto:

# One-shot automatic migration
harnspec migrate ./openspec --auto

# Preview first
harnspec migrate ./openspec --auto --dry-run

Manual migration steps:

# 1. Copy and merge directories
cp -r openspec/specs/* specs/
cp -r openspec/changes/archive/* specs/

# 2. Renumber specs sequentially
mv specs/auth specs/001-user-authentication
mv specs/api-gateway specs/002-api-gateway

# 3. Rename spec.md → README.md
find specs -name 'spec.md' -execdir mv {} README.md \;

# 4. Generate frontmatter from git history
harnspec backfill --assignee --all

# 5. Update AGENTS.md commands
sed -i 's/openspec/harnspec/g' AGENTS.md

# 6. Validate
harnspec validate
harnspec board

Time: ~15-30 minutes for 20 specs (or < 1 minute with --auto)

GitHub Spec Kit​

Source: .specify/specs/

Already compatible! spec-kit uses the same folder structure (###-name/).

Quick migration with --auto:

harnspec migrate ./.specify/specs --auto

Manual migration steps:

# 1. Move from .specify/specs to specs/
mv .specify/specs specs/

# 2. Rename spec.md → README.md
find specs -name 'spec.md' -execdir mv {} README.md \;

# 3. Generate frontmatter from git history
harnspec backfill --assignee --all

# 4. Validate
harnspec validate
harnspec board

Time: ~5 minutes for 20 specs (or < 30 seconds with --auto)

AWS Kiro​

Source: .kiro/specs/

Kiro uses a similar structure to spec-kit with some AWS-specific conventions.

Quick migration with --auto:

harnspec migrate ./.kiro/specs --auto

Manual migration steps:

# 1. Move from .kiro/specs to specs/
mv .kiro/specs specs/

# 2. Rename any spec.md files to README.md
find specs -name 'spec.md' -execdir mv {} README.md \;

# 3. Generate frontmatter from git history
harnspec backfill --assignee --all

# 4. Validate
harnspec validate
harnspec board

Time: ~5 minutes for 20 specs

ADR/RFC (Generic Markdown)​

Source: docs/adr/, docs/rfc/, or similar

For Architecture Decision Records or RFCs stored as flat markdown files:

# Auto migration handles generic markdown
harnspec migrate ./docs/adr --auto

# Or manual: each ADR becomes a spec folder
# 0001-use-typescript.md → specs/001-use-typescript/README.md

The harnspec backfill Command​

This is your primary migration tool for generating frontmatter from git history.

Basic Usage​

# Extract timestamps from git history
harnspec backfill

# Include assignee from git author
harnspec backfill --assignee

# Extract all available metadata
harnspec backfill --all

# Preview changes without applying
harnspec backfill --dry-run

What It Extracts​

From git history:

  • created_at - First commit timestamp
  • updated_at - Last commit timestamp
  • completed_at - When status changed to 'complete'
  • assignee - First commit author (with --assignee)
  • transitions - Full status change history (with --transitions)

Set manually after:

  • priority - Defaults to 'medium', adjust with harnspec update --priority
  • tags - Defaults from folder names, adjust with harnspec update --tags
  • status - Inferred from content/history, adjust if needed

Example Output​

---
status: complete
created_at: '2024-03-15T10:23:45Z'
updated_at: '2024-11-08T14:30:12Z'
completed_at: '2024-03-20T16:45:00Z'
assignee: Alice Chen
priority: high
tags:
  - product
  - mvp
---

Using harnspec migrate​

For more complex migrations or AI-assisted workflows, use the harnspec migrate command.

Auto Mode (Recommended) ✅​

One-shot migration that detects format, restructures, and backfills automatically:

# Automatic migration - detects format and handles everything
harnspec migrate ./openspec --auto

# Preview without making changes
harnspec migrate ./openspec --auto --dry-run

What --auto does:

  1. Auto-detects source format (spec-kit, OpenSpec, or generic markdown)
  2. Bulk restructures files in one pass
  3. Runs backfill to populate timestamps and assignees
  4. Validates all specs at the end

This is the recommended approach for most migrations.

Manual Mode (Default)​

Outputs migration instructions for any AI tool:

harnspec migrate ./openspec

This generates a prompt you can copy to ChatGPT, Claude, Copilot, or any AI assistant:

You are helping migrate specification documents to HarnSpec format.

Source: ./openspec (23 documents found)

Your Task:
1. Analyze the source documents
2. Extract metadata (title, status, dates, priority)
3. For each document:
   - Run: harnspec create <name>
   - Run: harnspec update <name> --status <status>
   - Run: harnspec update <name> --priority <priority>
   - Edit content to match HarnSpec structure
4. Preserve decision rationale and relationships
5. Keep specs under 400 lines

Execute migration commands now.

AI-Assisted Mode​

Automated migration using AI CLI tools:

# Using GitHub Copilot CLI
harnspec migrate ./openspec --with copilot

# Using Claude CLI
harnspec migrate ./openspec --with claude

# Using Gemini CLI
harnspec migrate ./openspec --with gemini

Prerequisites:

  • AI CLI tool must be installed
  • Tool must be authenticated/configured

Options:

# Preview without changes
harnspec migrate ./openspec --dry-run

# Process in batches
harnspec migrate ./openspec --batch-size 10

# Auto-run backfill after migration
harnspec migrate ./openspec --backfill

Migration Checklist​

Use this checklist to ensure a complete migration:

Before Migration​

  • Backup your existing documentation
  • Review source folder structure
  • Check git history is available (for backfill)
  • Install HarnSpec: npm install -g harnspec
  • Initialize HarnSpec: harnspec init

During Migration​

  • Reorganize folders (if needed for your source tool)
  • Rename main spec files to README.md
  • Run harnspec backfill --assignee --all
  • Manually adjust priorities if needed
  • Manually adjust tags if needed
  • Verify status values are correct

After Migration​

  • Run harnspec validate to check for issues
  • Run harnspec board to visualize migration
  • Test spec discovery: harnspec list, harnspec search
  • Update any broken relationships (depends_on, related)
  • Migrate system prompts (AGENTS.md, .cursorrules)

Migrating System Prompts​

Don't forget to migrate AI guidance files!

Common Source Files​

# Source tools often have:
openspec/AGENTS.md
.cursorrules
.github/copilot-instructions.md
CLAUDE.md

HarnSpec Uses​

AGENTS.md (in project root)

Optional: Move SDD Workflow to Agent Skills​

HarnSpec supports Agent Skills via SKILL.md. This lets you keep AGENTS.md short and project-specific.

Recommended steps:

  1. Install the skill via harnspec skill install
  2. Use the installed SKILL.md at .github/skills/HarnSpec-sdd/
  3. Reduce AGENTS.md to project-specific rules only (<100 lines)
  4. Add a short note in AGENTS.md that references the skill
  5. Commit the skill folder so it is shareable

Minimal AGENTS.md example:

# AI Agent Instructions

## Project: Your Project

Core SDD workflow is defined in .github/skills/HarnSpec-sdd/SKILL.md.

## Project-Specific Rules
- Use pnpm instead of npm

Migration Strategy​

  1. Review existing AI guidance from source tool
  2. Preserve project-specific conventions
  3. Merge with HarnSpec AGENTS.md (created by harnspec init)
  4. Update commands: openspec → harnspec, etc.
  5. Keep team workflows intact

This ensures AI agents maintain continuity during the transition.

Common Migration Scenarios​

Scenario 1: spec-kit with Multiple Files Per Feature​

Source:

.specify/specs/
└── 001-task-management/
    ├── spec.md
    ├── plan.md
    ├── tasks.md
    └── contracts/
        └── api.yml

Options:

Option A: Keep sub-specs (recommended for complex features)

mv .specify/specs specs/
mv specs/001-task-management/spec.md specs/001-task-management/README.md
# Keep plan.md, tasks.md, contracts/ as-is
harnspec backfill --assignee --all

Option B: Consolidate (for simpler features)

# Merge spec.md + plan.md into README.md manually
# Then run backfill
harnspec backfill --assignee --all

Scenario 2: OpenSpec with Separate Directories​

Source:

openspec/
├── specs/auth/spec.md
└── changes/archive/2024-11-15-oauth/

Migration:

# 1. Merge directories
cp -r openspec/specs/* specs/
cp -r openspec/changes/archive/* specs/

# 2. Renumber and rename
mv specs/auth specs/001-authentication
find specs -name 'spec.md' -execdir mv {} README.md \;

# 3. Backfill metadata
harnspec backfill --assignee --all

# 4. Update AGENTS.md commands
sed -i 's/openspec/harnspec/g' AGENTS.md

Migrating from External Systems​

For systems like Linear, Jira, Confluence, or Notion:

Export First​

  1. Export to markdown or JSON from your system
  2. Place exports in a directory (e.g., ./exports/)
  3. Run migration on the exported files
# Export from Linear, Jira, etc. to ./exports/
harnspec migrate ./exports/

Why No Direct API Integration?​

HarnSpec intentionally doesn't integrate with external system APIs because:

  • Security: No credential management needed
  • Simplicity: No authentication, API keys, rate limits
  • Maintenance: External APIs change, break, require updates
  • Privacy: Your data stays local

Export workflows are well-established and let you maintain control.

Troubleshooting​

Issue: No git history available​

Solution: Set timestamps manually or use current date

# backfill will use current timestamp for specs without git history
harnspec backfill --assignee --all

# Or set manually
harnspec update 001 --priority high

Issue: Duplicate sequence numbers​

Solution: Use harnspec check to detect conflicts

harnspec check
# Fix conflicts by renaming folders manually

Issue: Content format doesn't match template​

Good news: HarnSpec is flexible! Keep your existing format.

You don't need to rewrite content to match a specific structure. HarnSpec's first principle is "Intent Over Implementation"—as long as the spec communicates intent clearly, the exact format doesn't matter.

Issue: Relationships broken after migration​

Solution: Update depends_on and related fields manually

# Edit frontmatter in README.md for each spec
---
depends_on: [002, 005]
related: [010, 012]
---

# Verify relationships
harnspec deps 001

Migration Time Estimates​

Based on real migrations:

Source ToolSpecsTime (Manual)Time (--auto)Complexity
OpenSpec2020 min< 1 min⚠️ Moderate
OpenSpec10060 min< 1 min⚠️ Moderate
spec-kit205 min< 30 sec✅ Easy
spec-kit10015 min< 30 sec✅ Easy
Kiro205 min< 30 sec✅ Easy
ADR/RFC2010 min< 30 sec✅ Easy

Note: Times include backfill and validation. Use --auto for fastest migration!

Getting Help​

Need migration support?

  • GitHub Issues: Report migration issues
  • Examples: See spec 063 for detailed examples
  • Command Help: Run harnspec migrate --help or harnspec backfill --help

Next Steps​

After migration:

  1. Learn the workflow: Creating & Managing Specs
  2. Set up AI integration: Agent Configuration
  3. Understand principles: First Principles
  4. Configure for your team: Configuration Reference