Files
phronesis/SPEC.md
T
nvaldez ed3d21fd54 feat v0.3.0: MEMORIES.md template in every skill, add-only install/update policy
- every bundled skill ships MEMORIES.md (memory-skill template, name
  substituted); autotest frontmatter check enforces its presence (SPEC 4.7)
- copy_skill: MEMORIES.md is add-only - installed from the bundle when
  missing, never overwritten, on both install and update; --force does not
  change this (SPEC 4.7, 6.8, 7.6); uninstall removes it with the
  directory (SPEC 6.9, sad by design)
- FIX bug in --update: it passed the skill directory where the skills
  root was expected, copying the bundle into skills/<name>/<name>/ and
  never refreshing the real SKILL.md; now updates the real files and
  heals the legacy nested directory on the next copy (SPEC 7.7)
- tests strengthened to assert file contents, not just output: 84 total,
  all checks green; e2e-verified via the installed pipx CLI

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

19 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

  • 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:
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:
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.
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).
  • 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 <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.
  • 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 <name>/<name>/ 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 <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):
{
  "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/<name>/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<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).