Metadata-Version: 2.4
Name: openspec-ui
Version: 0.5.0
Summary: An unofficial, community-built interactive TUI for visualizing and managing OpenSpec changes and specs. Not affiliated with Fission-AI/OpenSpec.
Project-URL: Homepage, https://github.com/mrn-dk/openspec-ui
Project-URL: Repository, https://github.com/mrn-dk/openspec-ui
Project-URL: Issues, https://github.com/mrn-dk/openspec-ui/issues
Author: OpenSpec UI Contributors
License-Expression: MIT
License-File: LICENSE
Keywords: dashboard,openspec,spec-driven,textual,tui
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: POSIX
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Software Development :: Documentation
Classifier: Topic :: Terminals
Requires-Python: >=3.10
Requires-Dist: textual>=1.0.0
Description-Content-Type: text/markdown

# openspec-ui

> **Unofficial.** `openspec-ui` is a community-built tool and is **not
> affiliated with, endorsed by, or sponsored by [Fission-AI/OpenSpec](https://github.com/Fission-AI/OpenSpec).**
> It consumes the `openspec` CLI over subprocess as a third-party client.

An interactive, keyboard-driven terminal UI for visualizing and managing your
[OpenSpec](https://github.com/Fission-AI/OpenSpec) changes and specs.

`openspec view` dumps a static dashboard and exits. `openspec-ui` is the
interactive version: browse changes and specs, glance at progress, see a kanban
pipeline of your changes, open artifacts, edit them in `$EDITOR`, and create new
changes — all from one terminal command.

## Install & run

```bash
uvx openspec-ui
```

Run it from inside any directory containing an `openspec/` root (or a
subdirectory of one). Requires the `openspec` CLI on PATH.

Requires Python 3.10+ and [Textual](https://textual.textualize.io/) 1.0 or
newer (installed automatically).

## What it does

- **Dashboard** — an aligned table of changes (stage, name, progress, tasks,
  last modified) over headline counts of specs and of changes per stage.
  Specs are listed with their requirement counts.
- **Kanban** — a pipeline view of changes by stage, each column and card
  carrying that stage's colour, for at-a-glance status.
- **Change detail** — renders a change's artifacts (`proposal.md`,
  `design.md`, `specs/**`) as scrollable markdown with a navigable table of
  contents; ASCII diagrams and code blocks stay aligned in monospace. When an
  artifact resolves to several files, each gets its own tab.
- **Tasks** — a change's `tasks.md` rendered as its checklist, one section per
  heading with a done/total count. Read-only; edits go through `$EDITOR`.
- **Spec browser** — open a spec to read its overview and requirements, each
  expandable to reveal its scenarios.
- **Filter** — press `/` to narrow the changes and specs by name.
- **Edit** — press `e` to open the current artifact in `$EDITOR`; the view
  reloads from disk when the editor exits.
- **New change** — press `n` to create a change via `openspec new change`.
- **Command palette** — `Ctrl+P` for fuzzy-searchable actions, including
  jumping straight to any change or spec by name, and switching theme.
- **Live refresh** — open views re-read from disk as things change on disk;
  press `p` to pause.

Press `?` at any time for the key bindings available on the current screen.

## Screenshots

<sub>Screenshots show an example project, not this repository.</sub>

**Dashboard** — changes in an aligned table with stage, progress and task
counts, over headline counts per stage.

![The dashboard: changes in an aligned table with stage, progress and task
counts, over headline counts per stage](docs/images/dashboard.png)

**Kanban** — `k`. Every column heading and card border carries its stage's
colour, so the shape of the pipeline reads before any of the text does.

![Kanban: four stage columns with colour-coded headings and cards carrying a
stage-coloured left border](docs/images/kanban.png)

**Change detail** — `enter` on a change. Artifacts render as scrollable
markdown with a table of contents; code blocks and ASCII diagrams keep their
monospace alignment.

![A change's design document with a navigable table of contents on the left and
an ASCII diagram preserved in the body](docs/images/change-detail.png)

**Tasks** — the `tasks.md` checklist, one section per heading with its
done/total count. Finished sections start collapsed so the eye lands on what is
left. Read-only: edits go through `$EDITOR`.

![The tasks pane: sections with completion counts, completed sections collapsed
and remaining work expanded](docs/images/tasks.png)

**Spec browser** — `enter` on a spec. Requirements expand to reveal their
scenarios, which is the only way a spec with thirty of them stays readable.

![A spec's requirements listed with scenario counts, one expanded to show its
WHEN/THEN scenarios](docs/images/spec-browser.png)

**Command palette** — `Ctrl+P`. Fuzzy-matched actions, plus every change and
spec by name.

![The command palette filtered to billing-related commands](docs/images/command-palette.png)

**Filter** — `/`. Narrows the changes and specs by name; `escape` clears it.

![The dashboard with a filter narrowing the list to changes whose names contain
"add"](docs/images/filtering.png)

**Light theme** — all colour comes from the active Textual theme, so it follows
your terminal.

![The same dashboard under a light theme](docs/images/dashboard-light.png)

## Contributing

This project follows the OpenSpec spec-driven workflow (`openspec/`).

Git history uses **Conventional Commits** and **conventional branch names**:

- Branches: `feat/<scope>`, `fix/<scope>`, `refactor/<scope>`, `chore/<scope>`, …
- Commits: `feat:`, `fix:`, `docs:`, `refactor:`, `chore:`, … (with a scope
  when helpful, e.g. `feat: add kanban view`).
- Never commit directly to `main`. Work on a dedicated branch and open a pull
  request with the GitHub CLI (`gh pr create`), referencing the OpenSpec change
  name in the PR description.

For changes managed through OpenSpec, see `openspec/config.yaml` for the
project context and per-operation guidance that the openspec skills follow.
