slicer

Roadmap and slice management for the review → slice → implement → done loop.

slicer is AI-friendly: a coding agent can review a project, turn accepted findings into an importable roadmap, and work through bounded slices using commands with JSON output. For a new project, start with goals and acceptance criteria instead of review findings. The AI supplies the review and planning; slicer stores, validates, prioritizes, and renders the work. It runs locally without an AI service or API key.

Run slicer ai instructions for a concise agent quick start, or add --json for machine-readable output. It works before initialization and reads no project state.

The permanent canonical store is git-tracked JSON under .slicer/. It travels with branches and clones, exposes state changes in review diffs, and lets slicer check compare generated output byte for byte. The markdown under .slicer/render/ is generated output — readable, committed, and never parsed back. Edit through the commands or the TUI, not by hand.

Any future database may only be a disposable cache inside the checkout: gitignored, rebuildable from JSON, and never read back as authority. ~/.slicer/ is not a canonical state directory; canonical state stays inside the checkout. Coordination stays in git.

Stdlib Python 3.11+, no dependencies.

Install

Into its own virtual environment from PyPI. The distribution is squalor-slicer because the slicer name on PyPI is taken; the command it installs is still slicer.

python3 -m venv ~/.slicer-venv
~/.slicer-venv/bin/pip install squalor-slicer
ln -s ~/.slicer-venv/bin/slicer ~/.local/bin/slicer   # or anywhere on your PATH

slicer --about prints the version, description, source URL, and issues URL.

slicer --help confirms it. Other ways in — pip --user, pipx, uv, unreleased main — are in getting started; the editable install for working on slicer itself is in AGENTS.md.

Use it on a project

cd any-repo
slicer init                             # creates .slicer/
slicer add "Parse the config file" --size M --tree core
slicer promote S01                      # give it a slice file from the template
slicer edit S01 --section Why --text "Load settings before starting the app"
slicer render                           # regenerate .slicer/render/
slicer check                            # the gate: exit 1 if anything drifted

add appends a roadmap row; promote gives it a slice file.

Got a whole roadmap to load? Write it as a markdown outline and import it in one go:

slicer import --skeleton > roadmap.md   # a template, built from your config
slicer import roadmap.md --dry-run      # validate; writes nothing
slicer import roadmap.md                # apply

Each ## heading is an item, optional key: value lines carry its size, tree and dependencies, and ### sections become the slice itself — so one file can produce a fully written roadmap. It is a one-way ramp: the file is yours to delete afterwards.

Already running this workflow by hand in markdown? slicer migrate --from docs/slices converts an existing tree that is already in slicer's legacy format. It refuses to write anything unless every file round-trips byte for byte, so a document slicer cannot reproduce is never half-migrated.

Commands

Every flag, the .slicer/ layout, removing items, and roadmap prose are in the command reference; keys and screens are in the TUI manual. Every command except tui/ui takes --json, failures included; the agent reference has the payloads and exit codes.

slicer never commits, pushes or tags. Its git access is a read-only allowlist, and a mutation leaves the index untouched; see Git access.

Documentation

• Getting started — install to CI, with worked workflows for a new project and for an AI code review
• Command reference — every command and flag, .slicer/, removal, prose
• TUI manual — browsing, editing and the roadmap wizard
• Driving slicer from an agent — reusable prompts, JSON contracts, exit codes
• The outline format — what slicer import reads
• Configuration — every .slicer/config.json key and default
• Legacy format — what slicer migrate reads
• ARCHITECTURE.md — layering and invariants
• AGENTS.md — contributing: the dev loop, tests, and house style
• CHANGELOG.md — notable changes by release

Tests

python3 -m unittest discover -s tests -t tests

No install step and no dependencies — the suite puts src/ on sys.path itself. Fixtures and the optional live-tree migrator check are described in AGENTS.md.

Status

slicer manages its own roadmap: .slicer/ in this repository is a worked example you can read, and .slicer/render/ROADMAP.md is what it renders to. Run slicer --version for the installed version, and see the changelog. Its own goals and non-goals: run slicer goals, or read them at the top of the roadmap. In short, slicer is a small, dependency-light, file-based store for a project's roadmap, goals, and issues — canonical JSON that humans and AI agents plan from, projected deterministically to markdown — and is not a real-time, multi-user collaboration tool (coordination happens through git).

Apache-2.0. Stdlib Python, no dependencies, and none planned.