yirifi-roadmap 0.2.0
CLI and TUI for yirifi-roadmap planning system
Requires Python: >=3.10

# yirifi-roadmap

[![PyPI](https://img.shields.io/pypi/v/yirifi-roadmap)](https://pypi.org/project/yirifi-roadmap/)
[![Python](https://img.shields.io/pypi/pyversions/yirifi-roadmap)](https://pypi.org/project/yirifi-roadmap/)

CLI and TUI for the yirifi-roadmap planning system. Handles all mechanical operations
(ID generation, status transitions, schema validation, progress computation, dependency
graphs) so Claude can focus on intelligence.

## Installation

### From PyPI

```bash
# CLI only
uv pip install yirifi-roadmap

# CLI + Terminal UI
uv pip install "yirifi-roadmap[tui]"
```

### From Source (development)

```bash
cd yirifi-roadmap-app

# CLI only
uv pip install -e .

# CLI + TUI
uv pip install -e ".[tui]"

# With dev dependencies (testing)
uv pip install -e ".[tui,dev]"
```

## Usage

### CLI

```bash
yirifi-roadmap --help

# Query commands
yirifi-roadmap query status          # Items grouped by status
yirifi-roadmap query backlog         # Approved items by priority
yirifi-roadmap query blocked         # Blocked items + blockers
yirifi-roadmap query assigned saurav # Items for a person
yirifi-roadmap query progress        # Progress aggregation

# Compute commands
yirifi-roadmap compute stats         # Roadmap-wide statistics
yirifi-roadmap compute graph         # Dependency graph + bottlenecks
yirifi-roadmap compute impact feat-x # What does completing this unblock?
yirifi-roadmap compute stale         # Items not updated in 30+ days

# Validate commands
yirifi-roadmap validate audit        # Full repo health check
```

All commands output JSON by default. Add `--human` for formatted text.

### TUI

```bash
yirifi-roadmap-tui
```

5 tabs: Dashboard, Items, Board (kanban), Timeline, Dependencies.

Keyboard shortcuts: `1-5` switch tabs, `r` refresh, `n` new item, `q` quit, `Enter`
open detail, `t` transition, `c` check tasks, `Esc` close modal.

### Without Installing

```bash
cd yirifi-roadmap-app

# CLI
python -m yirifi_roadmap.cli --help

# TUI
python -m yirifi_roadmap.tui
```

## Command Groups

| Group | Commands | Purpose |
|-------|----------|---------|
| `id` | 3 | ID generation, checking, resolution |
| `query` | 13 | Read-only data retrieval |
| `validate` | 5 | Schema and rule enforcement |
| `scaffold` | 8 | Template rendering + file creation |
| `mutate` | 10 | Status transitions, field updates, tasks, archiving |
| `compute` | 8 | Dependency graphs, impact analysis, stats |

See [CLI Reference](../docs/core_reference/03-cli-reference.md) for the full command list.

## Publishing

```bash
./scripts/publish-pypi.sh              # Interactive mode
./scripts/publish-pypi.sh --bump patch # Bump and publish
./scripts/publish-pypi.sh --dry-run    # Build only, no upload
./scripts/publish-pypi.sh --help       # All options
```

## Documentation

- [Onboarding Guide](../docs/onboarding.md) — Getting started
- [Architecture Overview](../docs/core_reference/00-architecture-overview.md) — Two-layer design
- [CLI Reference](../docs/core_reference/03-cli-reference.md) — All 45 commands
- [Slash Commands](../docs/core_reference/04-slash-commands.md) — Claude Code integration