# writ

**Better instructions. Connected agents.**

[![PyPI](https://img.shields.io/pypi/v/enwrit)](https://pypi.org/project/enwrit/)
[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](https://opensource.org/licenses/MIT)
[![Python 3.11+](https://img.shields.io/badge/python-3.11+-blue.svg)](https://www.python.org/downloads/)
[![Tests](https://github.com/enwrit/writ/actions/workflows/ci.yml/badge.svg)](https://github.com/enwrit/writ/actions)

The quality and communication layer for AI coding agents. Lint your instructions, compose context across tools, and connect agents across repos and devices.

```bash
pip install enwrit
writ lint --file CLAUDE.md        # Instant quality score (0-100) for any instruction
writ init --template fullstack    # Bootstrap agent team in your repo
writ use architect                # Compose + write to your IDE's native files
```

**[Try the live lint demo](https://enwrit.com)** -- paste any instruction, get an instant quality score. Or **[browse 50+ instructions on the Hub](https://enwrit.com/hub)**.

---

## Lint Your Instructions

97% of AI instructions have quality defects. `writ lint` catches them.

```bash
writ lint --file .cursor/rules/my-rule.mdc
# Score: 34 / 100 (D)
# - 6 instances of vague language ("try to", "consider", "if possible")
# - No verification commands (agents can't check their own work)
# - No code examples
# Suggestions:
#   Replace vague phrases with imperative commands
#   Add backtick-wrapped test/build/lint commands (2-3x quality impact)
#   Add 1-3 code examples showing desired patterns
```

Scores 0-100 across 6 dimensions: **Clarity**, **Verification**, **Coverage**, **Brevity**, **Structure**, **Examples**. Works on any `.md`, `.mdc`, `.txt`, or YAML instruction file -- no `writ init` required.

```bash
writ lint --file CLAUDE.md              # Score any file
writ lint my-agent                      # Score a managed instruction
writ lint --deep --file AGENTS.md       # AI-powered analysis (Gemini, via enwrit.com)
writ lint --json --file rules.mdc       # Machine-readable output for CI
writ lint --ci --min-score 60           # Exit 1 if score too low (CI gate)
```

**[Try it in your browser](https://enwrit.com)** -- paste any instruction, get an instant score.

---

## 30-Second Quickstart

```bash
# 1. Install
pip install enwrit

# 2. Initialize in any repo (auto-detects your stack)
writ init

# 3. Install a pre-built instruction from the Hub
writ install verification-loop
writ install code-review-agent

# 4. Activate -- writes to your IDE's native files
writ use verification-loop
writ use code-review-agent
```

That's it. Your IDE now has battle-tested instructions -- no copy-paste, no manual conversion.

## What Makes writ Different

| Capability | What it means |
|-----------|--------------|
| **Instruction linting** | 6-dimension quality scoring (0-100) for any AI instruction file. Code-based + AI-powered. |
| **Context composition** | Layer project + team + agent + handoff context into one coherent instruction set |
| **9 output formats** | Write once, export to Cursor `.mdc`, `CLAUDE.md`, `AGENTS.md`, Copilot, Windsurf, Codex, Kiro, Agent Cards |
| **Agent communication** | Structured conversations between agents across repos and devices |
| **Personal library + cloud sync** | `writ save` → `writ load` on any device. Your agents follow you. |
| **Hub with 50+ instructions** | Rules, agents, and autonomous programs. `writ install <name>` |
| **MCP server** | One line in your config and any agent can search/install from the Hub |

## How It Works

writ writes to **native IDE files** -- it does NOT call LLM APIs.

| Tool | writ writes to |
|------|----------------|
| Cursor | `.cursor/rules/writ-*.mdc` |
| Claude Code | `CLAUDE.md` |
| AGENTS.md | `AGENTS.md` |
| GitHub Copilot | `.github/copilot-instructions.md` |
| Windsurf | `.windsurfrules` |
| Codex / Kiro | `AGENTS.md` |

When you run `writ use reviewer`, the tool composes all relevant context and writes it directly into the files your IDE already reads.

## Context Composition

The core innovation. Each agent's context is composed from 4 layers:

```
Layer 4: Handoff context      ← Output from another agent
Layer 3: Agent's instructions  ← The agent's own role
Layer 2: Inherited context     ← From parent agents
Layer 1: Project context       ← Auto-detected (languages, frameworks, structure)
```

```bash
writ use implementer --with architect    # Compose with architect's context
writ compose reviewer --with architect   # Preview before writing
```

## MCP Server (One-Line Setup)

Give any MCP-compatible agent access to the Hub -- no CLI needed:

```json
{
  "mcpServers": {
    "writ": {
      "command": "uvx",
      "args": ["enwrit", "mcp", "serve"]
    }
  }
}
```

This exposes 22 tools: search the Hub, install instructions, compose context, read files, start agent conversations, and more. Run `writ mcp serve --help` for the full list.

## Hub: Browse & Install

The [enwrit Hub](https://enwrit.com/hub) has 50+ curated instructions across three tiers:

- **Rules** -- passive context that shapes agent behavior (verification loops, commit hygiene, no-secrets)
- **Agents** -- on-invocation workers (code review, git commit, documentation, security audit)
- **Programs** -- autonomous metric-driven loops (test coverage optimizer, dependency freshness, dead code eliminator)

```bash
writ search "code review"          # Search from CLI
writ install code-review-agent     # Install into your project
writ use code-review-agent         # Activate in your IDE
```

## Templates

Bootstrap an agent team in seconds:

```bash
writ init --template fullstack     # Architect + implementer + reviewer + tester
writ init --template python        # Python developer + reviewer
writ init --template typescript    # TypeScript developer + reviewer
writ init --template rules         # Project rule + coding standards
```

## Personal Library & Cloud Sync

```bash
writ save my-reviewer              # Save to library (local + cloud)
writ login                         # Authenticate for cross-device sync
writ load my-reviewer              # Load on any machine
writ library                       # See everything (local + remote)
```

## Cross-Project Memory

```bash
writ memory export research-insights     # Export from current project
writ memory import research-insights     # Import in another project
```

## Agent-to-Agent Communication

Agents can have structured conversations across repos:

```bash
writ peers add partner-repo --path ../partner-repo
writ chat start --with partner-repo --goal "Review API design"
writ chat send <conv-id> "Here's my proposed schema..."
writ inbox                          # Check for responses
```

## All Commands

| Command | Description |
|---------|-------------|
| `writ init` | Initialize in current repo |
| `writ add <name>` | Create instruction (agent, rule, context, program) |
| `writ add --file <path>` | Import markdown file(s) or directory |
| `writ list` | List all instructions |
| `writ use <name>` | Activate (compose + write to IDE files) |
| `writ edit <name>` | Open in $EDITOR |
| `writ remove <name>` | Remove instruction |
| `writ export <name> <format>` | Export to specific format |
| `writ compose <name>` | Preview composed context |
| `writ save / load` | Personal library (local + cloud) |
| `writ library` | List personal library |
| `writ search <query>` | Search Hub |
| `writ install <name>` | Install from Hub |
| `writ publish / unpublish` | Make publicly discoverable |
| `writ login / logout` | Authenticate with enwrit.com |
| `writ register` | Create account |
| `writ lint [name] [--file] [--deep] [--json] [--ci]` | Quality score (0-100, 6 dimensions) |
| `writ sync` | Bulk bidirectional library sync |
| `writ mcp serve` | Start MCP server (22 tools) |
| `writ chat start/send/inbox` | Agent-to-agent conversations |
| `writ memory export/import` | Cross-project memory |
| `writ handoff create` | Create agent handoff |
| `writ review <name>` | Browse/submit reviews |
| `writ threads` | Knowledge threads |

## Instruction Format

Instructions are YAML files in `.writ/`, 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 specializing in TypeScript.
  Focus on: type safety, component composition, performance.
composition:
  inherits_from: [architect]
  project_context: true
```

Users interact primarily with markdown. Use `writ add --file` to import `.md`, `.mdc`, or `.txt` files directly.

## Development

```bash
git clone https://github.com/enwrit/writ.git
cd writ
python -m venv venv
source venv/bin/activate  # Windows: venv\Scripts\activate
pip install -e ".[dev]"
pytest                    # 378 tests
ruff check src/ tests/
```

## License

MIT

## Links

- **Hub**: [enwrit.com/hub](https://enwrit.com/hub) -- Browse and install instructions
- **Website**: [enwrit.com](https://enwrit.com)
- **GitHub**: [github.com/enwrit/writ](https://github.com/enwrit/writ)
- **PyPI**: [pypi.org/project/enwrit](https://pypi.org/project/enwrit/)
