writ / rules

---
description: Annotated treeview of the writ CLI project structure for agent orientation (enwrit.com)
alwaysApply: true
---

# Repository Structure

```
writ/                                   # github.com/enwrit/writ, writ-CLI (workspace name)
├── src/
│   └── writ/                           # Python package
│       ├── __init__.py                 # Package init, version
│       ├── __main__.py                 # Entry point for python -m writ (venv/MCP support)
│       ├── cli.py                      # Typer app, top-level command registration
│       ├── commands/                   # One file per command group
│       │   ├── __init__.py
│       │   ├── init.py                 # writ init -- scan repo, create .writ/, import existing files, auto-install writ-context to detected IDEs
│       │   ├── agent.py                # writ add/list/remove -- unified instruction management (add from Hub/library/--from prpm/create, auto-writes to IDE dirs, --format, --lib)
│       │   ├── library.py              # writ save [--local] -- personal library (local + optional cloud sync via enwrit.com)
│       │   ├── login.py                # writ login/logout -- authenticate with enwrit.com for cross-device sync
│       │   ├── register.py             # writ register -- interactive account creation + auto-login
│       │   ├── export.py               # INTERNAL: format export logic (CLI command removed, replaced by --format on writ add)
│       │   ├── compose.py              # INTERNAL: composition preview (CLI command removed)
│       │   ├── search.py               # writ search -- Hub API semantic search (6,000+ instructions), --min-score, --type filters
│       │   ├── install.py              # Hidden alias for writ add (backward compat)
│       │   ├── handoff.py              # writ handoff -- create/apply context handoffs between agents
│       │   ├── memory.py               # writ memory export/import/list -- cross-project memory sharing
│       │   ├── publish.py              # writ publish/unpublish [--yes] -- make instructions publicly discoverable on enwrit.com
│       │   ├── lint.py                 # writ lint [file|name] [--all] [--prompt] [--prompt --fix] [--prompt --security] [--cloud] [--local] [--local-model] [--code] [--sarif] [--json] [--ci] [--subagent] [--with-file] -- quality+safety scoring, full-project scan, persisted score cache
│       │   ├── connect.py              # writ connect -- interactive peer setup wizard for real repos
│       │   ├── sync.py                 # writ sync [--push|--pull|--prefer-local|--dry-run] -- bulk bidirectional library sync with confirmation prompt
│       │   ├── mcp.py                  # writ mcp install/uninstall/serve [--slim|--full] -- MCP server management (slim=2 tools, full=24 tools)
│       │   ├── chat.py                 # writ chat start/list/read/send/end/resume/gc -- agent-to-agent conversations (--file attach)
│       │   ├── peers_cmd.py            # writ peers add/list/remove -- manage peer repo connections
│       │   ├── knowledge.py            # writ review + writ threads list/read/start/post/resolve -- knowledge threads
│       │   ├── approvals.py            # writ approvals create/list/approve/deny -- human-in-the-loop approval management
│       │   ├── diff.py                 # writ diff <file> [--ref] -- lint score comparison vs git history
│       │   ├── upgrade.py              # writ upgrade [name] [--dry-run] -- version-aware instruction updates from Hub/PRPM
│       │   ├── plan.py                 # writ plan review <file> [--local] [--cloud] [--json] [--subagent] -- plan review (default: prompt injection, --local user model, --cloud enwrit.com API)
│       │   ├── docs.py                 # writ docs init/check/update [--json] [--user] [--all] -- knowledge health diagnostics (schema-driven, built-in static hidden by default)
│       │   ├── query.py               # writ query ["search"] -- search docs index (basic string filtering, agent navigation)
│       │   ├── status.py              # writ status -- recent log entries + documentation health summary
│       │   ├── hook.py                 # writ hook install/uninstall -- git pre-commit hook for instruction quality checks
│       │   └── model.py                # writ model set/list/clear -- configure LLM provider (openai, anthropic, gemini, local) for plan review
│       ├── core/                       # Core business logic
│       │   ├── __init__.py
│       │   ├── scanner.py              # Detect languages, frameworks; parse_markdown_file() for --file import
│       │   ├── store.py                # Read/write .writ/{agents,rules,context}/ and ~/.writ/ global store
│       │   ├── composer.py             # 4-layer context composition engine (the core innovation)
│       │   ├── formatter.py            # IDE_PATHS central config: 11 auto-detected safe formats (Cursor, Claude, Copilot, Kiro, Windsurf, Cline, Roo, AmazonQ, Gemini, Codex, OpenCode); content-category routing (rules/skills/agents by task_type); legacy shared-file formats opt-in via --format
│       │   ├── linter.py               # v2 earn-up scoring engine (Tier 1): 6-dimension 0-100, specificity density, verification gradient, critical caps, text quality signals (redundancy, density, duplicates, prose ratio)
│       │   ├── ml_scorer.py            # Tier 2 ML quality+safety scoring: m2cgen + TF-IDF inference, safety deductions, template suggestions, label-aware issue gating
│       │   ├── label_scorer.py         # TF-IDF+LGBM label classifier: positional TF-IDF + 26 structural features, 7 boolean labels (4-10ms inference)
│       │   ├── setfit_scorer.py        # DEPRECATED: SetFit ONNX inference (superseded by label_scorer.py)
│       │   ├── models.py               # Pydantic models: InstructionConfig, CompositionConfig, ProjectConfig (with DocsConfig), LintScore (tier: code|ml|ai), Conversation, Message, PeerConfig
│       │   ├── auth.py                 # Auth token management + persistent user identity (read/write API key to ~/.writ/config.yaml)
│       │   ├── messaging.py            # Conversation lifecycle, markdown read/write, file attachment embedding, _latest.md
│       │   ├── peers.py                # Peer repository management -- read/write peers.yaml
│       │   ├── invoker.py              # CLI agent detection (claude/gemini/codex/cursor) + invocation with AutoRespondTier, LLM API fallback
│       │   ├── local_llm.py            # Tier 2.5: auto-downloads llama.cpp binary (Vulkan GPU / CPU) + GGUF model, persistent server, hybrid inference (LightGBM scores + Qwen feedback) for --local-model
│       │   ├── context_window.py       # Sliding window + token estimation for API invocations
│       │   ├── file_io.py              # Cross-platform file locking + atomic append for conversation files
│       │   ├── llm_client.py           # Multi-provider LLM client (OpenAI, Anthropic, Gemini, local/LM Studio) for plan review
│       │   ├── doc_health.py           # Documentation health analysis: dead refs, treeview drift, staleness, contradictions, reverse drift (missing-from-index)
│       │   ├── type_inference.py       # Infer instruction type (agent/skill/rule/plan/context/other) from path, name, or store metadata -- used by lint --prompt for type-aware hooks
│       │   └── rubrics/                # Versioned rubric files for AI-powered features
│       │       └── plan-review-v1.md   # Plan review rubric (system prompt for LLM analysis)
│       ├── integrations/               # External registry integrations
│       │   ├── __init__.py
│       │   ├── prpm.py                 # HTTP-first PRPM integration (httpx -> prpm.dev API, CLI fallback) -> 7500+ packages
│       │   ├── skills.py               # HTTP-first Agent Skills integration (httpx -> agent-skills API, CLI fallback) -> 175k+ agent skills
│       │   ├── url.py                  # Install from any URL (fetches YAML via httpx) (or git repo fetch planned?)
│       │   ├── registry.py             # enwrit platform API client (httpx): push/pull library, hub_search (semantic), hub_download, relay, knowledge, approvals
│       │   └── mcp_server.py           # MCP server (FastMCP): V1 discovery, V2 compose/search/add, V3 conversations+peers, V4 knowledge, V5 approvals, V7 docs (24 full / 2 slim)
│       ├── utils.py                    # Path helpers, slugify, YAML I/O, markdown formatting, instruction classification (is_builtin, is_writ_managed, is_writ_dynamic, is_writ_static)
│       ├── models/                     # Bundled ML models for Tier 2 lint scoring
│       │   └── tier2/                  # m2cgen pure-Python scorers + kNN suggestion index
│       │       ├── __init__.py         # Quality and safety model availability checks
│       │       ├── scorer_headline.py  # Auto-generated: headline score prediction (m2cgen)
│       │       ├── scorer_*.py         # Auto-generated: 6 dimension score predictions
│       │       ├── scorer_safety_lt{30,60,80}.py # Generated ordinal safety probability heads
│       │       ├── safety_artifact_manifest.json # Safety model/config artifact identity + provenance
│       │       ├── safety_feature_config.json # Ordinal safety feature order, thresholds, artifact identity
│       │       ├── safety_tfidf_config.json # Safety vocabulary, IDF, chi2 mask, and parity metadata
│       │       ├── suggestion_index.pkl # LEGACY: SHAP-weighted kNN index (superseded by template suggestions)
│       │       ├── suggestion_templates.json # LEGACY: v1 auto-mined templates
│       │       ├── suggestion_templates_v2.json # Label-driven suggestion templates (14 templates, data-mined from 6.5k instructions)
│       │       ├── tfidf_config.json   # TF-IDF vocabulary + IDF weights + chi2 feature mask for score models (~2.4 MB)
│       │       ├── shap_weights.json   # Feature importance weights for kNN distance
│       │       ├── feature_config.json # Feature names (structural + interaction + TF-IDF) + normalization bounds
│       │       ├── vocab.txt           # WordPiece vocabulary for pure-Python SetFit tokenizer (~226KB)
│       │       └── labels/             # Label classifier models (positional TF-IDF + LGBM, ~7.67 MB total)
│       │           ├── __init__.py     # LABEL_NAMES list
│       │           ├── label_vocab.json # TF-IDF vocabulary: 17.7k features, segment mapping, IDF weights (1.9 MB)
│       │           ├── label_thresholds.json # Per-label optimized thresholds + evaluation metrics
│       │           └── label_*.py      # 7 m2cgen-exported LightGBM classifiers (670KB-1MB each)
│       └── templates/                  # Built-in templates (bundled in package)
│           ├── default/                # Single general-purpose agent
│           │   └── agent.yaml
│           ├── fullstack/              # Architect + implementer + reviewer + tester
│           │   ├── architect.yaml
│           │   ├── implementer.yaml
│           │   ├── reviewer.yaml
│           │   └── tester.yaml
│           ├── python/                 # Python developer + reviewer
│           │   ├── developer.yaml
│           │   └── reviewer.yaml
│           ├── typescript/             # TypeScript developer + reviewer
│           │   ├── developer.yaml
│           │   └── reviewer.yaml
│           ├── react/                  # React developer + reviewer
│           │   ├── developer.yaml
│           │   └── reviewer.yaml
│           ├── rules/                  # Rule templates (project-rule, coding-standards)
│           │   ├── project-rule-template.yaml
│           │   └── coding-standards.yaml
│           ├── context/               # Context templates (project-context, api-context)
│           │   ├── project-context.yaml
│           │   └── api-context.yaml
│           └── _builtin/              # Auto-installed on writ init (not user-selectable templates)
│               ├── writ-context.md    # CLI command reference, written to IDE rules dirs
│               ├── prompts/           # Injected instructions for "commands as instructions" pattern (versioned .md files, loaded by commands at runtime)
│               │   ├── docs-init-v1.md         # Instruction for writ docs init (LLM populates docs index)
│               │   ├── docs-update-v1.md       # Instruction for writ docs update (LLM acts on health-check findings, updates docs, logs summary; Step 2b concept-gap pass)
│               │   ├── docs-update-subagent-v1.md # Delegation prompt for writ docs update --subagent (parent writes semantic handover; subagent runs git/docs check/update)
│               │   ├── lint-deep-v1.md         # Qualitative review rubric for writ lint --prompt (actionable feedback, not scoring)
│               │   ├── lint-fix-v1.md          # Fix hook for writ lint --prompt --fix (instructs LLM to apply fixes directly)
│               │   ├── plan-review-local-v1.md # Wrapper for writ plan review (default prompt injection for IDE's AI)
│               │   └── hooks/                  # Type-specific supplement prompts, dynamically injected after base rubric by lint --prompt
│               │       ├── hook-lint-skill.md   # Skill-specific review criteria (procedure, triggers, self-containment)
│               │       ├── hook-lint-agent.md   # Agent-specific review criteria (persona, scope, delegation)
│               │       ├── hook-lint-rule.md    # Rule-specific review criteria (testability, contradictions, exceptions)
│               │       ├── hook-lint-plan.md    # Plan-specific review criteria (ordering, dependencies, risks)
│               │       ├── hook-lint-context.md # Context-specific review criteria (currency, minimality, accuracy)
│               │       ├── hook-lint-other.md   # Fallback for unknown document types (universal quality checks)
│               │       ├── hook-lint-security-light.md # Compact security quick-check (always injected on --prompt)
│               │       └── hook-lint-security-deep.md  # OWASP Agentic Top 10 deep review (injected with --prompt --security)
│               ├── agents/            # Built-in agent templates, auto-installed to IDE agents/ dirs on writ init
│               │   └── writ-agent.md  # Subagent for writ commands (lint --subagent, plan review --subagent)
│               └── skills/            # 12 battle-tested skills, auto-installed to IDE skill dirs on writ init
│                   ├── commands.md    # writ CLI command reference (installed as writ-commands/SKILL.md)
│                   ├── autoresearch.md, plan-skill.md, doc-maintenance.md, doc-health.md, pre-commit-checks.md
│                   ├── code-simplifier.md, security-scan.md, verify-skill.md, tech-debt-fixer.md
│                   └── superpower-skill.md, skill-creator-skill.md
├── tests/                              # pytest test suite (700+ tests)
│   ├── conftest.py                     # Shared fixtures (temp dirs, sample configs, monkeypatched cwd)
│   ├── test_cli.py                     # CLI command tests (init, add, search, templates, import, publish/unpublish)
│   ├── test_compose.py                 # Composition engine tests
│   ├── test_formatter.py               # Formatter output tests (IDE_PATHS config, content-category routing, all 11 safe formats, legacy formats)
│   ├── test_library.py                 # save + list --library tests
│   ├── test_login.py                   # Login/logout + remote sync + writ add fallback tests (mocked RegistryClient)
│   ├── test_mcp.py                     # MCP server tools V1-V5 + peer tools + identity + install tests (86 tests)
│   ├── test_register.py                # Account registration tests (writ register)
│   ├── test_scanner.py                 # Scanner + file parsing tests (mdc, CLAUDE.md, .windsurfrules)
│   ├── test_store.py                   # Store read/write tests (.writ/ and ~/.writ/)
│   ├── test_sync.py                    # Bulk library sync tests (writ sync)
│   ├── test_models.py                  # Pydantic model tests
│   ├── test_linter.py                  # Lint rules, v2 scoring, text signals, ML gating, safety-vector/deduction regressions, Tier 2 E2E archetypes
│   ├── test_messaging.py              # Conversation lifecycle, peers, attachments, _latest.md, CLI smoke tests
│   ├── test_invoker.py                # CLI agent detection, invocation, API fallback tests (22 tests)
│   ├── test_context_window.py         # Token estimation, sliding window, system prompt tests (19 tests)
│   ├── test_approvals_cli.py          # Approvals create/list/approve/deny CLI tests (14 tests)
│   ├── test_diff.py                   # writ diff score comparison tests
│   ├── test_handoff_cli.py            # Handoff create/list CLI tests (10 tests)
│   ├── test_knowledge_cli.py          # Review + threads CLI tests (17 tests)
│   ├── test_memory_cli.py             # Memory export/import/list CLI tests (9 tests)
│   ├── test_upgrade.py               # Upgrade command tests (10 tests)
│   ├── test_docs.py                  # Documentation health commands tests (docs init/check/update, query, status, log)
│   └── test_type_inference.py        # Type inference, changed patterns, plan --local, lint type hooks, reverse drift, core files, staleness config (37 tests)
├── action/                             # GitHub Action for writ lint (composite action, enwrit/writ@main)
│   └── action.yml                     # Composite action: install enwrit, lint specified files, SARIF upload, PR comments, changed-files-only
├── .cursor/                            # See .cursor-treeview.mdc for full breakdown
├── pyproject.toml                      # Package metadata, deps, CLI entry point ([project.scripts] writ)
├── requirements.txt                    # Core dependencies (pinned versions)
├── requirements-dev.txt                # Dev dependencies (pytest, ruff, etc.)
├── README.md                           # Project overview, install, quickstart, command list
├── LICENSE                             # MIT
├── AGENTS.md                           # Dogfooding -- our own tool manages this
├── .gitattributes
├── .gitignore
└── .github/
    └── workflows/
        ├── ci.yml                      # pytest + ruff linting on PR (3 OS x 3 Python versions)
        └── publish.yml                 # Github actions publish workflow, PyPI
```

