Files
phronesis/SPEC.md
T
nvaldez b0f07593b5 phronesis v0.3.0: port the four known skills from vibe-wiki - five bundled total
- fiona 2.2.0 (productivity) with its support files (llm-wiki-mod.md, markdown_rules.md)
- memory 1.0.1 (productivity) with MEMORIES.md template; CRLF converted to LF
- sectionize-markdown 1.2.0 (documentation); category added, minor bump
- specification-writer 1.1.0 (documentation); category added, minor bump
- autotest markdown check: md025 front_matter_title set never-matching, so a
  front-matter 'title' key is not an implicit second h1 (SPEC item 9.6)
- README skills table lists all five; all 7 autotest checks green

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

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

  • 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
├── 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._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 --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; 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. 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).

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).

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