@harnspec/cli 0.0.1

package/templates/detailed/AGENTS.md

@@ -0,0 +1,118 @@
+# AI Agent Instructions
+
+## Project: {project_name}
+
+## 🚨 CRITICAL: Before ANY Task
+
+**STOP and check these first:**
+
+1. **Discover context** → Use `board` tool to see project state
+2. **Search for related work** → Use `search` tool before creating new specs
+3. **Never create files manually** → Always use `create` tool for new specs
+
+> **Why?** Skipping discovery creates duplicate work. Manual file creation breaks HarnSpec tooling.
+
+## 🔧 Managing Specs
+
+### CLI Commands with Agent Skills
+
+| Action | Command |
+|--------|---------|
+| Project status | `harnspec board` |
+| List specs | `harnspec list` |
+| Search specs | `harnspec search "query"` |
+| View spec | `harnspec view <spec>` |
+| Create spec | `harnspec create <name>` |
+| Update spec | `harnspec update <spec> --status <status>` |
+| Link specs | `harnspec rel add <spec> --depends-on <other>` |
+| Unlink specs | `harnspec rel rm <spec> --depends-on <other>` |
+| Dependencies | `harnspec deps <spec>` |
+| Token count | `harnspec tokens <spec>` |
+| Validate specs | `harnspec validate` |
+
+## ⚠️ Core Rules
+
+| Rule | Details |
+|------|---------|
+| **NEVER edit frontmatter manually** | Use `update`, `link`, `unlink` for: `status`, `priority`, `tags`, `assignee`, `transitions`, timestamps, `depends_on` |
+| **ALWAYS link spec references** | Content mentions another spec → `harnspec link <spec> --depends-on <other>` |
+| **Track status transitions** | `planned` → `in-progress` (before coding) → `complete` (after done) |
+| **Keep specs current** | Document progress, decisions, and learnings as work happens. Obsolete specs mislead both humans and AI |
+| **No nested code blocks** | Use indentation instead |
+
+### 🚫 Common Mistakes
+
+| ❌ Don't | ✅ Do Instead |
+|----------|---------------|
+| Create spec files manually | Use `create` tool |
+| Skip discovery | Run `board` and `search` first |
+| Leave status as "planned" | Update to `in-progress` before coding |
+| Edit frontmatter manually | Use `update` tool |
+| Complete spec without documentation | Document progress, prompts, learnings first |
+
+## 📋 SDD Workflow
+
+```
+BEFORE: board → search → check existing specs
+DURING: update status to in-progress → code → document decisions → link dependencies
+AFTER:  document completion → update status to complete
+```
+
+**Status tracks implementation, NOT spec writing.**
+
+## Spec Dependencies
+
+Use `depends_on` to express blocking relationships between specs:
+
+- **`depends_on`** = True blocker, work order matters, directional (A depends on B)
+
+Link dependencies when one spec builds on another:
+
+```bash
+harnspec link <spec> --depends-on <other-spec>
+```
+
+## When to Use Specs
+
+| ✅ Write spec | ❌ Skip spec |
+|---------------|--------------|
+| Multi-part features | Bug fixes |
+| Breaking changes | Trivial changes |
+| Design decisions | Self-explanatory refactors |
+
+## Token Thresholds
+
+| Tokens | Status |
+|--------|--------|
+| <2,000 | ✅ Optimal |
+| 2,000-3,500 | ✅ Good |
+| 3,500-5,000 | ⚠️ Consider splitting |
+| >5,000 | 🔴 Must split |
+
+## Quality Validation
+
+Before completing work, validate spec quality:
+
+```bash
+harnspec validate              # Check structure and quality
+harnspec validate --check-deps # Verify dependency alignment
+```
+
+Validation checks:
+
+- Missing required sections
+- Excessive length (>400 lines)
+- Content/frontmatter dependency misalignment
+- Invalid frontmatter fields
+
+## First Principles (Priority Order)
+
+1. **Context Economy** - <2,000 tokens optimal, >3,500 needs splitting
+2. **Signal-to-Noise** - Every word must inform a decision
+3. **Intent Over Implementation** - Capture why, let how emerge
+4. **Bridge the Gap** - Both human and AI must understand
+5. **Progressive Disclosure** - Add complexity only when pain is felt
+
+---
+
+**Remember:** HarnSpec tracks what you're building. Keep specs in sync with your work!