### The `.writ/` directory (created by `writ init` in user repos)

```
.writ/                                  # Per-project store
├── config.yaml                         # Tool settings (active formats, registry URL)
├── agents/                             # Agent instruction definitions (task_type: agent)
│   └── *.yaml
├── rules/                              # Rule definitions (task_type: rule)
│   └── *.yaml
├── context/                            # Context definitions (task_type: context)
│   └── *.yaml
├── programs/                           # Program definitions (task_type: program)
│   └── *.yaml
├── handoffs/                           # Context handoff data between agents
├── memory/                             # Importable cross-project memory
├── conversations/                      # Agent-to-agent conversation files (append-only markdown)
│   └── _latest.md                      # Latest received message (overwritten on each new message, for efficient agent reads)
├── lint-scores.json                    # Auto-saved lint scores (headline, dimensions, tier, timestamp per file)
├── peers.yaml                          # Peer repo connections (name, path/remote, auto_respond, max_turns)
└── project-context.md                  # Auto-generated project context (from scanner)

~/.writ/                                # Global store (local cache of remote)
├── config.yaml                         # Global preferences, auth token
├── agents/                             # Personal agent library (synced to api.enwrit.com when logged in)
│   └── *.yaml
├── rules/                              # Personal rule library
│   └── *.yaml
├── context/                            # Personal context library
│   └── *.yaml
├── models/                             # Downloaded GGUF models for --local (auto-downloaded on first use)
│   └── writ-lint-0.8B-Q4_K_M.gguf    # ~530 MB, fine-tuned Qwen3.5-0.8B for lint feedback
├── memory/                             # Cross-project memory exports
│   └── *.yaml                          # PLANNED: synced to remote backend
├── templates/                          # PLANNED: user's custom templates
└── cache/                              # PLANNED: registry search cache
```