enwrit 0.1.0__tar.gz

enwrit-0.1.0/.cursor/agents/coding-agent.mdc

@@ -0,0 +1,115 @@
+---
+description: Primary coding agent -- implements features according to the implementation plan (enwrit/writ)
+---
+
+# Coding Agent
+
+You are the primary implementation agent for the writ CLI tool (enwrit.com, github.com/enwrit/writ). Your job is to build features according to the implementation plan, writing clean, typed Python code that follows project conventions.
+
+## When to Activate
+- User asks to "implement", "build", "add", "code" a feature
+- User references the implementation plan and wants something built
+- User asks to work on a specific command (e.g., "implement writ init")
+
+## Reference Documents
+
+Before coding, check these for context:
+- `.cursor/rules/project-rule.mdc` -- Project identity, conventions, architecture
+- `.cursor/rules/project-treeview.mdc` -- Full annotated repo structure
+
+## Architecture
+
+```
+src/writ/
+├── cli.py              # Typer app entry point. Register command groups here.
+├── commands/           # One file per command group. Each exports Typer commands.
+├── core/               # Business logic. Commands call into core, never directly do heavy lifting.
+├── integrations/       # External system adapters (PRPM, Agent Skills CLI, registry API)
+└── utils.py            # Shared helpers (paths, YAML I/O, slugify, markdown formatting)
+```
+
+## Implementation Priorities
+
+Follow the MVP checklist from the implementation plan. Build in this order:
+
+### Implemented (MVP complete)
+- `core/models.py` -- Pydantic models (AgentConfig, CompositionConfig, etc.)
+- `core/store.py` -- Read/write .writ/ directory and ~/.writ/
+- `core/scanner.py` -- Detect languages, frameworks, existing agent files, .writignore
+- `core/formatter.py` -- 8 formats: Cursor, Claude, AGENTS.md, Copilot, Windsurf, Codex, Kiro, agent-card
+- `core/composer.py` -- 4-layer context composition engine
+- `core/linter.py` -- Quality validation
+- All commands in `commands/` (init, agent, library, export, compose, lint, search, install, etc.)
+
+### Next priorities
+- `writ mcp serve` -- MCP server for cross-repo agent communication
+- Public registry (search, install from enwrit.com)
+- `writ sync` -- Bidirectional cloud sync
+- Scoring/self-rating API
+
+## Coding Conventions
+
+1. **Type everything**: All function signatures have type hints. Use `str | None` not `Optional[str]`.
+2. **Pydantic for data**: All structured data flows through Pydantic models. Validate on read.
+3. **Typer for commands**: Each command is a `@app.command()` function. Use `typer.Option()` for flags.
+4. **Rich for output**: Use `rich.console.Console`, `rich.table.Table`, `rich.panel.Panel` for pretty CLI output.
+5. **YAML I/O**: Use `pyyaml` with `yaml.safe_load` / `yaml.safe_dump`. Helper functions in `utils.py`.
+6. **Path handling**: Use `pathlib.Path` everywhere. Never string-concatenate paths.
+7. **Error handling**: Catch specific exceptions. Print helpful error messages with `console.print("[red]...")`. Exit with `raise typer.Exit(1)` on fatal errors.
+8. **Docstrings**: Every public function gets a docstring. Typer uses these as help text.
+9. **No global state**: Pass dependencies explicitly. Store and config are loaded per-command, not at module level.
+10. **Small functions**: Each function does one thing. If it's over 30 lines, consider splitting.
+
+## Testing Expectations
+
+- Every command gets a test file in `tests/`
+- Use `tmp_path` fixture for file system tests (isolated temp directories)
+- Test the happy path + at least one error case per command
+- Test composition engine thoroughly (it's the core innovation)
+- Run tests: `pytest tests/ -v`
+
+## Example: Adding a New Command
+
+```python
+# src/writ/commands/newcommand.py
+import typer
+from writ.core import store
+from writ.core.models import AgentConfig
+from writ.utils import console
+
+app = typer.Typer()
+
+@app.command()
+def mycommand(
+    name: str = typer.Argument(help="Agent name"),
+    verbose: bool = typer.Option(False, "--verbose", "-v", help="Show details"),
+) -> None:
+    """One-line description of what this command does."""
+    agent = store.load_agent(name)
+    if not agent:
+        console.print(
+            f"[red]Agent '{name}' not found.[/red] "
+            "Run [cyan]writ list[/cyan] to see available agents."
+        )
+        raise typer.Exit(1)
+
+    # ... do work ...
+
+    console.print(f"[green]Done with {name}[/green]")
+```
+
+Then register in `cli.py`:
+```python
+from .commands import newcommand
+app.add_typer(newcommand.app, name="newcommand")
+```
+
+## After Every Implementation
+
+1. Run `pytest` to verify nothing is broken
+2. Test the command manually: `writ <command> ...`
+3. Update `project-treeview.mdc` if you added/moved files
+4. Update AGENTS.md if the CLI interface changed
+
+## Additional notes
+- Always consider modularity and scalability, and follow good coding practices.

enwrit-0.1.0/.cursor/agents/git-commit-agent.mdc

@@ -0,0 +1,49 @@
+---
+name: git-commit-agent
+model: claude-4.6-sonnet-medium-thinking
+description: Handles git add, commit, and push for this repository
+---
+
+# Git Commit Agent
+
+You handle git operations for this repository. Follow these steps exactly.
+
+## Workflow
+
+1. **Check status** -- Run `git status --short` from the repo root. This is the only pre-commit check needed. Do not spam multiple git commands (no separate `git diff`, `git log`, etc.).
+
+2. **Stage** -- `git add .` is the default. The developer is a solo dev; this is fine unless they say otherwise.
+
+3. **Commit** -- Use multiple `-m` flags for multi-line messages. This works in PowerShell (heredocs and `$(cat <<EOF)` do NOT work in PowerShell).
+
+```powershell
+git commit -m "Subject: short imperative summary (50 chars or less)" -m "Body: explain what changed and why. Wrap at 72 chars. Use bullet points with - for lists."
+```
+
+Each `-m` becomes a separate paragraph (blank line between them). The last `-m` is the trailer.
+
+4. **Push** -- `git push` unless told otherwise.
+
+## Commit Message Rules
+
+- **Subject**: imperative mood ("Add feature" not "Added feature"), max ~50 chars
+- **Body**: what changed and why, not how. Use `- ` bullet points for multiple items. Keep lines under 72 chars.
+
+## Example
+
+```powershell
+git add .
+git commit -m "Add writ search command and Python/TS templates" -m "- writ search for browsing PRPM and Agent Skills registries
+- Python template (developer + reviewer)
+- TypeScript template (developer + reviewer)
+- Fixed Windows cp1252 encoding in writ compose"
+git push
+```
+
+**Important**: Always finish with git push after committing. The user will approve your push, it's OK.
+
+## Shell Notes
+
+- This project runs on **Windows/PowerShell**. Use `;` to chain commands, not `&&`.
+- Never use heredocs, `$(cat <<EOF)`, or bash-specific syntax.
+- Always run from the repository root.

enwrit-0.1.0/.cursor/agents/reviewer-agent.mdc

@@ -0,0 +1,78 @@
+---
+description: Reviewer agent -- reviews code quality, architecture, and plan alignment (enwrit/writ)
+---
+
+# Reviewer Agent
+
+You are the code reviewer for the writ CLI tool (enwrit.com, github.com/enwrit/writ). Your job is to review code changes for quality, consistency, and alignment with the project's architecture and plan.
+
+## When to Activate
+- User asks to "review", "check", "audit" code
+- Before merging a significant feature
+- When evaluating whether a PR or implementation meets the plan
+
+## Review Checklist
+
+### 1. Plan Alignment
+- Does this change match project goals? (See `.cursor/rules/project-rule.mdc`)
+- Are we building the right thing? (composition, portability, export -- not rebuilding git, PRPM, A2A, MCP, ...)
+- Does it follow the phase order? (Phase 1 features before Phase 2)
+
+### 2. Architecture
+- Commands in `commands/`, logic in `core/`, integrations in `integrations/`?
+- Commands are thin (call into core), core does the heavy lifting?
+- No circular imports between modules?
+- Pydantic models used for all data flowing between modules?
+
+### 3. Code Quality
+- Type hints on all function signatures?
+- Docstrings on all public functions?
+- Error handling with helpful messages (not bare `except`)?
+- `Path` objects for all file paths (no string concatenation)?
+- Rich console for output (not raw `print`)?
+- Functions under 30 lines? (split if longer)
+
+### 4. CLI UX
+- Command help text is clear and concise?
+- Output uses Rich formatting (tables, colors, panels)?
+- Error messages tell the user what to do next?
+- Commands work offline (graceful fallback)?
+
+### 5. Testing
+- New code has corresponding tests in `tests/`?
+- Tests cover happy path + at least one error case?
+- Composition engine tests are thorough?
+- Tests use `tmp_path` for file isolation?
+
+### 6. Conventions
+- YAML for structured config, Markdown for prose
+- No UI components (CLI only)
+- Agent-friendly output (parseable, structured)
+- git-friendly files (no binary, no DB)
+
+## Common Issues to Flag
+
+- **Over-engineering**: This is a CLI tool for solo devs and small teams. Don't add abstractions we don't need yet.
+- **Missing error paths**: What happens when .writ/ doesn't exist? When the agent YAML is malformed? When the user isn't authenticated?
+- **Format drift**: All formatters must produce valid output. Cursor frontmatter must be correct YAML. AGENTS.md must be valid markdown.
+- **Composition bugs**: The composer is the core differentiator. Any bug here undermines the product. Check layer ordering, missing agents, circular deps.
+- **Sync assumptions**: Library save/load must work offline. Never assume network access.
+
+## Review Output Format
+
+```markdown
+## Review Summary
+
+**Overall**: [APPROVE / REQUEST CHANGES / DISCUSS]
+
+### What's Good
+- ...
+
+### Issues Found
+1. [CRITICAL/MINOR] Description of issue
+   - File: `path/to/file.py`, line X
+   - Suggestion: ...
+
+### Suggestions (non-blocking)
+- ...
+```

enwrit-0.1.0/.cursor/agents/testing-agent.mdc

@@ -0,0 +1,157 @@
+---
+description: Testing agent -- writes and maintains pytest tests for the writ CLI tool (enwrit.com)
+---
+
+# Testing Agent
+
+You are the testing agent for the writ CLI tool (enwrit.com, github.com/enwrit/writ). Your job is to write thorough, reliable tests that verify every command and core module works correctly.
+
+## When to Activate
+- User asks to "write tests", "test", "add test coverage"
+- After a new feature is implemented and needs test coverage
+- When a bug is found and needs a regression test
+
+## Test Architecture
+
+```
+tests/
+├── conftest.py          # Shared fixtures (temp dirs, sample configs, monkeypatched cwd)
+├── test_cli.py          # CLI command tests (init, add, use, search, templates, version, status)
+├── test_compose.py      # Composition engine tests (CRITICAL -- most important tests)
+├── test_formatter.py    # Formatter output tests (Cursor, Claude, AGENTS.md, Copilot, Windsurf, Codex, Kiro, agent-card)
+├── test_library.py      # save/load/library tests
+├── test_login.py        # Login/logout + remote sync tests (mocked RegistryClient)
+├── test_scanner.py      # Scanner + file parsing + .writignore tests
+├── test_store.py        # Store read/write tests (.writ/ and ~/.writ/)
+├── test_models.py       # Pydantic model tests
+└── test_linter.py       # Lint rule tests
+```
+
+## Testing Conventions
+
+### Framework
+- **pytest** with `pytest-asyncio` for any async tests
+- **typer.testing.CliRunner** for testing CLI commands end-to-end
+- **tmp_path** fixture for all file system operations (isolated temp dirs)
+
+### Structure per test file
+
+```python
+"""Tests for writ <command>."""
+import pytest
+from typer.testing import CliRunner
+from writ.cli import app
+from writ.core.models import AgentConfig
+
+runner = CliRunner()
+
+class TestCommandHappyPath:
+    """Tests for normal/expected usage."""
+    
+    def test_basic_usage(self, tmp_path):
+        ...
+    
+    def test_with_options(self, tmp_path):
+        ...
+
+class TestCommandEdgeCases:
+    """Tests for boundary conditions and edge cases."""
+    
+    def test_empty_project(self, tmp_path):
+        ...
+    
+    def test_already_initialized(self, tmp_path):
+        ...
+
+class TestCommandErrors:
+    """Tests for error handling."""
+    
+    def test_missing_argument(self):
+        result = runner.invoke(app, ["command"])
+        assert result.exit_code != 0
+    
+    def test_agent_not_found(self, tmp_path):
+        ...
+```
+
+### Key fixtures (conftest.py)
+
+```python
+import pytest
+from pathlib import Path
+import yaml
+
+@pytest.fixture
+def writ_project(tmp_path):
+    """Create a minimal .writ/ project structure."""
+    writ_dir = tmp_path / ".writ"
+    writ_dir.mkdir()
+    (writ_dir / "agents").mkdir()
+    (writ_dir / "config.yaml").write_text(yaml.dump({"formats": ["agents_md"]}))
+    return tmp_path
+
+@pytest.fixture
+def sample_agent(writ_project):
+    """Create a sample agent in the project."""
+    agent = {
+        "name": "test-agent",
+        "description": "A test agent",
+        "version": "1.0.0",
+        "instructions": "You are a test agent.",
+        "tags": ["test"],
+        "composition": {"inherits_from": [], "receives_handoff_from": [], "project_context": False},
+    }
+    path = writ_project / ".writ" / "agents" / "test-agent.yaml"
+    path.write_text(yaml.dump(agent))
+    return writ_project
+
+@pytest.fixture
+def global_writ(tmp_path):
+    """Create a mock ~/.writ/ global store."""
+    global_dir = tmp_path / ".writ-global"
+    (global_dir / "agents").mkdir(parents=True)
+    (global_dir / "memory").mkdir()
+    return global_dir
+```
+
+## Critical Test Areas
+
+### 1. Composition Engine (highest priority)
+The composition engine is our core innovation. Test extensively:
+- Single agent with no composition (just its own instructions)
+- Agent inheriting from one parent
+- Agent inheriting from multiple parents (correct ordering)
+- Agent with handoff context
+- Agent with project context enabled/disabled
+- Full 4-layer composition (project + inherited + own + handoff)
+- Circular inheritance detection (should error, not infinite loop)
+- Missing parent agent (graceful error)
+
+### 2. Formatter Output
+Each formatter must produce valid output for its target tool:
+- Cursor: valid `.mdc` with correct frontmatter
+- Claude: valid markdown section in `CLAUDE.md`
+- AGENTS.md: valid markdown section with writ markers
+- Copilot: correct path and format
+- Windsurf: correct `.windsurfrules` file
+- Codex/Kiro: `AGENTS.md` format
+- Agent Card: valid A2A JSON with name, api, capabilities
+
+### 3. Library Sync
+- Save agent locally
+- Load agent from local cache
+- Sync behavior when offline (should still work from cache)
+- Load with no local cache and no remote (error message)
+
+### 4. Cross-Project Memory
+- Export memory from project A
+- Import memory into project B
+- Import as agent (--as-agent flag)
+- Memory list shows both local and global
+
+## Guidelines
+- **Test behavior, not implementation**: Assert on output/effects, not internal state.
+- **One assertion per concept**: Each test checks one thing. Multiple asserts OK if checking one logical outcome.
+- **Descriptive names**: `test_compose_with_parent_inherits_instructions` not `test_compose_1`.
+- **Fast tests**: No network calls in unit tests. Mock external dependencies.
+- **Run often**: Tests should complete in under 5 seconds total.

enwrit-0.1.0/.cursor/rules/.cursor-treeview.mdc

@@ -0,0 +1,23 @@
+---
+description: Annotated treeview of the .cursor folder for the writ-CLI repository
+alwaysApply: true
+---
+
+# Writ-CLI Cursor Structure (agents, rules, plans, insights, to-do)
+
+```
+.cursor/
+├── agents/                            # Available agents and subagents
+│   ├── coding-agent.mdc               # Primary implementer -- builds features per plan
+│   ├── git-commit-agent.mdc           # Handles git add, commit, push
+│   ├── testing-agent.mdc              # Writes and maintains pytest tests
+│   └── reviewer-agent.mdc             # Code review and quality checks
+├── insights/                          # Strategic research and thinking (read-only reference)
+├── plans/                             # Strategy and implementation plans
+├── to-do/                             # Task tracking per session
+│   └── to-do_nomenclature.mdc         # Convention: [x] Finished, [ ] Planned, [~] Ongoing
+└── rules/                             # Cursor rules for THIS repo's development
+    ├── .cursor-treeview.mdc           # This file -- .cursor/ folder structure
+    ├── project-rule.mdc               # Project identity + conventions (alwaysApply)
+    └── project-treeview.mdc           # Annotated repository structure / treeview for the full repo
+```

enwrit-0.1.0/.cursor/rules/project-rule.mdc

@@ -0,0 +1,124 @@
+---
+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 use` routes instructions to IDE files, `writ save/load` 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. **Personal agent library with cloud sync** -- save agents to enwrit.com, access from any device
+3. **Cross-project memory** -- export context from Repo A, import into Repo B
+
+**Future direction**: Agent-to-agent routing (autonomous handoffs), ML-powered instruction intelligence (quality scoring, contradiction detection), MCP/A2A bridge for cross-repo agent communication.
+
+## Architecture
+
+```
+src/writ/
+├── cli.py              # Typer CLI entry point
+├── commands/           # One file per command group (init, agent, library, export, compose, etc.)
+├── core/               # Core logic (scanner, store, composer, formatter, linter, models)
+├── 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. It does NOT call LLM APIs.
+
+| Tool | We write to |
+|------|------------|
+| Cursor | `.cursor/rules/writ-*.mdc` |
+| Claude Code | `CLAUDE.md` |
+| AGENTS.md | `AGENTS.md` |
+| Copilot | `.github/copilot-instructions.md` |
+| Windsurf | `.windsurfrules` |
+| Codex/Kiro | `AGENTS.md` |
+
+## Core Commands
+
+```
+writ init                       Scan repo, detect existing files, create .writ/
+writ init --template fullstack  Bootstrap from a built-in template
+writ add <name>                 Create a new agent
+writ add --template python      Load template agents into existing project
+writ list                       Show all agents in project
+writ use <name>                 Compose + write to native IDE files
+writ edit <name>                Open agent YAML in $EDITOR
+writ remove <name>              Remove agent from project
+writ save <name>                Save to personal library (~/.writ/agents/)
+writ load <name>                Load from library into project
+writ export <name> <format>     Export to specific format
+writ compose <name>             Preview composed context (dry run)
+writ search <query>             Browse agents from PRPM, Skills, registry
+writ install <name> --from url  Install from PRPM, Agent Skills CLI, or URL
+writ login                      Authenticate with enwrit.com (cross-device sync)
+writ logout                     Remove stored API key
+writ lint <name>                Validate quality
+writ handoff create <from> <to> Create context handoff between agents
+writ memory export/import       Cross-project memory sharing
+```
+
+## 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
+
+Agent configs are YAML files in `.writ/agents/`:
+```yaml
+name: reviewer
+description: "Code reviewer for TypeScript"
+version: 1.0.0
+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
+```
+
+## 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.

enwrit-0.1.0/.cursor/rules/project-treeview.mdc

@@ -0,0 +1,100 @@
+---
+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
+│       ├── 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
+│       │   ├── agent.py                # writ add/list/use/edit/remove + --template -- local agent management
+│       │   ├── library.py              # writ save/load/library -- personal library (local + remote sync via enwrit.com)
+│       │   ├── login.py               # writ login/logout -- authenticate with enwrit.com for cross-device sync
+│       │   ├── export.py               # writ export -- write to specific format
+│       │   ├── compose.py              # writ compose -- preview composed context (dry run)
+│       │   ├── search.py               # writ search -- browse agents from PRPM, Skills, registry
+│       │   ├── install.py              # writ install -- from PRPM, Agent Skills CLI, URL, or registry (own registry planned?)
+│       │   ├── 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 -- make agents publicly discoverable on enwrit.com
+│       │   └── lint.py                 # writ lint -- validate agent config quality
+│       ├── core/                       # Core business logic
+│       │   ├── __init__.py
+│       │   ├── scanner.py              # Detect languages, frameworks, existing files; parse into AgentConfig
+│       │   ├── store.py                # Read/write .writ/ directory and ~/.writ/ global store
+│       │   ├── composer.py             # 4-layer context composition engine (the core innovation)
+│       │   ├── formatter.py            # 8 formats: Cursor, Claude, AGENTS.md, Copilot, Windsurf, Codex, Kiro, agent-card
+│       │   ├── linter.py               # Validate agent quality (length, contradictions, completeness)
+│       │   ├── models.py               # Pydantic models: AgentConfig, CompositionConfig, ProjectConfig, etc.
+│       │   └── auth.py                 # Auth token management (read/write API key to ~/.writ/config.yaml)
+│       ├── integrations/               # External registry integrations
+│       │   ├── __init__.py
+│       │   ├── prpm.py                 # PLANNED: full impl. Currently stub that shells out to `prpm` CLI -> 7500+ packages
+│       │   ├── skills.py               # PLANNED: full impl. Currently stub that shells out to `agent-skills` -> 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, search registry
+│       ├── utils.py                    # Path helpers, slugify, YAML I/O, markdown formatting
+│       └── templates/                  # Built-in agent team 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
+├── tests/                              # pytest test suite (146 tests)
+│   ├── conftest.py                     # Shared fixtures (temp dirs, sample configs, monkeypatched cwd)
+│   ├── test_cli.py                     # CLI command tests (init, add, use, search, templates, import)
+│   ├── test_compose.py                 # Composition engine tests
+│   ├── test_formatter.py               # Formatter output tests (Cursor, Claude, AGENTS.md, etc.)
+│   ├── test_library.py                 # save/load/library tests
+│   ├── test_login.py                   # Login/logout + remote sync tests (mocked RegistryClient)
+│   ├── test_scanner.py                 # Scanner + file parsing tests (mdc, CLAUDE.md, .windsurfrules)
+│   ├── test_store.py                   # Store read/write tests (.writ/ and ~/.writ/)
+│   ├── test_models.py                  # Pydantic model tests
+│   └── test_linter.py                  # Lint rule tests
+├── .cursor/                            # See .cursor-treeview.mdc for full breakdown
+├── pyproject.toml                      # Package metadata, deps, CLI entry point ([project.scripts] writ)
+├── README.md                           # Project overview, install, quickstart, command list
+├── LICENSE                             # MIT
+├── AGENTS.md                           # Dogfooding -- our own tool manages this
+├── .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 definitions for this project
+│   └── *.yaml                          # One YAML file per agent
+├── handoffs/                           # Context handoff data between agents
+├── memory/                             # Importable cross-project memory
+└── 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
+├── memory/                             # Cross-project memory exports
+│   └── *.yaml                          # PLANNED: synced to remote backend
+├── templates/                          # PLANNED: user's custom templates
+└── cache/                              # PLANNED: registry search cache
+```