package/templates/detailed/README.md

@@ -0,0 +1,28 @@
+# Detailed Template
+
+For complex specs that benefit from structured sub-specs. Demonstrates how to manage token limits.
+
+## What's Included
+
+- **AGENTS.md** - Same AI agent instructions as standard template
+- **Sub-spec structure** - README.md + DESIGN.md + PLAN.md + TEST.md
+- Demonstrates splitting specs to stay under token limits
+- Example of real-world sub-spec organization
+
+## When to Use
+
+- Complex features with lots of detail
+- Specs approaching 3,500+ tokens
+- Need clear separation of concerns (design, plan, test)
+- Large teams with multiple reviewers
+
+## Philosophy
+
+Keep it lean, but organized. Use sub-specs to manage complexity without overwhelming context. Each file stays focused and under token limits.
+
+## Next Steps
+
+You're ready to go! Ask your AI to create a spec for your next feature.
+
+When a spec grows large, consider splitting sections into sub-spec files.
+

package/templates/detailed/config.json

@@ -0,0 +1,20 @@
+{
+  "name": "Enterprise",
+  "description": "Governance-ready with approvals, compliance, and security",
+  "config": {
+    "template": "enterprise",
+    "specsDir": "specs",
+    "structure": {
+      "pattern": "flat",
+      "prefix": "",
+      "dateFormat": "YYYYMMDD",
+      "sequenceDigits": 3,
+      "defaultFile": "README.md"
+    },
+    "features": {
+      "aiAgents": true,
+      "compliance": true,
+      "approvals": true
+    }
+  }
+}

package/templates/detailed/files/DESIGN.md

@@ -0,0 +1,43 @@
+# Design: {name}
+
+> Part of [{name}](README.md)
+
+## Architecture
+
+<!-- High-level system design, components, interactions -->
+
+## Technical Approach
+
+<!-- Specific technologies, patterns, frameworks -->
+
+## Design Decisions
+
+<!-- Key decisions and rationale -->
+
+### Decision 1
+
+**Context**: <!-- What problem does this solve? -->
+
+**Decision**: <!-- What did we choose? -->
+
+**Rationale**: <!-- Why this approach? -->
+
+**Trade-offs**: <!-- What are we giving up? -->
+
+## Dependencies
+
+<!-- What does this depend on? What depends on this? -->
+
+### System Dependencies
+- 
+
+### Team Dependencies
+- 
+
+## Security & Compliance
+
+<!-- Security implications, compliance requirements -->
+
+- [ ] Handles sensitive data (PII, credentials, etc.)
+- [ ] Security review completed
+- [ ] Compliance requirements addressed

package/templates/detailed/files/PLAN.md

@@ -0,0 +1,59 @@
+# Plan: {name}
+
+> Part of [{name}](README.md)
+
+## Implementation Phases
+
+### Phase 1: [Name]
+
+**Goal**: <!-- What does this phase achieve? -->
+
+**Tasks**:
+- [ ] Task 1
+- [ ] Task 2
+- [ ] Task 3
+
+**Dependencies**: <!-- What must be done before this? -->
+
+**Success criteria**: <!-- How do we know this is done? -->
+
+### Phase 2: [Name]
+
+**Goal**: <!-- What does this phase achieve? -->
+
+**Tasks**:
+- [ ] Task 1
+- [ ] Task 2
+- [ ] Task 3
+
+**Dependencies**: <!-- What must be done before this? -->
+
+**Success criteria**: <!-- How do we know this is done? -->
+
+## Rollout Strategy
+
+<!-- How will this be deployed to production? -->
+
+**Staging**:
+- 
+
+**Production**:
+- 
+
+**Monitoring**:
+- 
+
+**Rollback plan**:
+- 
+
+## Timeline
+
+| Phase | Duration | Dependencies |
+|-------|----------|--------------|
+|       |          |              |
+
+## Risks
+
+| Risk | Impact | Mitigation |
+|------|--------|------------|
+|      |        |            |

