# dd-dm (Dungeon Master)

A CLI tool for managing shared engineering rules across projects. Define and compose rules into a project constitution, then keep them in sync with explicit, reviewable diffs.

## What it does

- Manages shared engineering rules ("constitutions") for projects
- Syncs rules between a templates repository and local projects
- Prevents convention drift between humans and AI agents
- Keeps prompts and context lean by centralizing rules

## Installation

| Method | Command | Use case |
|--------|---------|----------|
| **End Users** | | |
| uvx (no install) | `uvx dd-dungeonmaster` | Quick use, no commitment |
| uv tool install | `uv tool install dd-dm --from dd-dungeonmaster` | Permanent global install |
| pip | `pip install dd-dungeonmaster` | Traditional install |
| **Testing/Development** | | |
| Test PyPI release | `uvx dd-dungeonmaster` | Verify published version works |
| Test from GitHub main | `uvx --from git+https://github.com/yizyace/dd_dungeonmaster.git dd-dm` | Test unreleased changes |
| Test specific branch | `uvx --from git+https://github.com/yizyace/dd_dungeonmaster.git@branch-name dd-dm` | Test feature branch |
| Test specific tag | `uvx --from git+https://github.com/yizyace/dd_dungeonmaster.git@v0.1.0 dd-dm` | Test specific release from source |
| **Upgrades** | | |
| Upgrade uv tool | `uv tool install dd-dm --force --from dd-dungeonmaster` | Upgrade to latest PyPI version |
| Upgrade pip | `pip install --upgrade dd-dungeonmaster` | Upgrade via pip |
| **Troubleshooting** | | |
| Check installed version | `dd-dm -v` | Verify version |
| Check install location | `which dd-dm` | Find where it's installed |
| Check package info | `uv pip show dd-dungeonmaster` | See install path, version, etc. |
| Uninstall (uv tool) | `uv tool uninstall dd-dm` | Remove global tool |
| Uninstall (pip) | `uv pip uninstall dd-dungeonmaster` | Remove from environment |

### Local Development Setup

1. Clone and setup:
   ```bash
   git clone https://github.com/yizyace/dd_dungeonmaster.git
   cd dd_dungeonmaster
   uv sync --all-extras
   ```

2. Run the CLI:
   ```bash
   uv run dd-dm --help
   ```

3. Run tests:
   ```bash
   uv run pytest
   ```

4. Run linter:
   ```bash
   uv run ruff check .
   uv run ruff format .
   ```

## Usage

```bash
# Initialize in a project (provide URL to your templates repo)
dd-dm init https://github.com/your-org/engineering-rules.git

# Add a module to your constitution
dd-dm add GIT_CONVENTIONAL_COMMITS

# Create a custom local module
dd-dm create my-team-rules

# Remove a module
dd-dm delete GIT_CONVENTIONAL_COMMITS

# Pull updates from templates repo
dd-dm pull

# Push local changes to templates repo
dd-dm push
```

## License

MIT
