This guide walks you through setting up and using the complete specification-driven development workflow with Claude Code commands and the mod-cli tool.

Prerequisites

- Claude Code or Cursor IDE
- Node.js 16+
- PNPM or NPM

Step 1: Install

Download and install the pre-built CLI package:

# Download the CLI package to current directory
curl -O https://docs.mod.computer/mod-cli-0.1.0.tgz

# Install globally from the downloaded file
npm install -g ./mod-cli-0.1.0.tgz

# Clean up the download file (optional)
rm mod-cli-0.1.0.tgz

# Verify installation
mod

Alternative download: Download mod-cli-0.1.0.tgz directly then run:

npm install -g ./mod-cli-0.1.0.tgz

Step 2: Init

The mod-cli tool includes pre-built Claude commands that you can install automatically:

# Navigate to your project directory
cd your-project

# Install Claude commands automatically
mod init

# Check that commands are properly installed:
mod init --list

Expected files:

• execute.md - Implements features with full @spec traceability
• overview.md - Analyzes codebase and creates specification scaffolding
• review.md - Reviews code and adds missing traceability
• spec.md - Creates ModSpec-compliant feature specifications

Create Workspace

Initialize a new mod workspace in your project:

# Create workspace
mod workspace create my-project

# Navigate to workspace directory
cd my-project

Expected output:

✅ Workspace created: my-project
📁 Created .mod/ directory structure
🔄 Initialized workspace configuration

Step 3: Sync

Start the sync process to track file changes in real-time:

# Start background sync (runs in background)
mod sync &

Expected output:

🔄 Sync started in background
📡 Monitoring file changes...
✅ Sync service active - tracking workspace changes

Step 4: Overview

In Claude Code or Cursor:

/overview

What this does:

• Maps your codebase architecture and component relationships
• Creates .mod/specs/ directory structure (for whole repo)
• For monorepo packages: generates specs/packagename/overview.md with architecture design
• For single repos: generates root overview.md with architectural component map
• Creates specification templates for major architectural components
• Works at both repo-wide and package-specific levels

Use when: Starting work on a new project, designing high-level architecture understanding, or mapping a specific package architecture in a monorepo.

Step 5: Spec

Option A: Automatic

In Claude Code or Cursor:

/spec user authentication with JWT tokens and password validation

What this does:

• Creates new branch automatically for the specification
• Creates .mod/specs/auth/user-authentication.spec.md
• Includes UX, APP, INT, INFRA, and QUAL requirements
• Provides hierarchical requirement structure
• Specifies exact implementation details
• Starts background sync to monitor changes

Option B: Manually

# Create and switch to feature branch
mod branch create user-authentication

# Verify branch creation
mod branch list

Expected output:

✅ Created branch: user-authentication
🔄 Switched to branch: user-authentication

Active branch: user-authentication
Available branches:
  * user-authentication (active)
  main

Then use /spec in Claude Code.

Use when: You need to design a new feature or document requirements before implementation.

Step 6: Execute

In Claude Code or Cursor:

/execute user-authentication.spec.md

What this does:

• Reads and parses the complete specification
• Implements all requirements with proper @spec traceability
• Applies complexity-based granularity (method-level vs line-level)
• Embeds @spec comments during code generation
• Runs mod branch status to check branch state
• Runs mod branch coverage to verify traceability
• Runs mod status user-authentication.spec.md to check requirement progress
• Provides implementation progress feedback

Use when: You have a specification ready and want to implement the feature with full traceability.

Step 7: Review

In Claude Code or Cursor:

/review user-authentication.spec.md

What this does:

• Runs initial mod branch status to check branch state
• Runs mod branch coverage to analyze traceability
• Runs mod status user-authentication.spec.md to check current requirement status
• Scans codebase for missing @spec traces
• Adds appropriate traceability comments
• Updates specification if implementation diverged sensibly
• Re-runs mod branch coverage and mod status to verify improvements

Use when: You have existing code that needs better specification traceability or want to verify implementation completeness.

Status & Coverage

In your terminal:

# Check overall spec requirement status
mod status user-authentication.spec.md

# Check overall branch status
mod branch status

# Check trace coverage on generated updates
mod branch coverage

Expected output:

.mod/specs/auth/user-authentication.spec.md - 24 requirements

## UX Requirements
✅ REQ-UX-1: Login Form Interface - traced
  ✅ REQ-UX-1.1: Email input validation - traced (2)
  ✅ REQ-UX-1.2: Password input masking - traced

## APP Requirements  
✅ REQ-APP-1: Authentication Logic - traced
  ✅ REQ-APP-1.1: JWT token generation - traced (3)
  ✅ REQ-APP-1.2: Password hashing - traced
  ❌ REQ-APP-1.3: Session management - todo

## INT Requirements
✅ REQ-INT-1: API Endpoints - traced
  ✅ REQ-INT-1.1: POST /auth/login - traced (2)
  ✅ REQ-INT-1.2: POST /auth/refresh - traced

Found 20 traced, 4 todo (47 traces total).

Iterate until complete:

1. If any requirements show "todo", run /execute or /review again
2. Run mod branch status and mod branch coverage after each iteration
3. Complete when all parent requirements show "traced"
4. Background sync continues monitoring changes throughout the process

Best Practices

Specification Quality

• Use hierarchical requirements (REQ-APP-1.1, REQ-APP-1.2)
• Include exact implementation details
• Specify traceability comment patterns
• Cross-reference related specifications

Traceability Standards

• Method-level specs for simple functions
• Line-level specs for complex business logic
• Always include spec file prefix in @spec comments
• Embed traces during code generation, not after

Workflow Integration

• Create workspace and branch before starting
• Start background sync for real-time change tracking
• Run /overview first for new projects
• Use /spec to create implementation-ready specifications (auto-creates branch)
• Use /execute for initial implementation (runs branch status/coverage)
• Use /review to improve existing code traceability (runs branch status/coverage)
• Use mod status <spec_name>.spec.md, mod branch status, and mod branch coverage to verify progress