package/templates/detailed/files/README.md

@@ -0,0 +1,30 @@
+---
+status: planned
+created: '{date}'
+tags: []
+priority: medium
+---
+
+# {name}
+
+> **Status**: {status} · **Priority**: {priority} · **Created**: {date}
+
+## Overview
+
+<!-- What are we solving? Why now? Expected impact? -->
+
+## Sub-Specs
+
+For detailed information, see:
+
+- **[DESIGN.md](DESIGN.md)** - Technical architecture and design decisions
+- **[PLAN.md](PLAN.md)** - Implementation plan and phases
+- **[TEST.md](TEST.md)** - Testing strategy and verification
+
+## Quick Summary
+
+<!-- Brief summary of the spec (2-3 paragraphs max) -->
+
+## Notes
+
+<!-- Key decisions, constraints, open questions -->

package/templates/detailed/files/TEST.md

@@ -0,0 +1,71 @@
+# Test: {name}
+
+> Part of [{name}](README.md)
+
+## Testing Strategy
+
+<!-- Overall approach to verifying this works -->
+
+## Unit Tests
+
+<!-- Component-level testing -->
+
+**Scope**:
+- 
+
+**Key test cases**:
+- [ ] Test case 1
+- [ ] Test case 2
+- [ ] Test case 3
+
+## Integration Tests
+
+<!-- System interaction testing -->
+
+**Scope**:
+- 
+
+**Key test cases**:
+- [ ] Test case 1
+- [ ] Test case 2
+- [ ] Test case 3
+
+## Performance Tests
+
+<!-- Load, stress, and performance testing -->
+
+**Requirements**:
+- 
+
+**Test scenarios**:
+- [ ] Scenario 1
+- [ ] Scenario 2
+
+## Security Tests
+
+<!-- Security validation -->
+
+**Security checks**:
+- [ ] Authentication/authorization
+- [ ] Input validation
+- [ ] Data encryption
+- [ ] Audit logging
+
+## Acceptance Criteria
+
+<!-- What must be true for this to be considered complete? -->
+
+- [ ] Criterion 1
+- [ ] Criterion 2
+- [ ] Criterion 3
+
+## Test Data
+
+<!-- What test data is needed? -->
+
+## Manual Testing
+
+<!-- What requires human verification? -->
+
+- [ ] Manual test 1
+- [ ] Manual test 2

package/templates/examples/api-refactor/README.md

