@mod-computer/cli 0.1.1 → 0.2.2

package/README.md

@@ -1,106 +1,142 @@
 # mod-cli
 
-## Intro
+Spec-driven development with traceability. Connect your specs, code, and tests so reviews show the full picture.
 
-mod-cli is the local sync agent for Mod, a collaboration layer for teams working with coding agents.
+## Quick Start
 
-Coding agents operate on local filesystems. They read specs, write code, and generate metadata (traces, reasoning, todos). But collaboration happens elsewhere: in GitHub PRs, Notion docs, Slack threads. The result: context lives in silos. Agents can't access specs being discussed in the browser. Teammates can't see agent reasoning. Reviews happen without the full picture.
-
-mod-cli bridges local and collaborative workflows. It syncs the local filesystem to Mod workspaces in real-time, making local changes visible to collaborators and remote edits available to agents. The CLI turns a directory into a distributed, collaborative filesystem.
-
-## Conceptual Overview
-
-**Workspaces**: A workspace is a container for files, branches, and metadata. Create workspaces with `mod workspace create`, list them with `mod workspace list`, switch with `mod workspace switch`. Each workspace has its own history, collaborators, and sync state. A directory connects to one workspace at a time.
-
-**Local-First Sync**: `mod sync start` launches a daemon that watches the local directory and syncs to the connected workspace. File edits, new files, deletions propagate automatically. Remote changes from collaborators sync back to local files. The daemon runs in the background; coding agents work locally as normal. Multiple collaborators can sync to the same workspace from different machines.
-
-**Branching**: Mod branches are lightweight isolation scopes for work-in-progress. Unlike git branches, they don't require commits or staging. Create a branch, start working, and all changes are tracked automatically. When integrated with git, Mod branches map to git branches. Without git, Mod branches provide standalone isolation.
-
-**Changelog**: Every file change on a branch is recorded automatically with timestamp, diff, and context. No manual commits required. The changelog captures what changed, when, and alongside what other activity (agent conversations, spec edits, collaborator comments). View at branch level or filter to a specific file.
-
-**Reversion**: Restore to any point in the changelog. Revert an entire branch to a previous state, or revert a single file while keeping other files at their current state. Fine-grained reversion without needing explicit commits as restore points.
+```bash
+# Install
+npm install -g @mod-computer/cli
 
-**Merge**: Combine branches by merging their changes. Mod detects conflicts at the file level and surfaces them for resolution. Metadata (comments, traces) merges automatically. After merge, the target branch contains changes from both branches with full history preserved.
+# Initialize workspace (installs /mod skill for Claude Code)
+mod init
+mod auth login
 
-**Git Integration**: In git repositories, sync respects git branch scope. Changes on a git branch sync to the corresponding Mod branch. Switching git branches switches sync context automatically. For non-git directories, Mod branches work independently. The CLI integrates with git workflows but doesn't require git.
+# Start working
+git checkout -b feat/user-auth
+```
 
-**Metadata Layer**: Workspaces and files carry metadata: comments, notes, and traces. The CLI provides commands to read and write metadata locally. Agents can query file context before making changes and write traces linking code to requirements. Teams see the same metadata in the web app. This shared context layer makes agent reasoning visible and lets teams annotate code without changing source files.
+## The Idea
 
-**File Import**: For existing projects, `mod sync import` brings current files into the workspace. In git repos, import can pull from git history. Preview first with `--preview` to see what will sync. After import, changes sync automatically.
+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?
 
-## Example
+mod-cli builds a trace graph as you work:
 
-A developer is implementing an authentication feature using Claude Code.
+```
+Spec requirement → Implementation → Tests
+```
 
-**1. Initialize**: The developer runs `mod init` in their project directory. They sign in (or are prompted to create an account), then select an existing workspace or create a new one. The directory is now connected to the workspace.
+At review, `mod trace report` shows what's connected. `mod trace diff` catches what isn't.
 
-**2. Start sync**: They run `mod sync start`. The daemon launches in the background, watching for file changes and syncing to the workspace.
+## Usage
 
-**3. Create branch**: They run `mod branch create add-auth`. A new branch is created. The spec file `specs/auth.md` was collaboratively edited in the web app and is already synced locally.
+### With Claude Code (Recommended)
 
-**4. Work with agent**: They prompt Claude Code to implement the spec. Claude reads `specs/auth.md` from the filesystem, checks existing comments with `mod comment list`, implements the requirements, and adds traces with `mod trace add src/auth.ts REQ-AUTH-1`. Every file change and metadata update syncs automatically.
+`mod init` installs the `/mod` skill automatically. Use it to implement specs:
 
-**5. Review changelog**: Running `mod changelog` shows all file changes with timestamps and diffs. The developer sees implementation progress alongside agent conversation context.
+```bash
+# Write a spec
+claude "Write a spec for user authentication in specs/auth.md"
 
-**6. Collaborate**: A teammate edits the spec in the web app, adding a section on rate limiting. The edit syncs to the local file. The developer prompts Claude again, and new changes sync back.
+# Implement from spec - agent handles traces
+claude "/mod implement specs/auth.md"
 
-**7. Ready for review**: Running `mod branch status` shows all changed files. The developer opens the web app to the review view, where teammates see file changes alongside traces and agent reasoning.
+# Add tests - agent traces them to implementations
+claude "/mod test specs/auth.md"
 
-## How It Works
+# Review coverage
+mod trace report specs/auth.md
+```
 
