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

$3

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
`

$3

`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

$3

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

$3

`bash


Single trace

mod trace add : --type= ["description"]
mod trace add : --type= --link=

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"}
]'
`

$3

`bash


Single link

mod trace link

Bulk link

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

$3

`bash
mod trace unlink
mod trace delete --force
`

$3

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

$3

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

$3

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

$3

`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
``