npm package: @mod-computer/mod
Description: Spec-driven development with traceability. Connect your specs, code, and tests so reviews show the full picture.
Latest version: 0.2.7

# mod

Spec-driven development with traceability. Connect your specs, code, and tests so reviews show the full picture.

## Quick Start

```bash
# Install
npm install -g @mod-computer/mod

# Initialize workspace (creates .mod/traces/, glassware.toml, installs mod skill)
mod init

# Start working
git checkout -b feat/user-auth
```

No account needed. No server connection. Just install and go.

## The Idea

You write specs. Agents implement them. But at review time, how do you know what requirement each function addresses? What's tested? What changed but isn't connected to anything?

mod builds a trace graph as you work:

```
requirement → specification → implementation → test
```

At review, `mod trace report` shows what's connected. `mod trace diff` catches what isn't.

## Usage

### With Claude Code (Recommended)

`mod init` installs the mod skill automatically. Any agent that reads project context picks it up. No special prefix needed.

```bash
# Start an agent session and ask it to implement
$ claude
> implement specs/auth.md

# Review coverage
$ mod trace report specs/auth.md
$ mod trace coverage
```

### Manual Workflow

```bash
# Add traces as you work
mod trace add specs/auth.md:15 --type=requirement
mod trace add src/auth/login.ts:42 --type=implementation --link=req-login--a1b2

# Link existing traces
mod trace link impl-login--a1b2 spec-login--c3d4

# View connections
mod trace report specs/auth.md
mod trace coverage

# Find gaps before merge
mod trace diff          # Untraced files on branch
mod trace unmet         # Requirements without implementations
```

## Commands

### Setup

```bash
mod init                # Initialize workspace, install mod skill
```

### Add Traces

```bash
# Single trace
mod trace add <file>:<line> --type=<type> ["description"]
mod trace add <file>:<line> --type=<type> --link=<trace-id>

# Bulk add (agent-friendly)
mod trace add-bulk --json '[
  {"file": "specs/auth.md", "line": 15, "type": "requirement"},
  {"file": "specs/auth.md", "line": 22, "type": "requirement"}
]'
```

### Link Traces

```bash
# Single link
mod trace link <source-id> <target-id>

# Bulk link
mod trace link-bulk --json '[
  {"source": "impl-login--d0e6f3a4", "target": "req-login--a7f3d2c1"}
]'
```

### Unlink and Delete

```bash
mod trace unlink <source-id> <target-id>
mod trace delete <trace-id> --force
```

### Bulk Update

```bash
mod trace update-bulk --json '[
  {"id": "req-login--a7f3d2c1", "nodeType": "specification"}
]'
```

### View Traces

```bash
mod trace list                    # All traces
mod trace list --type=requirement # Filter by type
mod trace list --file=<path>      # Filter by file
mod trace get <trace-id>          # Get trace details
```

### Reports

```bash
mod trace report <file>           # Per-document coverage
mod trace coverage                # Workspace-wide stats
```

### Find Gaps

```bash
mod trace diff                    # Untraced files on branch
mod trace diff main..HEAD         # Explicit git range
mod trace unmet                   # Requirements without implementations
```

## Schema

Define your trace graph in `glassware.toml`. The default schema:

```toml
node_types = ["requirement", "specification", "implementation", "test"]

[edge_types.specifies]
from = "specification"
to = "requirement"
attribute = "requirements"
label = "Specified"

[edge_types.implements]
from = "implementation"
to = "specification"
attribute = "specifications"
label = "Implemented"

[edge_types.tests]
from = "test"
to = "implementation"
attribute = "implementations"
label = "Tested"
```

Add custom node types and edges to match your workflow (releases, RFCs, ADRs, etc.).

## CI Integration

Commands exit non-zero when issues exist:

```bash
# Pre-merge validation
mod trace diff && mod trace unmet && git push
```

| Command | Exit 0 | Exit 1 |
|---------|--------|--------|
| `mod trace diff` | All changed files traced | Untraced files exist |
| `mod trace unmet` | All requirements implemented | Unmet requirements |

## Development

```bash
pnpm install    # Install dependencies
pnpm build      # Build CLI
pnpm dev        # Watch mode
pnpm test       # Run tests
```