196df53a9b
- SPEC.md sectionized with stable ids (sectionize-markdown conventions) - src/phronesis: cli, registry, harnesses (modular, vibe first), state, formatting, completions; argcomplete completion; exit codes per SPEC - phronesis -> version line + skill table (name, version, category, description wrapped below, daedalus-style) - phronesis <category> -> filtered table; close-match typos for skills+categories - phronesis <skill> --install | --project [--harness <name>] [-f] installs whole skill dir; prompt when present; EOF/default = skip; -f no prompt - phronesis --update -> refresh every state entry; warns unbundled; reinstalls missing - state: <config>/phronesis/installed.json, unique by (name, harness, scope) - skill/python-tdd bumped 1.2.0 with category: development - test/ (56 tests, 92% cov) + autotest pytest check with 75% floor; all 7 autotest checks green Generated by Mistral Vibe. Co-Authored-By: Mistral Vibe <vibe@mistral.ai>
14 KiB
14 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
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
├── autotest.py # Every repo check, single entry point
├── SPEC.md # This file
├── README.md, CONTRIBUTING.md, LICENSE
└── pyproject.toml, requirements.txt
- 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).
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.