0e4fe45bc1
Audit found the spec accurate through the skills port but silent on the release tooling. Added section 12 (publish.py guards and exit codes, roller-tag tolerance, immutable published versions, absolute-link README rule found at 0.1.0, MANIFEST.in and dist/ policy) and refreshed the item 2.1 tree (publish.py, MANIFEST.in, dist/, skill support files). CONTRIBUTING gains a short Releasing section pointing at SPEC 12. Generated by Mistral Vibe. Co-Authored-By: Mistral Vibe <vibe@mistral.ai>
17 KiB
17 KiB
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
- 2. Layout
- 3. Command line
- 4. Skill registry and front matter
- 5. Harnesses
- 6. Install and project
- 7. Update
- 8. State file
- 9. Quality gates
- 10. Packaging
- 11. Implementation plan
- 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.mdinstruction packages. The CLI lists them, and installs them into an agent harness such as Vibe:
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 phronesisthe commandphronesisis onPATHwith 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:
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._skillsmapped to the repository folderskill/(SPEC item 10.3), so the registry resolves the same paths from a checkout and from an installed package (daedalus_librarypattern).
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 --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
--installand--projectare mutually exclusive; using both exits 2. Each needs a skill word; with neither option the call lists. - 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. Theversioncolumn is at least 7 wide. - 3.3.3 One row per skill, sorted by name.
versionis the front matter version,categorythe 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 byESC[0m. Enabled whenNO_COLORis unset or empty and eitherFORCE_COLORis non-empty or stdout is a terminal; a non-emptyNO_COLORwins.
- 3.3.1 First line
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 andinstall: 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/--helpprints 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 phronesisfrom 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
--harnesschoices, and--install,--project,--force,-f. - 3.9
--versionprints the installed distribution version; when the metadata is missing, the version falls back to the checkoutpyproject.toml, elseunknown.
4. Skill registry and front matter
- 4.1 A skill is one directory under
skill/named after the skill, containing a single required fileSKILL.md. Support files may follow later; the whole directory is copied on install. - 4.2
SKILL.mdstarts with a---fenced YAML header with the required keysname,version,description,category. - 4.3
nameequals the directory name;versionisx.y.z;categoryis 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.mdthroughimportlib.resourcesand 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;Skillcarries 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
nameand two locations:global_dir()for the machine-level skill directory, andproject_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
--harnessdefaults tovibe; the default can change when more harnesses arrive, never silently in a patch release. - 5.4 The
vibeharness 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/skillsand project skills in the project's.vibe/skills.
- 5.4.1
- 5.5 A new harness adds one class and one
HARNESS_REGISTRYentry; the CLI, table, tests, and state file do not change.
6. Install and project
- 6.1
phronesis <skill> --installcopies the whole skill directory from the bundle intoharness.global_dir()/<name>/;--projectcopies intoharness.project_dir(cwd)/<name>/. Parent directories are created. - 6.2 When the target
SKILL.mdalready 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
yorYoverwrites 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.2.1 Answering
- 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).
7. Update
- 7.1
phronesis --updateloads 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
--updatealso 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,
--updateprintsnothing installedand 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_HOMEelse~/.configelsewhere.$PHRONESIS_CONFIGoverrides the location wholesale for tests and unusual setups. - 8.2 The file is a JSON object holding a
skillslist; each entry hasname,version,harness,scope,path, andinstalled(an ISO date):
{
"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. Thepathis the absoluteSKILL.mdpath;scopeisglobalorproject. - 8.4 Uninstalling is not part of the CLI; removing the harness
directory and the state entry is the workaround until section 6
grows a
--remove.
9. Quality gates
- 9.1
autotest.pyis 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, andmarkdowncover every script and markdown file in the repository as in the daedalus spec. - 9.3
frontmatterrequires the SPEC item 4.2 keys and checks the SPEC item 4.3 formats on everyskill/<name>/SKILL.md. - 9.4
pytestruns the suite fromtest/in a subprocess with coverage over thephronesispackage and fails under 75 percent. - 9.5
requirements.txtpins the check dependencies and the test dependencies; the runtime dependencies live inpyproject.toml(SPEC item 10.2). - 9.6 The markdown check configures md025's
front_matter_titlesearch with a pattern that never matches, so atitlekey 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 isphronesis = 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 packagephronesis._skillsto the repository folderskill/with every file included, so the registry sees the packaged skills throughimportlib.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.pyfirst: 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.pyandcompletions.py: the table rendering and the completion candidate functions, tested as pure functions. - 11.5
cli.pylast: parser, dispatch, install, and update wiring the parts above; end to end tests throughmain(argv). - 11.6 The implementation order is bottom up so every layer has a test before its consumer exists.
12. Release
- 12.1
publish.pyat the repository root releases the package to PyPI, ported from daedaluspython/src/publish/publish.py: guards, a chained sdist to wheel build,twine check, and with--uploada 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.tomlbeside the script is exit 2; a dirty working tree is exit 3; a HEAD whose tags do not includev<version>is exit 4 with the tags it actually carries printed; missingpython -m buildorpython -m twineis exit 5 with thepipx inject phronesis build twinehint; 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 thestableandlatestroller tags on the same commit never trip it. - 12.4 Build failure is exit 7; a
twine checkcomplaint (for example a README that will not render) is exit 8. Without--uploadthe run ends there with exit 0 and prints the command that would upload. - 12.5
--uploadrunspython -m twine uploadover exactlydist/<name>-<version>.tar.gzand the matching wheel, neverdist/*: 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 targetsrc/branch/masteron the repository server; markdown anchors (#...) stay relative and keep working. - 12.8
MANIFEST.inshipsskill/in the sdist; the wheel carries the skills asphronesis._skillspackage data (SPEC item 10.3);dist/is build output, gitignored, and never committed. - 12.9 Release tags:
v<version>on the release commit, and thestableandlatestroller tags moved onto the same commit (git tag -f ...plusgit push -f origin stable latest). - 12.10 Release tooling dependencies (
build,twine) live inrequirements.txt(SPEC item 9.5); the wheel's runtime dependencies stay minimal (SPEC item 10.2).