-**Sync Daemon**: `mod sync start` launches a background daemon that watches the directory. File system events trigger sync operations. The daemon maintains a WebSocket connection to the sync server for real-time updates.
+### Manual Workflow
 
-**Automerge Storage**: Local workspace state uses Automerge, a CRDT library for conflict-free replication. Changes merge automatically without coordination. The CLI stores Automerge documents in `~/.mod/` at the device root, shared across all connected repos.
+```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
 
-**Bidirectional Sync**: Local file changes update Automerge documents and propagate to the server. Server changes (from collaborators or the web app) update local Automerge state and write back to files. The sync is continuous and automatic.
+# Link existing traces
+mod trace link impl-login--a1b2 spec-login--c3d4
 
-**Branch State**: Each branch maintains independent file states in Automerge. Switching branches updates local files to match. Branch metadata and change history sync alongside file content.
+# View connections
+mod trace report specs/auth.md
+mod trace coverage
 
-**Changelog**: The CLI records every file change with timestamp, diff, and surrounding context. The changelog is queryable and connects code changes to concurrent activity like agent conversations and collaborator edits.
+# Find gaps before merge
+mod trace diff          # Untraced files on branch
+mod trace unmet         # Requirements without implementations
+```
 
-## Commands Reference
+## Commands
 
-### Core Commands
+### Setup
 
 ```bash
-mod init                    # Initialize workspace and install Claude commands
-mod sync start              # Start background sync daemon
-mod sync stop               # Stop sync daemon
-mod sync status             # Show sync health and connection status
-mod sync import             # Import existing files to workspace
+mod init                # Initialize workspace, install /mod skill
+mod auth login          # Authenticate
+mod auth logout         # Sign out
+mod auth status         # Show auth state
 ```
 
-### Branch Management
+### Traces
 
 ```bash
-mod branch create <name>    # Create new branch
-mod branch switch <name>    # Switch to branch
-mod branch list             # List all branches
-mod branch status           # Show current branch and changes
-mod branch changelog        # Show automatic changelog
-mod branch tree             # Display directory tree
+# Add traces
+mod trace add <file>:<line> --type=<type> ["description"]
+mod trace add <file>:<line> --type=<type> --link=<trace-id>
+
+# Link traces
+mod trace link <source-id> <target-id>
+
+# View traces
+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
+mod trace report <file>           # Per-document coverage
+mod trace coverage                # Workspace-wide stats
+
+# Find gaps
+mod trace diff                    # Untraced files on branch
+mod trace diff main..HEAD         # Explicit git range
+mod trace unmet                   # Requirements without implementations
 ```
 
-### Workspace Management
+### Comments
 
 ```bash
-mod workspace create <name> # Create new workspace
-mod workspace list          # List workspaces
-mod workspace switch <name> # Switch active workspace
-mod workspace info          # Show workspace details
+mod comment add <file>:<line> "text"
+mod comment list [file]
 ```
 
-### Metadata
+## Trace Types
+
+| Type | Use For |
+|------|---------|
+| `requirement` | Specs, user stories, acceptance criteria |
+| `specification` | Detailed technical specs |
+| `implementation` | Code that builds something |
+| `test` | Code that verifies something |
+| `design` | Design docs, architecture notes |
+| `decision` | ADRs, decision records |
+| `utility` | Helpers that don't need tracing |
+
+## CI Integration
+
+Commands exit non-zero when issues exist:
 
 ```bash
-mod comment add <file> <text>   # Add comment to file
-mod comment list [file]         # List comments (all or per file)
-mod note set <file> <text>      # Set note on file
-mod note get <file>             # Get note for file
-mod trace add <file> <req-id>   # Add trace linking file to requirement
-mod trace list [file]           # List traces (all or per file)
+# 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
@@ -109,17 +145,3 @@ pnpm build      # Build CLI
 pnpm dev        # Watch mode
 pnpm test       # Run tests
 ```
-
-## Thoughts
-
-**Daemon architecture**: The sync daemon runs as a background process rather than requiring an active terminal. This lets developers work normally while sync happens invisibly. The daemon writes logs to `~/.mod/logs/sync.log` for debugging.
-
-**CRDT trade-offs**: Automerge handles conflicts automatically, but the resulting merges aren't always what users expect for text files. Currently optimizing for metadata sync; file content sync may need smarter merge strategies.
-
-**Git integration**: In git repos, sync is branch-aware: git branch switches trigger Mod branch switches. Mod adds real-time collaboration and agent context on top of git. In non-git directories, Mod provides standalone change tracking and sync.
-
-**Device-level storage**: All state lives in `~/.mod/` at the device root rather than per-repo. Sign in once, use across all repos. Single daemon can sync multiple connected directories. No per-repo config to gitignore.
-
-**Metadata commands**: Specific commands for comments, notes, and traces rather than a generic `mod meta` interface. Agents benefit from semantic clarity. Each metadata type has different workflows: comments are threaded, notes are single per file, traces link to requirement IDs. Keeping them separate makes intent clear for both agents and humans.
-
-**Offline handling**: The daemon queues changes when offline and syncs when reconnected. Local edits always work; sync catches up when possible. Conflict resolution happens through Automerge's CRDT properties.