Files
phronesis/SPEC.md
T
nvaldez e913d0b67f feat v0.2.0: phronesis <skill> --uninstall - remove installed skills
- --uninstall [--project] removes the harness target skill directory
  and drops the matching state entry; --install/--uninstall exclusive
- safety guard (SPEC 6.6): the directory must hold a parseable SKILL.md
  whose front-matter name equals the directory, else refused, exit 2;
  unbundled (retired) skill names can still be removed by name
- SPEC section 6 items 6.6-6.7, section 3 table/3.2, item 8.4 rewritten;
  README command block; 8 new tests (76 total, all checks green)

Generated by Mistral Vibe.
Co-Authored-By: Mistral Vibe <vibe@mistral.ai>
2026-11-19 11:22:35 +01:00

370 lines
18 KiB
Markdown

# phronesis specification
How this repository is laid out, what the CLI does, and the rules for
maintaining it. This file alone is enough to rebuild the tool: it
states every observable behavior. Change this file first when the
behavior changes, then change the code and the tests to match.
<!-- toc-start: headings 2..6 -->
- [1. Purpose](#1-purpose)
- [2. Layout](#2-layout)
- [3. Command line](#3-command-line)
- [4. Skill registry and front matter](#4-skill-registry-and-front-matter)
- [5. Harnesses](#5-harnesses)
- [6. Install and project](#6-install-and-project)
- [7. Update](#7-update)
- [8. State file](#8-state-file)
- [9. Quality gates](#9-quality-gates)
- [10. Packaging](#10-packaging)
- [11. Implementation plan](#11-implementation-plan)
- [12. Release](#12-release)
<!-- toc-end -->
## 1. Purpose
- **1.1** Every heading and list item has a stable id. Cite an item as
`SPEC item 3.7.1`. New items get the next free number; numbers of
removed items are not reused.
- **1.2** phronesis is a repository of skills: self-contained
`SKILL.md` instruction packages. The CLI lists them, and installs
them into an agent harness such as Vibe:
```text
phronesis list every skill
phronesis <category> filter the list
phronesis <skill> show one skill and an install hint
phronesis <skill> --install [--harness <name>] install globally
phronesis <skill> --project [--harness <name>] install in the project only
phronesis --update update every installed skill
```
- **1.3** The tool is a pip or pipx package (section 10); after
`pipx install phronesis` the command `phronesis` is on `PATH` with the
skills bundled inside the wheel.
- **1.4** Harnesses are modular: the CLI knows only the harness
interface (section 5); each harness knows where that agent keeps its
skills. Adding a harness adds one class and one registry entry; no
other file changes.
- **1.5** The software may crash on bad input; no broad except hiding
defects (python-tdd skill item 0). The one dependency policy: reuse
first (daedalus SPEC item 1.5); today the dependencies are PyYAML
(front matter) and argcomplete (completion, guarded import).
## 2. Layout
- **2.1** Repository tree:
```text
phronesis/
├── src/
│ └── phronesis/ # The CLI package
│ ├── __init__.py # Package version, REPO_ROOT
│ ├── __main__.py # python -m phronesis
│ ├── cli.py # Parser, list, install, update, dispatch
│ ├── registry.py # Skill dataclass, bundled SKILLS, front matter
│ ├── harnesses.py # Harness interface, HARNESS_REGISTRY, vibe harness
│ ├── state.py # installed.json load, save, record
│ ├── completions.py # Completion candidates for argcomplete
│ └── formatting.py # Table cells, wrapping, colors
├── test/ # pytest suite, one module per source module
├── skill/ # One directory per skill; ships as package data
│ └── <name>/
│ ├── SKILL.md # required front matter file
│ └── <support files> # templates, rules, scripts (optional; all ship)
├── publish.py # Release guards, build, twine check/upload (section 12)
├── MANIFEST.in # Ships skill/ in the sdist
├── autotest.py # Every repo check, single entry point
├── SPEC.md # This file
├── README.md, CONTRIBUTING.md, LICENSE
├── pyproject.toml, requirements.txt
└── dist/ # Build artifacts, gitignored
```
- **2.2** The skills ship through the package as
`phronesis._skills` mapped to the repository folder `skill/`
(SPEC item 10.3), so the registry resolves the same paths from a
checkout and from an installed package (daedalus `_library` pattern).
## 3. Command line
| Call | Result | Exit code |
| --- | --- | --- |
| `phronesis` | Version line, then every skill (SPEC items 3.3.1 to 3.3.5) | 0 |
| `phronesis -l`, `phronesis --list` | Same as the bare call | 0 |
| `phronesis <category>` | Version line, then the skills in that category | 0 |
| `phronesis <skill>` | The one-row table for that skill plus an install hint | 0 |
| `phronesis <skill> --install [--harness <name>]` | Install globally (section 6) | 0, or 2 on error |
| `phronesis <skill> --project [--harness <name>]` | Install in the project only (section 6) | 0, or 2 on error |
| `phronesis <skill> --uninstall [--project] [--harness <name>]` | Remove the skill and its state entry (SPEC items 6.6 to 6.7) | 0, or 2 on error |
| `phronesis --update` | Update every installed skill (section 7) | 0, or 2 on error |
| `phronesis --version` | `phronesis <version>` | 0 |
| `phronesis -h`, `phronesis --help` | Usage (SPEC item 3.8) | 0 |
| Unknown option, category, or skill; unknown harness | Error and close matches to stderr | 2 |
- **3.1** One positional `<category|skill>` word is allowed. A token is
a category only when it matches a category in use; otherwise it is
treated as a skill name. Names and category labels must not collide
(SPEC item 4.6).
- **3.2** `--install` and `--project` are mutually exclusive, and so are
`--install` and `--uninstall`; each needs a skill word; with neither
install nor uninstall option the call lists. `--project` scopes
`--uninstall` to the project (SPEC item 6.7).
- **3.3** Listing format (bare, `--list`, filtered, one skill):
- **3.3.1** First line `Phronesis Version: <version>`. When at least
one skill is listed, a blank line and the table follow.
- **3.3.2** The table has a header row `skill`, `version`,
`category`, then a rule row of `-` per column. Columns are
left-aligned, padded to the widest cell (header included), and
separated by two spaces. The `version` column is at least 7 wide.
- **3.3.3** One row per skill, sorted by name. `version` is the
front matter version, `category` the front matter category.
- **3.3.4** Under each row the description is wrapped to the terminal
width (at least 40 columns; 80 when the width cannot be read),
every line indented by 8 spaces. Long words and hyphenated words
are not split.
- **3.3.5** Color like daedalus: when enabled, the padded name cell
is green (`ESC[32m`), the version cell yellow (`ESC[33m`), the
category cell bright blue (`ESC[94m`), each followed by `ESC[0m`.
Enabled when `NO_COLOR` is unset or empty and either `FORCE_COLOR`
is non-empty or stdout is a terminal; a non-empty `NO_COLOR` wins.
```text
Phronesis Version: 0.1.0
skill version category
----------- ------- ----------
python-tdd 1.2.0 development
Minimalist TDD architect for Python work
```
- **3.4** `phronesis <skill>` (no install option) prints the filtered
table for that one skill, then a blank line and
`install: phronesis <skill> --install --harness <name>`.
- **3.5** Unknown skill or empty category: exit 2 with close matches
on stderr (up to 3 candidates, similarity at least 0.6).
- **3.6** `-h` / `--help` prints the argparse rendering of the parser
in SPEC item 3.10.
- **3.7** The installed command is the entry point
`phronesis = phronesis.cli:main`; `python -m phronesis` from the
repository root works the same.
- **3.8** Shell completion uses argcomplete and is off when the
package is not installed (guarded import). The completion candidates
are the category labels in use, the skill names, the `--harness`
choices, and `--install`, `--project`, `--force`, `-f`.
- **3.9** `--version` prints the installed distribution version; when
the metadata is missing, the version falls back to the checkout
`pyproject.toml`, else `unknown`.
## 4. Skill registry and front matter
- **4.1** A skill is one directory under `skill/` named after the
skill, containing a single required file `SKILL.md`. Support files
may follow later; the whole directory is copied on install.
- **4.2** `SKILL.md` starts with a `---` fenced YAML header with the
required keys `name`, `version`, `description`, `category`.
- **4.3** `name` equals the directory name; `version` is `x.y.z`;
`category` is a lowercase kebab label `^[a-z][a-z0-9-]*$`.
- **4.4** The registry loads every bundled skill at import time by
scanning `phronesis._skills/*/SKILL.md` through
`importlib.resources` and parsing the front matter; a malformed
skill raises at import, so tests and CI catch it immediately.
- **4.5** Skills cached in `SKILLS: dict[str, Skill]` keyed by name;
`Skill` carries name, version, description, category, and the source
directory path.
- **4.6** Every category in use is offered by completion and by the
`<category>` word (SPEC items 3.1, 3.8).
## 5. Harnesses
- **5.1** A harness is a class with `name` and two locations:
`global_dir()` for the machine-level skill directory, and
`project_dir(cwd)` for the project-level skill directory.
- **5.2** `HARNESS_REGISTRY: dict[str, Harness]` maps names to instances;
`--harness <name>` picks from it. Unknown harness exits 2 with the
available names on stderr.
- **5.3** `--harness` defaults to `vibe`; the default can change when
more harnesses arrive, never silently in a patch release.
- **5.4** The `vibe` harness targets Mistral Vibe:
- **5.4.1** `global_dir()` is `~/.vibe/skills`.
- **5.4.2** `project_dir(cwd)` is `<cwd>/.vibe/skills`.
- **5.4.3** Skills install as `<dir>/<name>/SKILL.md`; Vibe
discovers global skills in `~/.vibe/skills` and project skills in
the project's `.vibe/skills`.
- **5.5** A new harness adds one class and one `HARNESS_REGISTRY` entry;
the CLI, table, tests, and state file do not change.
## 6. Install and project
- **6.1** `phronesis <skill> --install` copies the whole skill
directory from the bundle into `harness.global_dir()/<name>/`;
`--project` copies into `harness.project_dir(cwd)/<name>/`. Parent
directories are created.
- **6.2** When the target `SKILL.md` already exists the CLI prompts
once on stderr and reads the answer from stdin:
`skill installed as <version>, bundle has <version>. update? [y/N]`
- **6.2.1** Answering `y` or `Y` overwrites and records the state.
- **6.2.2** Any other answer or end of stdin leaves the target
untouched, prints `skipped`, and exits 0.
- **6.2.3** `--force` (or `-f`) overwrites and records without
prompting.
- **6.3** After every install or overwrite the state file records the
entry (section 8).
- **6.4** Success prints one line to stdout:
`installed python-tdd 1.2.0 (vibe, global) -> /home/me/.vibe/skills/python-tdd/SKILL.md`.
- **6.5** A skill that is not bundled exits 2 with close matches
(SPEC item 3.5).
- **6.6** `phronesis <skill> --uninstall` removes the harness
target directory `harness.global_dir()/<name>/`, or the project one
with `--project`. A safety guard runs first: the directory must hold
a `SKILL.md` whose front matter parses and whose `name` equals the
directory; anything else is refused with exit 2 and nothing is
deleted. The skill does not need to still be bundled (SPEC item 8.3).
- **6.7** After a successful removal the matching state entry
`(name, harness, scope)` is dropped (SPEC item 8.3), and one line is
printed: `removed <name> <version> (<harness>, <scope>) -> <path>`.
A missing state entry does not fail the removal.
## 7. Update
- **7.1** `phronesis --update` loads the state file and processes
every recorded entry, so all installed skills end at the bundled
versions; it never prompts.
- **7.2** Per entry: copy the bundled directory over the recorded
path, print `updated python-tdd 1.0.0 -> 1.2.0 (vibe, global)`, and
record the new version in the state.
- **7.3** Entries whose local file is missing are reinstalled the same
way, so `--update` also repairs a broken tree.
- **7.4** Entries whose skill is no longer bundled print a warning to
stderr and are kept; the exit code stays 0.
- **7.5** When the state file records nothing, `--update` prints
`nothing installed` and exits 0.
## 8. State file
- **8.1** The CLI keeps one JSON state file per machine at
`<config>/phronesis/installed.json`, where `<config>` is
`%APPDATA%` on Windows and `$XDG_CONFIG_HOME` else `~/.config`
elsewhere. `$PHRONESIS_CONFIG` overrides the location wholesale for
tests and unusual setups.
- **8.2** The file is a JSON object holding a `skills` list; each
entry has `name`, `version`, `harness`, `scope`, `path`, and
`installed` (an ISO date):
```json
{
"skills": [
{
"name": "python-tdd",
"version": "1.2.0",
"harness": "vibe",
"scope": "global",
"path": "/home/me/.vibe/skills/python-tdd/SKILL.md",
"installed": "2026-11-19"
}
]
}
```
- **8.3** An entry is unique by `(name, harness, scope)`: reinstalling
updates the entry instead of appending a new one. The `path` is the
absolute `SKILL.md` path; `scope` is `global` or `project`.
- **8.4** `--uninstall` drops the matching entry (SPEC item 6.7);
a state entry whose files were removed by hand is reinstalled by
`--update` (SPEC item 7.3).
## 9. Quality gates
- **9.1** `autotest.py` is the single entry point and runs every check
in parallel; any check failing fails the run (exit 1).
- **9.2** `sanity`, `python_syntax`, `pycodestyle`, `shellcheck`,
`frontmatter`, and `markdown` cover every script and markdown file
in the repository as in the daedalus spec.
- **9.3** `frontmatter` requires the SPEC item 4.2 keys and checks the
SPEC item 4.3 formats on every `skill/<name>/SKILL.md`.
- **9.4** `pytest` runs the suite from `test/` in a subprocess with
coverage over the `phronesis` package and fails under 75 percent.
- **9.5** `requirements.txt` pins the check dependencies and the test
dependencies; the runtime dependencies live in `pyproject.toml`
(SPEC item 10.2).
- **9.6** The markdown check configures md025's `front_matter_title`
search with a pattern that never matches, so a `title` key in
skill front matter is not an implicit second top-level heading;
a genuine duplicate h1 still fails the check.
## 10. Packaging
- **10.1** src layout: the package lives at `src/phronesis/`, the
console script is `phronesis = phronesis.cli:main`, the wheel
requires Python 3.11 or newer.
- **10.2** Runtime dependencies: `pyyaml`, `argcomplete`.
- **10.3** The `skill/` folder ships as package data: the distribution
maps the package `phronesis._skills` to the repository folder
`skill/` with every file included, so the registry sees the packaged
skills through `importlib.resources` (SPEC item 2.2).
- **10.4** Build backend is setuptools; a checkout can run
`python -m pip install -e .` and the CLI stays identical to the
installed one.
## 11. Implementation plan
- **11.1** `registry.py` first: front matter parsing, `Skill`, and the
SKILLS scan; unit tested alone.
- **11.2** `state.py`: the JSON load, save, and record logic with
roundtrip tests.
- **11.3** `harnesses.py`: the interface and the vibe harness, tested
against empty temporary home and project directories.
- **11.4** `formatting.py` and `completions.py`: the table rendering
and the completion candidate functions, tested as pure functions.
- **11.5** `cli.py` last: parser, dispatch, install, and update wiring
the parts above; end to end tests through `main(argv)`.
- **11.6** The implementation order is bottom up so every layer has a
test before its consumer exists.
## 12. Release
- **12.1** `publish.py` at the repository root releases the package to
PyPI, ported from daedalus `python/src/publish/publish.py`: guards,
a chained sdist to wheel build, `twine check`, and with `--upload`
a twine upload of exactly this version's two artifacts. It is run
from the checkout (`.venv/bin/python publish.py [--upload]`); the
state of the tree is the source of truth.
- **12.2** Guards, each stopping before anything is built: no
`pyproject.toml` beside the script is exit 2; a dirty working tree
is exit 3; a HEAD whose tags do not include `v<version>` is exit 4
with the tags it actually carries printed; missing
`python -m build` or `python -m twine` is exit 5 with the
`pipx inject phronesis build twine` hint; a version already on PyPI,
or a PyPI that cannot be reached, is exit 6 (never publish blind).
- **12.3** The tag guard lists the tags on HEAD and accepts
`v<version>` among them, so the `stable` and `latest` roller tags
on the same commit never trip it.
- **12.4** Build failure is exit 7; a `twine check` complaint (for
example a README that will not render) is exit 8. Without
`--upload` the run ends there with exit 0 and prints the command
that would upload.
- **12.5** `--upload` runs `python -m twine upload` over exactly
`dist/<name>-<version>.tar.gz` and the matching wheel, never
`dist/*`: upload failure is exit 9. Credentials are never handled
by the script: twine prompts or reads `~/.pypirc` (username
`__token__` with a PyPI API token).
- **12.6** A published version is immutable (guard item 12.2, exit 6).
To change anything, including the README that PyPI renders, bump
the version in `pyproject.toml`, commit, tag, and release again
(daedalus SPEC item 9.8 practice).
- **12.7** The README that ships must use absolute links to the
repository web UI: PyPI resolves relative links against the
project page and they break (`pypi.org/project/phronesis/<v>/...`),
found at 0.1.0. Links target `src/branch/master` on the repository
server; markdown anchors (`#...`) stay relative and keep working.
- **12.8** `MANIFEST.in` ships `skill/` in the sdist; the wheel
carries the skills as `phronesis._skills` package data (SPEC item
10.3); `dist/` is build output, gitignored, and never committed.
- **12.9** Release tags: `v<version>` on the release commit, and the
`stable` and `latest` roller tags moved onto the same commit
(`git tag -f ...` plus `git push -f origin stable latest`).
- **12.10** Release tooling dependencies (`build`, `twine`) live in
`requirements.txt` (SPEC item 9.5); the wheel's runtime
dependencies stay minimal (SPEC item 10.2).