writ / rules

---
description: Core project identity, architecture, and conventions for the writ CLI tool (enwrit.com)
alwaysApply: true
---

# enwrit (writ) -- Agent Instruction Management CLI

**Product**: enwrit | **CLI command**: `writ` | **Domain**: enwrit.com | **GitHub**: github.com/enwrit/writ | **PyPI**: `pip install enwrit`

## What This Project Is

The communication layer for AI agents. Routes context between repos, devices, and tools. Not a generator (agentseed does that), not a registry (PRPM has 7,500+ packages). We compose, sync, route, and score context and/or agent instructions.

**Core framing**: Every feature is a routing operation -- `writ add` routes instructions to IDE files, `writ save` + `writ add --lib` routes between devices, `writ handoff` routes between agents, `writ memory` routes between repos.

Core capabilities:
1. **Context composition** -- layer project + team + agent + handoff context into one instruction set
2. **Instruction quality scoring** -- 3-tier lint (code + ML + AI), plan review, pre-commit hooks
3. **Knowledge health** -- schema-driven documentation health-checking (`writ docs init/check/update`). Uses the "commands as injected instructions" pattern: writ prints instructions for the IDE's own LLM to execute, zero API cost. Validated by Karpathy's LLM Wiki (5K+ stars) as one of three core operations for knowledge management.
4. **Personal AI instructions with cloud sync** -- save instructions to enwrit.com, access from any device
5. **Cross-project memory** -- export context from Repo A, import into Repo B
6. **Agent-to-agent communication** -- structured conversations between agents in different repos (local filesystem or backend relay), with MCP Polling, CLI agent invocation, and API fallback

**Architectural pattern -- "commands as injected instructions"**: Some writ commands (`writ docs init`, `writ docs update`) don't call APIs. They return plain text instructions that the IDE's built-in LLM executes. No cost to writ. Works with any model. The instructions are stored as versioned `.md` files in `templates/_builtin/prompts/`.

**Future direction**: full A2A protocol endpoints, mobile approval workflows.

## Architecture

```
src/writ/
├── cli.py              # Typer CLI entry point
├── commands/           # One file per command group (init, agent, library, search, chat, etc.)
├── core/               # Core logic (scanner, store, composer, formatter, linter, ml_scorer, models)
├── models/tier2/       # Bundled ML models for Tier 2 lint (m2cgen scorers + kNN index)
├── integrations/       # External registry integrations (PRPM, Agent Skills CLI, URL)
└── utils.py            # Helpers
```

- **CLI**: Python 3.11+, Typer + Rich for beautiful terminal output
- **Data models**: Pydantic for all config validation
- **Config format**: YAML (structured data) + Markdown (prose instructions)
- **Local store**: `.writ/` directory per project, `~/.writ/` global cache (synced to remote)
- **No local database**: Everything is files. Git-friendly. Agent-readable.

## How It Works