@@ -0,0 +1,86 @@
+# API Refactor Demo
+
+> **Tutorial**: [Refactoring with Specs](https://harnspec.github.io/docs/tutorials/refactoring-specs)
+
+## Scenario
+
+You're maintaining a Node.js application that started simple but has grown messy. The app integrates with multiple external services (weather API, currency converter, timezone lookup), but all the HTTP logic is tangled together in the main application code.
+
+You want to extract a reusable API client module that:
+
+- Centralizes HTTP request handling
+- Provides a clean interface for service calls
+- Handles errors consistently
+- Makes the code easier to test and maintain
+
+## What's Here
+
+A monolithic Node.js app with:
+
+- Weather lookup feature (calls external API)
+- Currency conversion (calls external API)
+- Timezone lookup (calls external API)
+- All HTTP logic mixed into business logic (tight coupling)
+- No error handling abstraction
+- Hard to test individual parts
+
+**Files:**
+
+- `src/app.js` - Main application with all features
+- `src/services/weatherService.js` - Weather API calls (tightly coupled)
+- `src/services/currencyService.js` - Currency API calls (tightly coupled)
+- `src/services/timezoneService.js` - Timezone API calls (tightly coupled)
+
+## Getting Started
+
+```bash
+# Install dependencies
+npm install
+
+# Run the app
+npm start
+
+# Try the features:
+# - Weather: Get weather for a city
+# - Currency: Convert between currencies
+# - Timezone: Look up timezone info
+```
+
+## Your Mission
+
+Refactor the HTTP logic into a clean, reusable API client. Follow the tutorial and ask your AI assistant:
+
+> "Help me refactor this app using HarnSpec. I want to extract a reusable API client module that centralizes all the HTTP logic."
+
+The AI will guide you through:
+
+1. Creating a refactoring spec
+2. Designing the API client interface
+3. Extracting the HTTP logic step by step
+4. Updating services to use the new client
+5. Verifying everything still works
+
+## Current Problems
+
+- **Duplicated code**: Each service reimplements HTTP requests
+- **No error handling**: Errors handled inconsistently
+- **Hard to test**: Can't mock HTTP calls easily
+- **Tight coupling**: Business logic mixed with HTTP details
+- **No retry logic**: Network failures aren't handled
+
+These are perfect opportunities to practice refactoring with specs!
+
+## Expected Result
+
+After refactoring, you should have:
+
+```
+src/
+  app.js (unchanged interface)
+  client/
+    apiClient.js (new - centralized HTTP logic)
+  services/
+    weatherService.js (simplified - uses apiClient)
+    currencyService.js (simplified - uses apiClient)
+    timezoneService.js (simplified - uses apiClient)
+```

package/templates/examples/api-refactor/package.json

@@ -0,0 +1,16 @@
+{
+  "name": "api-refactor-demo",
+  "version": "1.0.0",
+  "description": "Monolithic Node.js app for HarnSpec Tutorial 3",
+  "type": "module",
+  "scripts": {
+    "start": "node src/app.js",
+    "dev": "node --watch src/app.js"
+  },
+  "keywords": ["harnspec", "tutorial", "demo"],
+  "author": "",
+  "license": "MIT",
+  "dependencies": {
+    "node-fetch": "^3.3.2"
+  }
+}

package/templates/examples/api-refactor/src/app.js

@@ -0,0 +1,40 @@
+import { getWeather } from './services/weatherService.js';
+import { convertCurrency } from './services/currencyService.js';
+import { getTimezone } from './services/timezoneService.js';
+
+console.log('=== Multi-Service App Demo ===\n');
+
+// Demo 1: Weather lookup
+console.log('1. Weather Lookup:');
+try {
+  const weather = await getWeather('London');
+  console.log(`   ${weather.city}: ${weather.temp}°C, ${weather.condition}`);
+} catch (error) {
+  console.log(`   Error: ${error.message}`);
+}
+
+console.log('');
+
+// Demo 2: Currency conversion
+console.log('2. Currency Conversion:');
+try {
+  const result = await convertCurrency(100, 'USD', 'EUR');
+  console.log(`   ${result.amount} ${result.from} = ${result.converted} ${result.to}`);
+} catch (error) {
+  console.log(`   Error: ${error.message}`);
+}
+
+console.log('');
+
+// Demo 3: Timezone lookup
+console.log('3. Timezone Lookup:');
+try {
+  const timezone = await getTimezone('America/New_York');
+  console.log(`   ${timezone.name}: ${timezone.offset} (${timezone.abbreviation})`);
+} catch (error) {
+  console.log(`   Error: ${error.message}`);
+}
+
+console.log('');
+console.log('Notice: All services work, but they all duplicate HTTP logic!');
+console.log('Your task: Extract a reusable API client module.');

package/templates/examples/api-refactor/src/services/currencyService.js

@@ -0,0 +1,43 @@
+import fetch from 'node-fetch';
+
+/**
+ * Convert currency
+ * 
+ * PROBLEM: Duplicates HTTP logic from weatherService
+ * - Same fetch boilerplate
+ * - Same error handling pattern
+ * - Same JSON parsing
+ * - Should be using a shared HTTP client!
+ */
+export async function convertCurrency(amount, from, to) {
+  // Mock API endpoint (replace with real API in production)
+  const url = `https://api.exchangerate.host/convert?from=${from}&to=${to}&amount=${amount}`;
+  
+  try {
+    const response = await fetch(url);
+    
+    if (!response.ok) {
+      throw new Error(`Currency API error: ${response.status}`);
+    }
+    
+    const data = await response.json();
+    
+    // Business logic: Transform API response to our format
+    return {
+      amount,
+      from,
+      to,
+      converted: data.result || (amount * 0.85).toFixed(2),
+      rate: data.info?.rate || 0.85,
+    };
+  } catch (error) {
+    // For demo, return mock data on error
+    return {
+      amount,
+      from,
+      to,
+      converted: (amount * 0.85).toFixed(2),
+      rate: 0.85,
+    };
+  }
+}

package/templates/examples/api-refactor/src/services/timezoneService.js

@@ -0,0 +1,41 @@
+import fetch from 'node-fetch';
+
+/**
+ * Get timezone information
+ * 
+ * PROBLEM: Yet another copy of the same HTTP logic!
+ * - Third time we're writing fetch + error handling + JSON parsing
+ * - Violates DRY principle
+ * - Makes testing hard (need to mock fetch in 3 places)
+ * - Changes to HTTP logic need updates in 3 files
+ */
+export async function getTimezone(zone) {
+  // Mock API endpoint (replace with real API in production)
+  const url = `http://worldtimeapi.org/api/timezone/${zone}`;
+  
+  try {
+    const response = await fetch(url);
+    
+    if (!response.ok) {
+      throw new Error(`Timezone API error: ${response.status}`);
+    }
+    
+    const data = await response.json();
+    
+    // Business logic: Transform API response to our format
+    return {
+      name: data.timezone || zone,
+      offset: data.utc_offset || '-05:00',
+      abbreviation: data.abbreviation || 'EST',
+      datetime: data.datetime || new Date().toISOString(),
+    };
+  } catch (error) {
+    // For demo, return mock data on error
+    return {
+      name: zone,
+      offset: '-05:00',
+      abbreviation: 'EST',
+      datetime: new Date().toISOString(),
+    };
+  }
+}

package/templates/examples/api-refactor/src/services/weatherService.js

@@ -0,0 +1,42 @@
+import fetch from 'node-fetch';
+
+/**
+ * Get weather for a city
+ * 
+ * PROBLEM: This function has HTTP logic mixed with business logic
+ * - Manual fetch calls
+ * - Manual error handling
+ * - Manual JSON parsing
+ * - No retry logic
+ * - Hard to test (can't mock HTTP)
+ */
+export async function getWeather(city) {
+  // Mock API endpoint (replace with real API in production)
+  const url = `https://api.weatherapi.com/v1/current.json?key=mock&q=${city}`;
+  
+  try {
+    const response = await fetch(url);
+    
+    if (!response.ok) {
+      throw new Error(`Weather API error: ${response.status}`);
+    }
+    
+    const data = await response.json();
+    
+    // Business logic: Transform API response to our format
+    return {
+      city: data.location?.name || city,
+      temp: data.current?.temp_c || Math.floor(Math.random() * 30),
+      condition: data.current?.condition?.text || 'Sunny',
+      humidity: data.current?.humidity || Math.floor(Math.random() * 100),
+    };
+  } catch (error) {
+    // For demo, return mock data on error
+    return {
+      city,
+      temp: Math.floor(Math.random() * 30),
+      condition: 'Sunny (mock data)',
+      humidity: Math.floor(Math.random() * 100),
+    };
+  }
+}