e913d0b67f
- --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>
370 lines
18 KiB
Markdown
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).
|