Slash Commands
Writ generates slash commands for Claude Code during writ init. These are markdown files in .claude/commands/ that expose writ’s full CLI as discoverable commands in the agent’s palette. Agents see them alongside other project commands and can invoke them without remembering exact CLI syntax.
How They Work
Each slash command is a .md file that tells the agent what command to run and what flags are available. They’re generated once during writ init and regenerated on writ init --reconfigure. Each file includes a <!-- Generated by writ init. Do not edit. --> header so writ can identify and manage its own files.
Slash commands are thin wrappers. They don’t contain business logic. They document the CLI command and let the agent invoke it. The CLI is the source of truth.
Full Command List
Core Workflow
| Command | What It Does |
|---|---|
/writ-context | Get structured project state. Run this FIRST at the start of every task. |
/writ-seal | Checkpoint current work with a summary and spec linkage. |
/writ-spec-add | Create a new task/spec with an ID and title. |
/writ-spec-done | Mark a spec complete. Creates a final seal. |
Status and Review
| Command | What It Does |
|---|---|
/writ-status | Fleet overview: agents, specs, progress, commit readiness. |
/writ-diff | View file changes. Supports --spec, --agent, --stat, --name-only. |
/writ-log | Seal history. --all includes diverged branches. |
/writ-show | Inspect a specific seal. --diff shows file changes. |
Spec Management
| Command | What It Does |
|---|---|
/writ-spec-status | List specs, optionally filtered by lifecycle state. |
/writ-spec-show | Detailed view of a single spec. |
/writ-spec-reopen | Reopen a completed spec for continued work. |
Round Trip
| Command | What It Does |
|---|---|
/writ-finish | Promote completed specs to git commits. Supports --strategy, --dry-run. |
/writ-summary | Generate commit messages (--format commit) or PR descriptions (--format pr). |
Recovery and Convergence
| Command | What It Does |
|---|---|
/writ-restore | Restore working directory to any seal’s state. |
/writ-converge | Merge diverged branches. Strategies: escalate, three-way-merge, most-recent, orchestrator. |
Diagnostics
| Command | What It Does |
|---|---|
/writ-verify | Verify cryptographic integrity of the seal chain. |
/writ-doctor | Run diagnostic checks on repo health. |
Generation and Cleanup
During Init
writ init
# ✓ Generated 20 slash commands in .claude/commands/
Slash commands are only generated when Claude Code is detected (presence of CLAUDE.md or .claude/ directory). Other frameworks get the CLI and instruction templates appropriate to their environment.
Regeneration
writ init --reconfigure
This overwrites all existing writ-*.md files in .claude/commands/ with fresh copies. Non-writ files are preserved.
Cleanup
writ uninit
Removes only writ-*.md files from .claude/commands/. Any slash commands you’ve created yourself are left untouched.
Slash Commands vs MCP Tools
Both provide the same capabilities. The difference is how the agent discovers and invokes them:
| Slash Commands | MCP Tools | |
|---|---|---|
| How agent finds them | Command palette, / prefix | Tool palette, native MCP discovery |
| How agent invokes them | Runs the CLI command in a shell | Calls the MCP tool function |
| Output | CLI stdout (text or TOON) | MCP tool result (text) |
| Works without MCP | Yes, just files on disk | No, requires MCP connection |
| Works without Claude Code | No, Claude Code specific | Yes, any MCP client |
In a Claude Code environment with both enabled (the default after writ init), the agent has two paths to every writ command. The MCP path is typically preferred by agents because it’s a native tool call rather than a shell command, but both work identically.
Relationship to Instruction Templates
Slash commands are Layer 2 in writ’s adoption stack. They complement, not replace, the instruction templates (Layer 1) in CLAUDE.md:
- Instructions tell agents the workflow: run context first, seal after work, mark specs complete.
- Slash commands make the workflow easy to execute: the exact commands are discoverable in the palette.
- MCP tools (Layer 3) make it native: no shell involved, direct tool calls.
All three are generated by writ init. All three are cleaned up by writ uninit.