# 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. - [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) ## 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 filter the list phronesis show one skill and an install hint phronesis --install [--harness ] install globally phronesis --project [--harness ] 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 │ └── / │ ├── SKILL.md # required front matter file │ └── # 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 ` | Version line, then the skills in that category | 0 | | `phronesis ` | The one-row table for that skill plus an install hint | 0 | | `phronesis --install [--harness ]` | Install globally (section 6) | 0, or 2 on error | | `phronesis --project [--harness ]` | Install in the project only (section 6) | 0, or 2 on error | | `phronesis --uninstall [--project] [--harness ]` | 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 ` | 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 `` 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: `. 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 ` (no install option) prints the filtered table for that one skill, then a blank line and `install: phronesis --install --harness `. - **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 `` word (SPEC items 3.1, 3.8). - **4.7** Every bundled skill ships a `MEMORIES.md` memory template beside its `SKILL.md` (the pattern of the `memory` skill, with the skill's name substituted). The installed `MEMORIES.md` is maintained locally; the bundle only provides the starting template (SPEC item 6.8). autotest enforces the file's presence (SPEC item 9.3). ## 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 ` 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 `/.vibe/skills`. - **5.4.3** Skills install as `//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 --install` copies the whole skill directory from the bundle into `harness.global_dir()//`; `--project` copies into `harness.project_dir(cwd)//`. 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 , bundle has . 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 --uninstall` removes the harness target directory `harness.global_dir()//`, 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 (, ) -> `. A missing state entry does not fail the removal. - **6.8** `MEMORIES.md` is add-only on install and update both: copied from the bundle when the target has none, left untouched when it has one, because the file is maintained locally and holds machine-specific entries. `--force` does not change this. - **6.9** Uninstall removes the whole skill directory, and the locally maintained `MEMORIES.md` dies with it; to keep the memory, copy the file out before `--uninstall`. ## 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. - **7.6** `--update` never overwrites an existing `MEMORIES.md`; it adds the template only when the file is missing (SPEC item 6.8). - **7.7** A copy also heals legacy state: a nested `//` directory left inside the skill target by a pre-0.3.0 `--update` that nested its copy is removed on the next install or update of that skill. ## 8. State file - **8.1** The CLI keeps one JSON state file per machine at `/phronesis/installed.json`, where `` 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, checks the SPEC item 4.3 formats on every `skill//SKILL.md`, and fails when a skill directory lacks `MEMORIES.md` (SPEC item 4.7). - **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` 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` 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/-.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//...`), 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` 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).