The tool writes to native IDE/CLI files. LLM APIs are only called for `writ lint --cloud` (enwrit.com Gemini), `writ lint --local` / `writ plan review --local` (user's configured model), and `writ lint --local-model` (bundled Qwen). `writ lint --prompt`, `writ plan review` (default), and `writ docs update` use the "commands as injected instructions" pattern -- they print instructions for the IDE's own LLM to execute, no API cost. `writ lint --prompt` is type-aware: it infers the file type (skill/agent/rule/plan/context/other) from its path and injects a type-specific review hook via modular prompts in `prompts/hooks/`. Default `writ lint` uses the bundled Tier 2 quality model and an experimental safety model when available, falling back to code heuristics (Tier 1).

11 tools auto-detected via `IDE_PATHS` in `formatter.py`. Instructions routed to `rules/`, `skills/writ-*/`, or `agents/` based on `task_type`:

| Tool | Detect | Example path | Mode |
|------|--------|-------------|------|
| Cursor | `.cursor/` | `.cursor/{rules,skills/writ-*,agents}/writ-*.mdc` | Auto-detected |
| Claude Code | `.claude/` | `.claude/{rules,skills/writ-*,agents}/writ-*.md` | Auto-detected |
| GitHub Copilot | `.github/` | `.github/{instructions,skills/writ-*,agents}/writ-*` | Auto-detected |
| Kiro | `.kiro/` | `.kiro/{steering,skills/writ-*,agents}/writ-*.md` | Auto-detected |
| Windsurf | `.windsurf/` | `.windsurf/{rules,skills/writ-*,agents}/writ-*.md` | Auto-detected |
| Codex | `.codex/` | `.codex/{rules,skills/writ-*,agents}/writ-*.md` | Auto-detected |
| Gemini CLI | `.gemini/` | `.gemini/{rules,skills/writ-*,agents}/writ-*.md` | Auto-detected |
| OpenCode | `.opencode/` | `.opencode/{rules,skills/writ-*,agents}/writ-*.md` | Auto-detected |
| Cline | `.clinerules/` | `.clinerules/writ-*.md`, `.cline/agents/` | Auto-detected |
| Roo Code | `.roo/` | `.roo/{rules,skills/writ-*,agents}/writ-*.md` | Auto-detected |
| Amazon Q | `.amazonq/` | `.amazonq/{rules,agents}/writ-*.md` | Auto-detected |

Legacy shared-file formats (opt-in via `--format`): `claude`, `agents_md`, `copilot_legacy`, `windsurf_legacy`, `codex_legacy`, `kiro`.

## Core Commands

```
writ init                       Scan repo, create .writ/, auto-install writ-context to detected IDEs
writ init --template fullstack  Bootstrap from a built-in template
writ add <name>                 Add instruction: checks project -> library -> Hub -> creates new; auto-writes to IDE dirs
writ add <name> --lib           Force fetch from personal library instead of project
writ add <name> --from prpm    Install directly from PRPM registry
writ add <name> --format cursor Export to a specific format
writ add --file <path>          Import markdown file(s) or directory into .writ/
writ add --template rules       Load rule templates into existing project
writ list                       Show user instructions (built-in hidden by default)
writ list --all                 Show all instructions including built-in
writ list --user                Show only user instructions
writ list --library             Show personal library contents (local + remote)
writ remove <name>              Remove instruction from project
writ save <name>                Save to personal library (~/.writ/); syncs to cloud if logged in
writ save <name> --local        Save locally only (skip cloud sync)
writ search <query>             Semantic search across 6,000+ instructions (Hub API)
writ register                   Interactive account creation + auto-login
writ login                      Authenticate with enwrit.com (cross-device sync)
writ logout                     Remove stored API key
writ lint <name|file>           Validate quality + experimental safety signal (auto-detects file vs store name)
writ lint --all                 Lint all project instruction files and persist scores
writ lint --prompt              Qualitative review via prompt injection for IDE's AI
writ lint --prompt --fix        Review + instruct AI to apply fixes directly
writ lint --prompt --with-file  Inline file content in the prompt output
writ lint --prompt --subagent   Launch a subagent for the review
writ lint --prompt --security   Deep OWASP-based security review via IDE's AI
writ lint --sarif               SARIF 2.1.0 JSON output (GitHub Security tab integration)
writ lint --cloud               AI scoring via enwrit.com API only (requires login)
writ lint --local               AI scoring via your configured local model (writ model set local)
writ lint --local-model         Bundled writ-lint-0.8B model (auto-downloaded, no setup needed)
writ lint --code                Force Tier 1 code-only scoring (deterministic)
writ lint --score               Output headline score only (machine-readable)
writ lint --quiet               Output score + dimension table only (no issues/suggestions)
writ connect                    Interactive peer setup wizard for real repos
writ publish <name>             Make instruction publicly discoverable on enwrit.com
writ sync                       Bulk bidirectional library sync (confirmation prompt for >5 ops)
writ sync --dry-run             Preview what would sync without changing anything
writ mcp install                Install MCP server config to detected IDEs (slim mode by default)
writ mcp install --full         Install with all 24 MCP tools exposed
writ mcp uninstall              Remove MCP server config from IDEs
writ mcp serve                  Start MCP server (auto-installs deps on first run)
writ handoff create <from> <to> Create context handoff between agents
writ memory export/import       Cross-project memory sharing
writ chat start --with <repo>   Start agent-to-agent conversation with a peer repo
writ chat send <id> "msg" -f x  Send message with optional file attachments
writ chat list/read/end         Manage and observe agent conversations
writ review <name>              Browse or submit reviews for public instructions
writ threads list/start/post    Knowledge threads -- collaborative agent discussions
writ approvals create            Request human approval for an agent action
writ approvals list/approve/deny  Human-in-the-loop approval management
writ inbox                      Show conversations with unread messages
writ peers add/list/remove      Manage peer repo connections (local or remote)
writ diff <file>                Compare current lint score vs previous git commit
writ upgrade [name]             Check for and apply instruction updates from Hub/PRPM
writ plan review <file>         Plan review via prompt injection (default, no API call)
writ plan review <file> --local Send to your configured local model (writ model set local)
writ plan review <file> --cloud Send to enwrit.com API only (requires login)
writ plan review --with-plan    Include plan content inline in the prompt
writ plan review --subagent     Launch a subagent for the review
writ docs init                  Create documentation index for knowledge health tracking
writ docs check [--user|--all]  Heuristic documentation health scan (static built-in hidden by default)
writ docs update [--user|--all] Documentation update pass (check + injected instruction for LLM)
writ query ["search term"]      Search documentation index (agent navigation of project knowledge)
writ status                     Recent activity log + documentation health score
writ hook install/uninstall     Git pre-commit hook for instruction quality checks
writ model set/list/clear       Configure LLM provider for plan review (openai, anthropic, gemini, local)
```

## Development Conventions

1. **Typed Python**: Type hints on all functions. Pydantic for data models.
2. **One command per file**: `commands/init.py`, `commands/agent.py`, etc.
3. **No UI**: CLI and markdown output only. Agents consume this tool.
4. **Tests**: pytest for all commands and core logic. Test each command independently.
5. **Error handling**: Graceful failures with helpful messages. Never crash silently.
6. **Keep it simple**: This is a CLI tool. Don't over-engineer. Ship fast, iterate.
7. **Dogfood**: This repo uses AGENTS.md and .cursor/rules/ -- managed by our own tool.

## Key Data Model

Instructions are YAML files in `.writ/{agents,rules,context}/`, routed by `task_type`:
```yaml
name: reviewer
description: "Code reviewer for TypeScript"
version: 1.0.0
task_type: agent                # agent | rule | context | program | template
tags: [typescript, review]
instructions: |
  You are a code reviewer...
composition:
  inherits_from: []             # Agents whose instructions prepend
  receives_handoff_from: []     # Agents that hand off context
  project_context: true         # Include auto-detected project context
```

The core Pydantic model is `InstructionConfig` (covers agents, rules, context, templates).
YAML is the internal storage format; users interact primarily with markdown (`writ add --file`).

## Development Commands

```bash
# Activate venv (required before running writ/pytest/ruff)
venv\Scripts\activate              # PowerShell (Windows)
source venv/bin/activate           # Bash/macOS/Linux

# Install in editable mode (after fresh clone)
pip install -e ".[dev]"

# Run tests
python -m pytest tests/ -v

# Lint
ruff check src/ tests/
ruff check --fix src/ tests/      # auto-fix what's possible
```

## Learnings:

- **Shell note**: This project is developed on Windows/PowerShell. Use `;` to chain commands (not `&&`). Watch for cp1252 encoding -- avoid Unicode box-drawing characters in Rich output (use ASCII alternatives).
- All significant changes should be verified with tests before merging.