Compare commits
6 Commits
| Author | SHA1 | Date | |
|---|---|---|---|
| 51ae214998 | |||
| 0226e33ac7 | |||
| ed3d21fd54 | |||
| e913d0b67f | |||
| 0e4fe45bc1 | |||
| 64373b7b1a |
+20
-4
@@ -19,11 +19,17 @@ reading only that file should be able to follow the skill.
|
||||
---
|
||||
```
|
||||
|
||||
3. Write the instructions below the front matter. Cover identity,
|
||||
3. Add `skill/<name>/MEMORIES.md`: copy the template from
|
||||
[skill/memory/MEMORIES.md](./skill/memory/MEMORIES.md) and
|
||||
substitute the skill's name for `SKILL_NAME`. It is the starting
|
||||
memory the installed skill uses; installs add it when missing and
|
||||
never overwrite it ([SPEC.md items 6.8, 6.9](./SPEC.md)).
|
||||
|
||||
4. Write the instructions below the front matter. Cover identity,
|
||||
rules, workflow, and examples; avoid references that only make
|
||||
sense inside your machine.
|
||||
4. Add the skill to the table in [README.md](./README.md).
|
||||
5. Run the checks. All of them must pass:
|
||||
5. Add the skill to the table in [README.md](./README.md).
|
||||
6. Run the checks. All of them must pass:
|
||||
|
||||
```bash
|
||||
python -m pip install -r requirements.txt
|
||||
@@ -31,7 +37,7 @@ reading only that file should be able to follow the skill.
|
||||
python autotest.py
|
||||
```
|
||||
|
||||
6. Commit with a semantic message, e.g. `feat: add skill <name>`.
|
||||
7. Commit with a semantic message, e.g. `feat: add skill <name>`.
|
||||
A new category is announced to users the moment the skill is
|
||||
bundled, since `phronesis` lists it live.
|
||||
|
||||
@@ -62,6 +68,16 @@ reading only that file should be able to follow the skill.
|
||||
- Plain, imperative sentences. Lists over prose where order matters.
|
||||
- Test what you preach: a TDD skill is itself written cleanly.
|
||||
|
||||
## Releasing
|
||||
|
||||
- Bump `version` in `pyproject.toml`, commit, then tag the release:
|
||||
`git tag -a v<x.y.z> -m "..."` and move the `stable`/`latest`
|
||||
roller tags (`git tag -f ...`, `git push -f origin stable latest`).
|
||||
- `python publish.py` guards, builds, and twine-checks exactly the
|
||||
tagged version; `python publish.py --upload` publishes it
|
||||
([SPEC.md section 12](./SPEC.md)). A published version is
|
||||
immutable: any change, even to the README, is a new version.
|
||||
|
||||
## License
|
||||
|
||||
By contributing you agree your work is released under the
|
||||
|
||||
@@ -23,6 +23,7 @@ phronesis <category> filter the list
|
||||
phronesis <skill> show one skill and an install hint
|
||||
phronesis <skill> --install [--harness <name>] install globally (~/.vibe/skills)
|
||||
phronesis <skill> --project [--harness <name>] install in the project only (.vibe/skills)
|
||||
phronesis <skill> --uninstall remove it again (project scope: add --project)
|
||||
phronesis --update update every installed skill
|
||||
```
|
||||
|
||||
@@ -62,11 +63,12 @@ phronesis/
|
||||
|
||||
| Skill | Version | Category | Purpose |
|
||||
| --- | --- | --- | --- |
|
||||
| [fiona](./skill/fiona/SKILL.md) | 2.2.0 | productivity | Operate an llm-wiki with the fiona-assistant CLI |
|
||||
| [memory](./skill/memory/SKILL.md) | 1.0.1 | productivity | Give a skill its own MEMORIES.md beside its SKILL.md |
|
||||
| [python-tdd](./skill/python-tdd/SKILL.md) | 1.2.0 | development | Minimalist TDD architect for Python work |
|
||||
| [sectionize-markdown](./skill/sectionize-markdown/SKILL.md) | 1.2.0 | documentation | Number headings and list items so each rule can be cited |
|
||||
| [specification-writer](./skill/specification-writer/SKILL.md) | 1.1.0 | documentation | Write structured, maintainable SPEC.md files |
|
||||
| [fiona](https://gitea.nolivaldeziii.com/nvaldez/phronesis/src/branch/master/skill/fiona/SKILL.md) | 2.2.0 | productivity | Operate an llm-wiki with the fiona-assistant CLI |
|
||||
| [linux-server-hardening](https://gitea.nolivaldeziii.com/nvaldez/phronesis/src/branch/master/skill/linux-server-hardening/SKILL.md) | 1.2.0 | security | Numbered checklist to audit, harden, and verify an exposed Debian-family Linux server (SSH, accounts, firewall, fail2ban, updates) |
|
||||
| [memory](https://gitea.nolivaldeziii.com/nvaldez/phronesis/src/branch/master/skill/memory/SKILL.md) | 1.0.1 | productivity | Give a skill its own MEMORIES.md beside its SKILL.md |
|
||||
| [python-tdd](https://gitea.nolivaldeziii.com/nvaldez/phronesis/src/branch/master/skill/python-tdd/SKILL.md) | 1.2.0 | development | Minimalist TDD architect for Python work |
|
||||
| [sectionize-markdown](https://gitea.nolivaldeziii.com/nvaldez/phronesis/src/branch/master/skill/sectionize-markdown/SKILL.md) | 1.2.0 | documentation | Number headings and list items so each rule can be cited |
|
||||
| [specification-writer](https://gitea.nolivaldeziii.com/nvaldez/phronesis/src/branch/master/skill/specification-writer/SKILL.md) | 1.1.0 | documentation | Write structured, maintainable SPEC.md files |
|
||||
|
||||
## Checks
|
||||
|
||||
@@ -96,10 +98,10 @@ python autotest.py frontmatter # only the named checks
|
||||
|
||||
## Adding a skill
|
||||
|
||||
See [CONTRIBUTING.md](./CONTRIBUTING.md). The short version: one
|
||||
See [CONTRIBUTING.md](https://gitea.nolivaldeziii.com/nvaldez/phronesis/src/branch/master/CONTRIBUTING.md). The short version: one
|
||||
directory per skill under `skill/`, everything the agent needs in a
|
||||
single `SKILL.md`, and `python autotest.py` green before you commit.
|
||||
|
||||
## License
|
||||
|
||||
[MIT](./LICENSE)
|
||||
[MIT](https://gitea.nolivaldeziii.com/nvaldez/phronesis/src/branch/master/LICENSE)
|
||||
|
||||
@@ -18,6 +18,7 @@ behavior changes, then change the code and the tests to match.
|
||||
- [9. Quality gates](#9-quality-gates)
|
||||
- [10. Packaging](#10-packaging)
|
||||
- [11. Implementation plan](#11-implementation-plan)
|
||||
- [12. Release](#12-release)
|
||||
|
||||
<!-- toc-end -->
|
||||
|
||||
@@ -70,11 +71,15 @@ phronesis/
|
||||
├── test/ # pytest suite, one module per source module
|
||||
├── skill/ # One directory per skill; ships as package data
|
||||
│ └── <name>/
|
||||
│ └── SKILL.md
|
||||
│ ├── 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
|
||||
├── pyproject.toml, requirements.txt
|
||||
└── dist/ # Build artifacts, gitignored
|
||||
```
|
||||
|
||||
- **2.2** The skills ship through the package as
|
||||
@@ -92,6 +97,7 @@ phronesis/
|
||||
| `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 |
|
||||
@@ -101,9 +107,10 @@ phronesis/
|
||||
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.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.
|
||||
@@ -168,6 +175,11 @@ python-tdd 1.2.0 development
|
||||
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
|
||||
|
||||
@@ -208,6 +220,23 @@ python-tdd 1.2.0 development
|
||||
`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
|
||||
|
||||
@@ -223,6 +252,12 @@ python-tdd 1.2.0 development
|
||||
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
|
||||
|
||||
@@ -253,9 +288,9 @@ python-tdd 1.2.0 development
|
||||
- **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`.
|
||||
- **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
|
||||
|
||||
@@ -264,8 +299,9 @@ python-tdd 1.2.0 development
|
||||
- **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.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
|
||||
@@ -304,3 +340,49 @@ python-tdd 1.2.0 development
|
||||
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).
|
||||
|
||||
+6
-4
@@ -138,12 +138,14 @@ def check_frontmatter(path: pathlib.Path) -> int:
|
||||
|
||||
|
||||
def check_skills_dir() -> int:
|
||||
"""Every skill/<name>/ directory must contain a SKILL.md."""
|
||||
"""Every skill/<name>/ directory must contain SKILL.md and MEMORIES.md."""
|
||||
errors = 0
|
||||
for entry in sorted(SKILL_ROOT.iterdir()) if SKILL_ROOT.is_dir() else []:
|
||||
if entry.is_dir() and not (entry / "SKILL.md").is_file():
|
||||
logger.error(" [FAIL] skill '%s' has no SKILL.md", entry.name)
|
||||
errors += 1
|
||||
if entry.is_dir():
|
||||
for required in ("SKILL.md", "MEMORIES.md"):
|
||||
if not (entry / required).is_file():
|
||||
logger.error(" [FAIL] skill '%s' has no %s", entry.name, required)
|
||||
errors += 1
|
||||
return errors
|
||||
|
||||
|
||||
|
||||
+1
-1
@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
|
||||
|
||||
[project]
|
||||
name = "phronesis"
|
||||
version = "0.1.0"
|
||||
version = "0.4.0"
|
||||
description = "A chest of skills: list them, install them into an agent harness (vibe, ...)"
|
||||
readme = "README.md"
|
||||
requires-python = ">=3.11"
|
||||
|
||||
@@ -0,0 +1,173 @@
|
||||
---
|
||||
name: skill-memories
|
||||
version: 1.0.1
|
||||
title: fiona Memories
|
||||
created: 2026-11-18
|
||||
updated: 2026-11-18
|
||||
type: summary
|
||||
---
|
||||
|
||||
# fiona Memories
|
||||
|
||||
<!-- toc-start: headings 2..6 -->
|
||||
|
||||
- [1. How to use this file](#1-how-to-use-this-file)
|
||||
- [1.1 When to read](#11-when-to-read)
|
||||
- [1.2 When to write](#12-when-to-write)
|
||||
- [1.3 How to write](#13-how-to-write)
|
||||
- [1.4 How the memory evolves](#14-how-the-memory-evolves)
|
||||
- [2. Output and wording](#2-output-and-wording)
|
||||
- [2.1 Style and format](#21-style-and-format)
|
||||
- [2.2 Placement and naming](#22-placement-and-naming)
|
||||
- [3. Inputs and sources](#3-inputs-and-sources)
|
||||
- [3.1 Where inputs come from](#31-where-inputs-come-from)
|
||||
- [3.2 Quirks and parsing](#32-quirks-and-parsing)
|
||||
- [4. Steps and tools](#4-steps-and-tools)
|
||||
- [4.1 Commands and flags](#41-commands-and-flags)
|
||||
- [4.2 Machine and shell](#42-machine-and-shell)
|
||||
- [5. Recurring requests](#5-recurring-requests)
|
||||
- [5.1 Patterns](#51-patterns)
|
||||
|
||||
<!-- toc-end -->
|
||||
|
||||
What users want from the fiona skill, kept across sessions:
|
||||
standing preferences, corrections, repeated request patterns, and
|
||||
facts a run verified while using this skill. Preferences for the
|
||||
whole wiki go to the wiki's `MEMORY.md`. Knowledge from sources goes
|
||||
to pages under `wiki/`.
|
||||
|
||||
## 1. How to use this file
|
||||
|
||||
### 1.1 When to read
|
||||
|
||||
- **1.1.1** Read this file once [the skill](./SKILL.md) is loaded,
|
||||
before its first step of the session. When it is already in
|
||||
context, do not read it again.
|
||||
- **1.1.2** Apply every entry that matches the request.
|
||||
- **1.1.2.1** An entry overrides a default of the skill and an
|
||||
entry of the wiki's `MEMORY.md`, for work done with this skill
|
||||
only.
|
||||
- **1.1.2.2** An entry never overrides the boundaries in the wiki's
|
||||
`AGENTS.md`; when the two conflict, follow the boundary and ask
|
||||
the user.
|
||||
- **1.1.2.3** An entry never changes a tool contract: a command, a
|
||||
flag, or a required frontmatter field.
|
||||
- **1.1.3** Every heading and list item is numbered as
|
||||
[sectionize-markdown](../../skills/sectionize-markdown/SKILL.md)
|
||||
describes. Cite an item as `fiona MEMORIES.md item 2.1.3`; a
|
||||
new item takes the next free number in its subsection.
|
||||
|
||||
### 1.2 When to write
|
||||
|
||||
- **1.2.1** Write an entry when one of these happens while the skill
|
||||
is in use:
|
||||
- **1.2.1.1** The user states a requirement or preference for this
|
||||
skill that outlasts the current request ("always", "never", "from
|
||||
now on", "when you do X").
|
||||
- **1.2.1.2** The user corrects the skill's output or a step it
|
||||
took.
|
||||
- **1.2.1.3** The same kind of request comes for the second time;
|
||||
record the pattern and what the user wanted.
|
||||
- **1.2.1.4** A run verifies a reusable fact about the skill's
|
||||
inputs, hosts, or tools that the skill does not state.
|
||||
- **1.2.1.5** The user explicitly asks you to remember something
|
||||
for this skill.
|
||||
- **1.2.2** Do not write:
|
||||
- **1.2.2.1** One-off values that only apply to the current
|
||||
request.
|
||||
- **1.2.2.2** Passwords, tokens, cookies, personal data, or
|
||||
anything the user asks to keep out.
|
||||
- **1.2.2.3** Preferences that hold for any wiki work; those go to
|
||||
the wiki's `MEMORY.md`.
|
||||
- **1.2.2.4** Facts the skill or a wiki page already states; cite
|
||||
them instead.
|
||||
- **1.2.2.5** Guesses; only what the user said or a run showed.
|
||||
|
||||
### 1.3 How to write
|
||||
|
||||
- **1.3.1** Put the entry under the `###` subsection that fits.
|
||||
- **1.3.1.1** When none fits, add a `###` subsection with the next
|
||||
free number under the matching `##`, or a new `##` category with
|
||||
the next free number.
|
||||
- **1.3.1.2** Never put an entry directly under a `##`; its id
|
||||
would collide with a later subsection.
|
||||
- **1.3.2** Use the knowledge-entry shape of sectionize-markdown
|
||||
section 4: a header line with the source tag and a short title,
|
||||
one child per fact, and a last child with the ref and the date.
|
||||
- **1.3.3** Source tags: `user` (the user said it), `run` (a command
|
||||
or tool run showed it), `source` (a file under `raw/` states it),
|
||||
joined with `+` when several agree.
|
||||
- **1.3.4** The ref says where to check the fact: the user's request
|
||||
and its date, the command and its output line, or a page or raw
|
||||
path.
|
||||
- **1.3.5** Write the entry in the same turn, then tell the user
|
||||
which item was added or changed, for example "Saved to fiona
|
||||
MEMORIES.md item 2.1.1".
|
||||
- **1.3.6** Bump `version` (patch for a changed entry, minor for a
|
||||
new entry or subsection) and set `updated` in the frontmatter on
|
||||
every change.
|
||||
- **1.3.7** Append `- YYYY-MM-DD - fiona memory: <item id> <title>`
|
||||
to `wiki/log.md`, and bump that file too.
|
||||
- **1.3.8** The change lands in the save of the current ingest cycle
|
||||
or housekeeping pass.
|
||||
- **1.3.8.1** With no cycle running, save it on its own with
|
||||
`fiona-assistant git save --description "fiona memory: <item id> <title>"`.
|
||||
|
||||
An entry looks like this:
|
||||
|
||||
```text
|
||||
- **2.1.1** [user] "Reports open with the verdict"
|
||||
- **2.1.1.1** The report starts with pass or fail, then the evidence.
|
||||
- **2.1.1.2** Applies to every run of this skill.
|
||||
- **2.1.1.3** Ref: user request YYYY-MM-DD; added YYYY-MM-DD.
|
||||
```
|
||||
|
||||
### 1.4 How the memory evolves
|
||||
|
||||
- **1.4.1** Before adding an entry, look for a near-duplicate in the
|
||||
same category; extend it instead and keep its id and its earliest
|
||||
date.
|
||||
- **1.4.2** A finding that contradicts an entry becomes its next
|
||||
child, titled `OVERRIDE: ...`, with the new facts and its own ref.
|
||||
- **1.4.3** An entry that no longer applies is marked
|
||||
**Superseded YYYY-MM-DD** with the reason; it is not deleted.
|
||||
- **1.4.4** An entry that held for several uses graduates; mark it
|
||||
**Promoted YYYY-MM-DD** with the target.
|
||||
- **1.4.4.1** A rule for every run of the skill moves into
|
||||
[the skill](./SKILL.md).
|
||||
- **1.4.4.2** A preference that turns out to hold for all wiki
|
||||
work moves to the wiki's `MEMORY.md`.
|
||||
- **1.4.5** Never renumber ids; pages, log lines, and chats may cite
|
||||
them.
|
||||
- **1.4.6** Git is the memory's history: `git log -p MEMORIES.md` in
|
||||
the skill's folder shows when each entry changed and why.
|
||||
|
||||
## 2. Output and wording
|
||||
|
||||
What the skill produces and how it reads.
|
||||
|
||||
### 2.1 Style and format
|
||||
|
||||
### 2.2 Placement and naming
|
||||
|
||||
## 3. Inputs and sources
|
||||
|
||||
What the skill reads and where it comes from.
|
||||
|
||||
### 3.1 Where inputs come from
|
||||
|
||||
### 3.2 Quirks and parsing
|
||||
|
||||
## 4. Steps and tools
|
||||
|
||||
How the skill's commands and the machine behave.
|
||||
|
||||
### 4.1 Commands and flags
|
||||
|
||||
### 4.2 Machine and shell
|
||||
|
||||
## 5. Recurring requests
|
||||
|
||||
Requests that come back, and what the user wanted each time.
|
||||
|
||||
### 5.1 Patterns
|
||||
@@ -0,0 +1,173 @@
|
||||
---
|
||||
name: skill-memories
|
||||
version: 1.0.1
|
||||
title: linux-server-hardening Memories
|
||||
created: 2026-11-19
|
||||
updated: 2026-11-19
|
||||
type: summary
|
||||
---
|
||||
|
||||
# linux-server-hardening Memories
|
||||
|
||||
<!-- toc-start: headings 2..6 -->
|
||||
|
||||
- [1. How to use this file](#1-how-to-use-this-file)
|
||||
- [1.1 When to read](#11-when-to-read)
|
||||
- [1.2 When to write](#12-when-to-write)
|
||||
- [1.3 How to write](#13-how-to-write)
|
||||
- [1.4 How the memory evolves](#14-how-the-memory-evolves)
|
||||
- [2. Output and wording](#2-output-and-wording)
|
||||
- [2.1 Style and format](#21-style-and-format)
|
||||
- [2.2 Placement and naming](#22-placement-and-naming)
|
||||
- [3. Inputs and sources](#3-inputs-and-sources)
|
||||
- [3.1 Where inputs come from](#31-where-inputs-come-from)
|
||||
- [3.2 Quirks and parsing](#32-quirks-and-parsing)
|
||||
- [4. Steps and tools](#4-steps-and-tools)
|
||||
- [4.1 Commands and flags](#41-commands-and-flags)
|
||||
- [4.2 Machine and shell](#42-machine-and-shell)
|
||||
- [5. Recurring requests](#5-recurring-requests)
|
||||
- [5.1 Patterns](#51-patterns)
|
||||
|
||||
<!-- toc-end -->
|
||||
|
||||
What users want from the linux-server-hardening skill, kept across sessions:
|
||||
standing preferences, corrections, repeated request patterns, and
|
||||
facts a run verified while using this skill. Preferences for the
|
||||
whole wiki go to the wiki's `MEMORY.md`. Knowledge from sources goes
|
||||
to pages under `wiki/`.
|
||||
|
||||
## 1. How to use this file
|
||||
|
||||
### 1.1 When to read
|
||||
|
||||
- **1.1.1** Read this file once [the skill](./SKILL.md) is loaded,
|
||||
before its first step of the session. When it is already in
|
||||
context, do not read it again.
|
||||
- **1.1.2** Apply every entry that matches the request.
|
||||
- **1.1.2.1** An entry overrides a default of the skill and an
|
||||
entry of the wiki's `MEMORY.md`, for work done with this skill
|
||||
only.
|
||||
- **1.1.2.2** An entry never overrides the boundaries in the wiki's
|
||||
`AGENTS.md`; when the two conflict, follow the boundary and ask
|
||||
the user.
|
||||
- **1.1.2.3** An entry never changes a tool contract: a command, a
|
||||
flag, or a required frontmatter field.
|
||||
- **1.1.3** Every heading and list item is numbered as
|
||||
[sectionize-markdown](../../skills/sectionize-markdown/SKILL.md)
|
||||
describes. Cite an item as `linux-server-hardening MEMORIES.md item 2.1.3`; a
|
||||
new item takes the next free number in its subsection.
|
||||
|
||||
### 1.2 When to write
|
||||
|
||||
- **1.2.1** Write an entry when one of these happens while the skill
|
||||
is in use:
|
||||
- **1.2.1.1** The user states a requirement or preference for this
|
||||
skill that outlasts the current request ("always", "never", "from
|
||||
now on", "when you do X").
|
||||
- **1.2.1.2** The user corrects the skill's output or a step it
|
||||
took.
|
||||
- **1.2.1.3** The same kind of request comes for the second time;
|
||||
record the pattern and what the user wanted.
|
||||
- **1.2.1.4** A run verifies a reusable fact about the skill's
|
||||
inputs, hosts, or tools that the skill does not state.
|
||||
- **1.2.1.5** The user explicitly asks you to remember something
|
||||
for this skill.
|
||||
- **1.2.2** Do not write:
|
||||
- **1.2.2.1** One-off values that only apply to the current
|
||||
request.
|
||||
- **1.2.2.2** Passwords, tokens, cookies, personal data, or
|
||||
anything the user asks to keep out.
|
||||
- **1.2.2.3** Preferences that hold for any wiki work; those go to
|
||||
the wiki's `MEMORY.md`.
|
||||
- **1.2.2.4** Facts the skill or a wiki page already states; cite
|
||||
them instead.
|
||||
- **1.2.2.5** Guesses; only what the user said or a run showed.
|
||||
|
||||
### 1.3 How to write
|
||||
|
||||
- **1.3.1** Put the entry under the `###` subsection that fits.
|
||||
- **1.3.1.1** When none fits, add a `###` subsection with the next
|
||||
free number under the matching `##`, or a new `##` category with
|
||||
the next free number.
|
||||
- **1.3.1.2** Never put an entry directly under a `##`; its id
|
||||
would collide with a later subsection.
|
||||
- **1.3.2** Use the knowledge-entry shape of sectionize-markdown
|
||||
section 4: a header line with the source tag and a short title,
|
||||
one child per fact, and a last child with the ref and the date.
|
||||
- **1.3.3** Source tags: `user` (the user said it), `run` (a command
|
||||
or tool run showed it), `source` (a file under `raw/` states it),
|
||||
joined with `+` when several agree.
|
||||
- **1.3.4** The ref says where to check the fact: the user's request
|
||||
and its date, the command and its output line, or a page or raw
|
||||
path.
|
||||
- **1.3.5** Write the entry in the same turn, then tell the user
|
||||
which item was added or changed, for example "Saved to linux-server-hardening
|
||||
MEMORIES.md item 2.1.1".
|
||||
- **1.3.6** Bump `version` (patch for a changed entry, minor for a
|
||||
new entry or subsection) and set `updated` in the frontmatter on
|
||||
every change.
|
||||
- **1.3.7** Append `- YYYY-MM-DD - linux-server-hardening memory: <item id> <title>`
|
||||
to `wiki/log.md`, and bump that file too.
|
||||
- **1.3.8** The change lands in the save of the current ingest cycle
|
||||
or housekeeping pass.
|
||||
- **1.3.8.1** With no cycle running, save it on its own with
|
||||
`fiona-assistant git save --description "linux-server-hardening memory: <item id> <title>"`.
|
||||
|
||||
An entry looks like this:
|
||||
|
||||
```text
|
||||
- **2.1.1** [user] "Reports open with the verdict"
|
||||
- **2.1.1.1** The report starts with pass or fail, then the evidence.
|
||||
- **2.1.1.2** Applies to every run of this skill.
|
||||
- **2.1.1.3** Ref: user request YYYY-MM-DD; added YYYY-MM-DD.
|
||||
```
|
||||
|
||||
### 1.4 How the memory evolves
|
||||
|
||||
- **1.4.1** Before adding an entry, look for a near-duplicate in the
|
||||
same category; extend it instead and keep its id and its earliest
|
||||
date.
|
||||
- **1.4.2** A finding that contradicts an entry becomes its next
|
||||
child, titled `OVERRIDE: ...`, with the new facts and its own ref.
|
||||
- **1.4.3** An entry that no longer applies is marked
|
||||
**Superseded YYYY-MM-DD** with the reason; it is not deleted.
|
||||
- **1.4.4** An entry that held for several uses graduates; mark it
|
||||
**Promoted YYYY-MM-DD** with the target.
|
||||
- **1.4.4.1** A rule for every run of the skill moves into
|
||||
[the skill](./SKILL.md).
|
||||
- **1.4.4.2** A preference that turns out to hold for all wiki
|
||||
work moves to the wiki's `MEMORY.md`.
|
||||
- **1.4.5** Never renumber ids; pages, log lines, and chats may cite
|
||||
them.
|
||||
- **1.4.6** Git is the memory's history: `git log -p MEMORIES.md` in
|
||||
the skill's folder shows when each entry changed and why.
|
||||
|
||||
## 2. Output and wording
|
||||
|
||||
What the skill produces and how it reads.
|
||||
|
||||
### 2.1 Style and format
|
||||
|
||||
### 2.2 Placement and naming
|
||||
|
||||
## 3. Inputs and sources
|
||||
|
||||
What the skill reads and where it comes from.
|
||||
|
||||
### 3.1 Where inputs come from
|
||||
|
||||
### 3.2 Quirks and parsing
|
||||
|
||||
## 4. Steps and tools
|
||||
|
||||
How the skill's commands and the machine behave.
|
||||
|
||||
### 4.1 Commands and flags
|
||||
|
||||
### 4.2 Machine and shell
|
||||
|
||||
## 5. Recurring requests
|
||||
|
||||
Requests that come back, and what the user wanted each time.
|
||||
|
||||
### 5.1 Patterns
|
||||
@@ -0,0 +1,215 @@
|
||||
---
|
||||
name: linux-server-hardening
|
||||
version: 1.2.0
|
||||
description: Load this skill when a Linux server needs hardening before or after exposure to a network (Debian or Raspberry Pi homelab) - a numbered, human-followable checklist that audits listeners and accounts, enforces SSH key-only, closes unused accounts, scopes the firewall, sets up fail2ban and automatic security updates, and verifies every change with a real probe.
|
||||
category: security
|
||||
---
|
||||
|
||||
# Linux Server Hardening
|
||||
|
||||
<!-- toc-start: headings 2..6 -->
|
||||
|
||||
- [1. How to use this checklist](#1-how-to-use-this-checklist)
|
||||
- [2. Audit the exposure](#2-audit-the-exposure)
|
||||
- [3. Harden SSH](#3-harden-ssh)
|
||||
- [4. Close unused accounts](#4-close-unused-accounts)
|
||||
- [5. Firewall the ingress](#5-firewall-the-ingress)
|
||||
- [6. Brute force protection](#6-brute-force-protection)
|
||||
- [7. Automatic security updates](#7-automatic-security-updates)
|
||||
- [8. Reduce the listening surface](#8-reduce-the-listening-surface)
|
||||
- [9. Verify and record](#9-verify-and-record)
|
||||
- [10. Memory](#10-memory)
|
||||
|
||||
<!-- toc-end -->
|
||||
|
||||
A hardening checklist for a Debian-family Linux server, written
|
||||
so a human can follow it top to bottom. Every heading and list
|
||||
item has a stable id; cite one as `item 3.4`. Items are facts to
|
||||
hold and gotchas; boxes are steps to do and verify. The ground
|
||||
rule throughout: a probe decides, memory and recollection do not.
|
||||
|
||||
## 1. How to use this checklist
|
||||
|
||||
- **1.1** Work in order 2 to 9: audit first (read-only), then
|
||||
change, then verify. Never batch two changes between probes.
|
||||
- **1.2** The skill assumes a Debian-family host with sudo; adapt
|
||||
names and paths to the distribution in front of you.
|
||||
- **1.3** Before editing any live config, copy it aside:
|
||||
`sudo cp -a <file> /tmp/<file>.bak-$(date +%Y%m%d)`.
|
||||
- **1.4** Edit live config in place; never reconstruct it from a
|
||||
template or memory. Diff against the backup after the edit.
|
||||
- **1.5** Every change gets a recorded one-line undo (the backup
|
||||
path, the prior shell, the old rule set).
|
||||
- **1.6** `sudo` is assumed on every command below; do not run a
|
||||
shell as root.
|
||||
|
||||
## 2. Audit the exposure
|
||||
|
||||
Read-only; change nothing here. Build the picture before touching
|
||||
anything.
|
||||
|
||||
- [ ] **2.1** Inventory the TCP and UDP listeners with their
|
||||
owning processes:
|
||||
`sudo ss -tlnp` and `sudo ss -ulnp`.
|
||||
- [ ] **2.2** For every listener, name the service, why it runs,
|
||||
and who may reach it (public, LAN, loopback). No unexplained
|
||||
listener stays unexplained.
|
||||
- [ ] **2.3** Inventory accounts that can log in:
|
||||
`awk -F: '$7 ~ /(sh|bash)$/ {print $1":"$3}' /etc/passwd`.
|
||||
- [ ] **2.4** Inventory accounts with a usable password:
|
||||
`sudo awk -F: '$2 ~ /^\$/ {print $1}' /etc/shadow`.
|
||||
- [ ] **2.5** Inventory sudo members: `getent group sudo`, and
|
||||
check `authorized_keys` of every human account for content.
|
||||
- [ ] **2.6** Record the firewall state: `sudo ufw status
|
||||
verbose` (or the nftables equivalent).
|
||||
- [ ] **2.7** Record pending updates: `apt list --upgradable
|
||||
2>/dev/null | tail -n +2 | wc -l` and flag the security
|
||||
ones.
|
||||
- **2.8** A listener is not an open port: cross the listener list
|
||||
with the firewall rules. "Open" means reachable from a given
|
||||
source, and only the firewall says which sources those are.
|
||||
|
||||
## 3. Harden SSH
|
||||
|
||||
- **3.1** Keep everything in a drop-in, not the main file:
|
||||
`/etc/ssh/sshd_config.d/10-no-password.conf` (included at the
|
||||
top of `sshd_config` on Debian).
|
||||
- [ ] **3.2** Write the drop-in with:
|
||||
`PasswordAuthentication no`,
|
||||
`KbdInteractiveAuthentication no`,
|
||||
`PermitRootLogin no`, `MaxAuthTries 3`,
|
||||
`X11Forwarding no`, `LoginGraceTime 30`.
|
||||
- [ ] **3.3** Validate before activating:
|
||||
`sudo sshd -t` must print nothing.
|
||||
- [ ] **3.4** Activate gracefully: `sudo systemctl reload ssh`.
|
||||
A reload drops no existing session; a restart can.
|
||||
- [ ] **3.5** Verify the effective config, not the file:
|
||||
`sudo sshd -T | grep -Ei '^(passwordauthentication|
|
||||
kbdinteractiveauthentication|permitrootlogin)'`.
|
||||
- [ ] **3.6** Verify behavior with a live probe:
|
||||
`ssh -o PreferredAuthentications=none -o ConnectTimeout=5
|
||||
localhost` must answer `Permission denied (publickey)`.
|
||||
- **3.7** GOTCHA: if VNC or other services tunnel over SSH
|
||||
(`ssh -L`), `AllowTcpForwarding` must stay `yes`. Turning it
|
||||
off silently kills the tunnels and looks like "server not
|
||||
responding".
|
||||
- **3.8** GOTCHA: `PermitRootLogin without-password` (the
|
||||
default) still allows root login with a key. An empty
|
||||
`/root/.ssh/authorized_keys` saves you today; say `no` anyway.
|
||||
- **3.9** Check the protocol only on museum-grade hosts: SSH
|
||||
protocol 2 is enforced by the software itself on OpenSSH
|
||||
7.6 and later - the `Protocol` directive was removed from
|
||||
the config language and modern sshd cannot speak protocol 1.
|
||||
Verify with `ssh -v` (`Remote protocol version 2.0`). A
|
||||
"force protocol 2" item in a modern guide is a staleness
|
||||
marker for the guide, not a gap in the host.
|
||||
|
||||
## 4. Close unused accounts
|
||||
|
||||
- [ ] **4.1** For each candidate account, verify first that
|
||||
nothing uses it: `ps -eo user,args | grep <name>`, `sudo
|
||||
crontab -l -u <name>`, enabled units, recent logins
|
||||
(`sudo last | grep <name>`).
|
||||
- [ ] **4.2** Lock the password: `sudo passwd -l <name>`.
|
||||
- [ ] **4.3** Set the shell to `/usr/sbin/nologin`:
|
||||
`sudo usermod -s /usr/sbin/nologin <name>`.
|
||||
- [ ] **4.4** Verify: `sudo passwd -S <name>` shows `L`, and
|
||||
`getent passwd <name>` shows the nologin shell.
|
||||
- **4.5** GOTCHA: a password lock does NOT block SSH key login.
|
||||
An account with content in `authorized_keys` stays reachable
|
||||
until its shell is nologin (or the keys are removed).
|
||||
- **4.6** Record the undo: `sudo passwd -u <name>` plus
|
||||
`sudo usermod -s /bin/bash <name>` (or the prior shell).
|
||||
|
||||
## 5. Firewall the ingress
|
||||
|
||||
- [ ] **5.1** Set the policy: `sudo ufw default deny incoming`
|
||||
and `sudo ufw default allow outgoing`.
|
||||
- [ ] **5.2** Add allow rules scoped to a source, never to
|
||||
`Anywhere` without a reason; write a comment per rule:
|
||||
`sudo ufw allow from 192.168.178.0/24 to any port 22 proto
|
||||
tcp comment 'SSH from LAN'`.
|
||||
- [ ] **5.3** If access arrives through a proxy or jump host,
|
||||
allow exactly that one IP for that port.
|
||||
- [ ] **5.4** Enable and verify: `sudo ufw --force enable;
|
||||
sudo ufw status verbose`. The current SSH session must
|
||||
survive the enable; if it does not, you locked yourself
|
||||
out.
|
||||
- **5.5** Cover both stacks: repeat rules for the IPv6 prefixes
|
||||
in use, and note that an ISP global prefix can rotate.
|
||||
|
||||
## 6. Brute force protection
|
||||
|
||||
- [ ] **6.1** Install and enable fail2ban with the sshd jail
|
||||
(Debian default ships it); verify it counts probes:
|
||||
`sudo fail2ban-client status sshd`.
|
||||
- **6.2** GOTCHA: if public access arrives through a stream or
|
||||
reverse proxy, every internet probe reaches sshd with the
|
||||
proxy's IP. A ban can then only hit the proxy - cutting the
|
||||
owner's own public path (a self-DoS an attacker can trigger)
|
||||
while real attacker IPs stay invisible.
|
||||
- [ ] **6.3** In that topology, add the proxy to ignoreip
|
||||
(`/etc/fail2ban/jail.local`, `[DEFAULT]` section:
|
||||
`ignoreip = 127.0.0.1/8 ::1 <proxy-ip>`), reload, and
|
||||
verify with `sudo fail2ban-client get sshd ignoreip`.
|
||||
- **6.4** Per-client banning in that topology belongs on the
|
||||
proxy host, against its own (real-client-IP) logs. Do not
|
||||
pretend it works on the backend box.
|
||||
|
||||
## 7. Automatic security updates
|
||||
|
||||
- [ ] **7.1** Install: `sudo apt-get install -y
|
||||
unattended-upgrades`.
|
||||
- [ ] **7.2** Enable: write `/etc/apt/apt.conf.d/20auto-upgrades`
|
||||
with `APT::Periodic::Update-Package-Lists "1";` and
|
||||
`APT::Periodic::Unattended-Upgrade "1";`.
|
||||
- [ ] **7.3** Verify the timers are enabled:
|
||||
`systemctl is-enabled apt-daily.timer
|
||||
apt-daily-upgrade.timer`.
|
||||
- [ ] **7.4** Verify the origins with `sudo unattended-upgrades
|
||||
--dry-run --debug`: the distribution's security origin must
|
||||
be in the allowed list.
|
||||
- **7.5** GOTCHA: third-party repositories (vendor repos such as
|
||||
the Raspberry Pi Foundation origin) are not in the default
|
||||
allow list and stay manual; re-check `apt list --upgradable`
|
||||
occasionally.
|
||||
|
||||
## 8. Reduce the listening surface
|
||||
|
||||
- [ ] **8.1** For every listener that survived the audit without
|
||||
a reason, disable both the service and its socket:
|
||||
`sudo systemctl disable --now <name>.service <name>.socket`
|
||||
(example: rpcbind, when no NFS or rpc is in use).
|
||||
- [ ] **8.2** Verify the port is gone from `sudo ss -tlnp` and
|
||||
`sudo ss -ulnp`; a socket unit can re-activate a service.
|
||||
- **8.3** Prefer not running a service over filtering it: a
|
||||
disabled service is closed to every source, forever.
|
||||
|
||||
## 9. Verify and record
|
||||
|
||||
- [ ] **9.1** Re-run the probes of section 2; compare listener
|
||||
by listener and rule by rule against the pre-hardening
|
||||
picture.
|
||||
- [ ] **9.2** Test the public path from a real outside leg (a
|
||||
phone on mobile data), not from inside the LAN, and not
|
||||
through a VPN.
|
||||
- **9.3** GOTCHA: consumer VPN exits (verified with Mullvad)
|
||||
silently drop non-web ports; a failed TCP test through such a
|
||||
tunnel says nothing about the port. If a question remains, use
|
||||
`https://check-host.net/check-tcp?host=<ip>:<port>` or a phone
|
||||
on mobile data.
|
||||
- [ ] **9.4** Record what changed and how to undo it on the
|
||||
host's wiki entity page, then save the change set as one
|
||||
commit. A hardening step that is not written down did not
|
||||
happen.
|
||||
|
||||
## 10. Memory
|
||||
|
||||
- **10.1** After loading this skill, read [MEMORIES](./MEMORIES.md)
|
||||
once per session. When it is already in context, do not read it
|
||||
again.
|
||||
- **10.2** Update it whenever an important memory about this skill
|
||||
comes up: a lasting preference, a correction, a repeated
|
||||
request, or a fact a run verified. Also update it whenever the
|
||||
user explicitly asks you to remember something for this skill.
|
||||
Section 1 of that file says how.
|
||||
@@ -0,0 +1,173 @@
|
||||
---
|
||||
name: skill-memories
|
||||
version: 1.0.1
|
||||
title: python-tdd Memories
|
||||
created: 2026-11-18
|
||||
updated: 2026-11-18
|
||||
type: summary
|
||||
---
|
||||
|
||||
# python-tdd Memories
|
||||
|
||||
<!-- toc-start: headings 2..6 -->
|
||||
|
||||
- [1. How to use this file](#1-how-to-use-this-file)
|
||||
- [1.1 When to read](#11-when-to-read)
|
||||
- [1.2 When to write](#12-when-to-write)
|
||||
- [1.3 How to write](#13-how-to-write)
|
||||
- [1.4 How the memory evolves](#14-how-the-memory-evolves)
|
||||
- [2. Output and wording](#2-output-and-wording)
|
||||
- [2.1 Style and format](#21-style-and-format)
|
||||
- [2.2 Placement and naming](#22-placement-and-naming)
|
||||
- [3. Inputs and sources](#3-inputs-and-sources)
|
||||
- [3.1 Where inputs come from](#31-where-inputs-come-from)
|
||||
- [3.2 Quirks and parsing](#32-quirks-and-parsing)
|
||||
- [4. Steps and tools](#4-steps-and-tools)
|
||||
- [4.1 Commands and flags](#41-commands-and-flags)
|
||||
- [4.2 Machine and shell](#42-machine-and-shell)
|
||||
- [5. Recurring requests](#5-recurring-requests)
|
||||
- [5.1 Patterns](#51-patterns)
|
||||
|
||||
<!-- toc-end -->
|
||||
|
||||
What users want from the python-tdd skill, kept across sessions:
|
||||
standing preferences, corrections, repeated request patterns, and
|
||||
facts a run verified while using this skill. Preferences for the
|
||||
whole wiki go to the wiki's `MEMORY.md`. Knowledge from sources goes
|
||||
to pages under `wiki/`.
|
||||
|
||||
## 1. How to use this file
|
||||
|
||||
### 1.1 When to read
|
||||
|
||||
- **1.1.1** Read this file once [the skill](./SKILL.md) is loaded,
|
||||
before its first step of the session. When it is already in
|
||||
context, do not read it again.
|
||||
- **1.1.2** Apply every entry that matches the request.
|
||||
- **1.1.2.1** An entry overrides a default of the skill and an
|
||||
entry of the wiki's `MEMORY.md`, for work done with this skill
|
||||
only.
|
||||
- **1.1.2.2** An entry never overrides the boundaries in the wiki's
|
||||
`AGENTS.md`; when the two conflict, follow the boundary and ask
|
||||
the user.
|
||||
- **1.1.2.3** An entry never changes a tool contract: a command, a
|
||||
flag, or a required frontmatter field.
|
||||
- **1.1.3** Every heading and list item is numbered as
|
||||
[sectionize-markdown](../../skills/sectionize-markdown/SKILL.md)
|
||||
describes. Cite an item as `python-tdd MEMORIES.md item 2.1.3`; a
|
||||
new item takes the next free number in its subsection.
|
||||
|
||||
### 1.2 When to write
|
||||
|
||||
- **1.2.1** Write an entry when one of these happens while the skill
|
||||
is in use:
|
||||
- **1.2.1.1** The user states a requirement or preference for this
|
||||
skill that outlasts the current request ("always", "never", "from
|
||||
now on", "when you do X").
|
||||
- **1.2.1.2** The user corrects the skill's output or a step it
|
||||
took.
|
||||
- **1.2.1.3** The same kind of request comes for the second time;
|
||||
record the pattern and what the user wanted.
|
||||
- **1.2.1.4** A run verifies a reusable fact about the skill's
|
||||
inputs, hosts, or tools that the skill does not state.
|
||||
- **1.2.1.5** The user explicitly asks you to remember something
|
||||
for this skill.
|
||||
- **1.2.2** Do not write:
|
||||
- **1.2.2.1** One-off values that only apply to the current
|
||||
request.
|
||||
- **1.2.2.2** Passwords, tokens, cookies, personal data, or
|
||||
anything the user asks to keep out.
|
||||
- **1.2.2.3** Preferences that hold for any wiki work; those go to
|
||||
the wiki's `MEMORY.md`.
|
||||
- **1.2.2.4** Facts the skill or a wiki page already states; cite
|
||||
them instead.
|
||||
- **1.2.2.5** Guesses; only what the user said or a run showed.
|
||||
|
||||
### 1.3 How to write
|
||||
|
||||
- **1.3.1** Put the entry under the `###` subsection that fits.
|
||||
- **1.3.1.1** When none fits, add a `###` subsection with the next
|
||||
free number under the matching `##`, or a new `##` category with
|
||||
the next free number.
|
||||
- **1.3.1.2** Never put an entry directly under a `##`; its id
|
||||
would collide with a later subsection.
|
||||
- **1.3.2** Use the knowledge-entry shape of sectionize-markdown
|
||||
section 4: a header line with the source tag and a short title,
|
||||
one child per fact, and a last child with the ref and the date.
|
||||
- **1.3.3** Source tags: `user` (the user said it), `run` (a command
|
||||
or tool run showed it), `source` (a file under `raw/` states it),
|
||||
joined with `+` when several agree.
|
||||
- **1.3.4** The ref says where to check the fact: the user's request
|
||||
and its date, the command and its output line, or a page or raw
|
||||
path.
|
||||
- **1.3.5** Write the entry in the same turn, then tell the user
|
||||
which item was added or changed, for example "Saved to python-tdd
|
||||
MEMORIES.md item 2.1.1".
|
||||
- **1.3.6** Bump `version` (patch for a changed entry, minor for a
|
||||
new entry or subsection) and set `updated` in the frontmatter on
|
||||
every change.
|
||||
- **1.3.7** Append `- YYYY-MM-DD - python-tdd memory: <item id> <title>`
|
||||
to `wiki/log.md`, and bump that file too.
|
||||
- **1.3.8** The change lands in the save of the current ingest cycle
|
||||
or housekeeping pass.
|
||||
- **1.3.8.1** With no cycle running, save it on its own with
|
||||
`fiona-assistant git save --description "python-tdd memory: <item id> <title>"`.
|
||||
|
||||
An entry looks like this:
|
||||
|
||||
```text
|
||||
- **2.1.1** [user] "Reports open with the verdict"
|
||||
- **2.1.1.1** The report starts with pass or fail, then the evidence.
|
||||
- **2.1.1.2** Applies to every run of this skill.
|
||||
- **2.1.1.3** Ref: user request YYYY-MM-DD; added YYYY-MM-DD.
|
||||
```
|
||||
|
||||
### 1.4 How the memory evolves
|
||||
|
||||
- **1.4.1** Before adding an entry, look for a near-duplicate in the
|
||||
same category; extend it instead and keep its id and its earliest
|
||||
date.
|
||||
- **1.4.2** A finding that contradicts an entry becomes its next
|
||||
child, titled `OVERRIDE: ...`, with the new facts and its own ref.
|
||||
- **1.4.3** An entry that no longer applies is marked
|
||||
**Superseded YYYY-MM-DD** with the reason; it is not deleted.
|
||||
- **1.4.4** An entry that held for several uses graduates; mark it
|
||||
**Promoted YYYY-MM-DD** with the target.
|
||||
- **1.4.4.1** A rule for every run of the skill moves into
|
||||
[the skill](./SKILL.md).
|
||||
- **1.4.4.2** A preference that turns out to hold for all wiki
|
||||
work moves to the wiki's `MEMORY.md`.
|
||||
- **1.4.5** Never renumber ids; pages, log lines, and chats may cite
|
||||
them.
|
||||
- **1.4.6** Git is the memory's history: `git log -p MEMORIES.md` in
|
||||
the skill's folder shows when each entry changed and why.
|
||||
|
||||
## 2. Output and wording
|
||||
|
||||
What the skill produces and how it reads.
|
||||
|
||||
### 2.1 Style and format
|
||||
|
||||
### 2.2 Placement and naming
|
||||
|
||||
## 3. Inputs and sources
|
||||
|
||||
What the skill reads and where it comes from.
|
||||
|
||||
### 3.1 Where inputs come from
|
||||
|
||||
### 3.2 Quirks and parsing
|
||||
|
||||
## 4. Steps and tools
|
||||
|
||||
How the skill's commands and the machine behave.
|
||||
|
||||
### 4.1 Commands and flags
|
||||
|
||||
### 4.2 Machine and shell
|
||||
|
||||
## 5. Recurring requests
|
||||
|
||||
Requests that come back, and what the user wanted each time.
|
||||
|
||||
### 5.1 Patterns
|
||||
@@ -0,0 +1,173 @@
|
||||
---
|
||||
name: skill-memories
|
||||
version: 1.0.1
|
||||
title: sectionize-markdown Memories
|
||||
created: 2026-11-18
|
||||
updated: 2026-11-18
|
||||
type: summary
|
||||
---
|
||||
|
||||
# sectionize-markdown Memories
|
||||
|
||||
<!-- toc-start: headings 2..6 -->
|
||||
|
||||
- [1. How to use this file](#1-how-to-use-this-file)
|
||||
- [1.1 When to read](#11-when-to-read)
|
||||
- [1.2 When to write](#12-when-to-write)
|
||||
- [1.3 How to write](#13-how-to-write)
|
||||
- [1.4 How the memory evolves](#14-how-the-memory-evolves)
|
||||
- [2. Output and wording](#2-output-and-wording)
|
||||
- [2.1 Style and format](#21-style-and-format)
|
||||
- [2.2 Placement and naming](#22-placement-and-naming)
|
||||
- [3. Inputs and sources](#3-inputs-and-sources)
|
||||
- [3.1 Where inputs come from](#31-where-inputs-come-from)
|
||||
- [3.2 Quirks and parsing](#32-quirks-and-parsing)
|
||||
- [4. Steps and tools](#4-steps-and-tools)
|
||||
- [4.1 Commands and flags](#41-commands-and-flags)
|
||||
- [4.2 Machine and shell](#42-machine-and-shell)
|
||||
- [5. Recurring requests](#5-recurring-requests)
|
||||
- [5.1 Patterns](#51-patterns)
|
||||
|
||||
<!-- toc-end -->
|
||||
|
||||
What users want from the sectionize-markdown skill, kept across sessions:
|
||||
standing preferences, corrections, repeated request patterns, and
|
||||
facts a run verified while using this skill. Preferences for the
|
||||
whole wiki go to the wiki's `MEMORY.md`. Knowledge from sources goes
|
||||
to pages under `wiki/`.
|
||||
|
||||
## 1. How to use this file
|
||||
|
||||
### 1.1 When to read
|
||||
|
||||
- **1.1.1** Read this file once [the skill](./SKILL.md) is loaded,
|
||||
before its first step of the session. When it is already in
|
||||
context, do not read it again.
|
||||
- **1.1.2** Apply every entry that matches the request.
|
||||
- **1.1.2.1** An entry overrides a default of the skill and an
|
||||
entry of the wiki's `MEMORY.md`, for work done with this skill
|
||||
only.
|
||||
- **1.1.2.2** An entry never overrides the boundaries in the wiki's
|
||||
`AGENTS.md`; when the two conflict, follow the boundary and ask
|
||||
the user.
|
||||
- **1.1.2.3** An entry never changes a tool contract: a command, a
|
||||
flag, or a required frontmatter field.
|
||||
- **1.1.3** Every heading and list item is numbered as
|
||||
[sectionize-markdown](../../skills/sectionize-markdown/SKILL.md)
|
||||
describes. Cite an item as `sectionize-markdown MEMORIES.md item 2.1.3`; a
|
||||
new item takes the next free number in its subsection.
|
||||
|
||||
### 1.2 When to write
|
||||
|
||||
- **1.2.1** Write an entry when one of these happens while the skill
|
||||
is in use:
|
||||
- **1.2.1.1** The user states a requirement or preference for this
|
||||
skill that outlasts the current request ("always", "never", "from
|
||||
now on", "when you do X").
|
||||
- **1.2.1.2** The user corrects the skill's output or a step it
|
||||
took.
|
||||
- **1.2.1.3** The same kind of request comes for the second time;
|
||||
record the pattern and what the user wanted.
|
||||
- **1.2.1.4** A run verifies a reusable fact about the skill's
|
||||
inputs, hosts, or tools that the skill does not state.
|
||||
- **1.2.1.5** The user explicitly asks you to remember something
|
||||
for this skill.
|
||||
- **1.2.2** Do not write:
|
||||
- **1.2.2.1** One-off values that only apply to the current
|
||||
request.
|
||||
- **1.2.2.2** Passwords, tokens, cookies, personal data, or
|
||||
anything the user asks to keep out.
|
||||
- **1.2.2.3** Preferences that hold for any wiki work; those go to
|
||||
the wiki's `MEMORY.md`.
|
||||
- **1.2.2.4** Facts the skill or a wiki page already states; cite
|
||||
them instead.
|
||||
- **1.2.2.5** Guesses; only what the user said or a run showed.
|
||||
|
||||
### 1.3 How to write
|
||||
|
||||
- **1.3.1** Put the entry under the `###` subsection that fits.
|
||||
- **1.3.1.1** When none fits, add a `###` subsection with the next
|
||||
free number under the matching `##`, or a new `##` category with
|
||||
the next free number.
|
||||
- **1.3.1.2** Never put an entry directly under a `##`; its id
|
||||
would collide with a later subsection.
|
||||
- **1.3.2** Use the knowledge-entry shape of sectionize-markdown
|
||||
section 4: a header line with the source tag and a short title,
|
||||
one child per fact, and a last child with the ref and the date.
|
||||
- **1.3.3** Source tags: `user` (the user said it), `run` (a command
|
||||
or tool run showed it), `source` (a file under `raw/` states it),
|
||||
joined with `+` when several agree.
|
||||
- **1.3.4** The ref says where to check the fact: the user's request
|
||||
and its date, the command and its output line, or a page or raw
|
||||
path.
|
||||
- **1.3.5** Write the entry in the same turn, then tell the user
|
||||
which item was added or changed, for example "Saved to sectionize-markdown
|
||||
MEMORIES.md item 2.1.1".
|
||||
- **1.3.6** Bump `version` (patch for a changed entry, minor for a
|
||||
new entry or subsection) and set `updated` in the frontmatter on
|
||||
every change.
|
||||
- **1.3.7** Append `- YYYY-MM-DD - sectionize-markdown memory: <item id> <title>`
|
||||
to `wiki/log.md`, and bump that file too.
|
||||
- **1.3.8** The change lands in the save of the current ingest cycle
|
||||
or housekeeping pass.
|
||||
- **1.3.8.1** With no cycle running, save it on its own with
|
||||
`fiona-assistant git save --description "sectionize-markdown memory: <item id> <title>"`.
|
||||
|
||||
An entry looks like this:
|
||||
|
||||
```text
|
||||
- **2.1.1** [user] "Reports open with the verdict"
|
||||
- **2.1.1.1** The report starts with pass or fail, then the evidence.
|
||||
- **2.1.1.2** Applies to every run of this skill.
|
||||
- **2.1.1.3** Ref: user request YYYY-MM-DD; added YYYY-MM-DD.
|
||||
```
|
||||
|
||||
### 1.4 How the memory evolves
|
||||
|
||||
- **1.4.1** Before adding an entry, look for a near-duplicate in the
|
||||
same category; extend it instead and keep its id and its earliest
|
||||
date.
|
||||
- **1.4.2** A finding that contradicts an entry becomes its next
|
||||
child, titled `OVERRIDE: ...`, with the new facts and its own ref.
|
||||
- **1.4.3** An entry that no longer applies is marked
|
||||
**Superseded YYYY-MM-DD** with the reason; it is not deleted.
|
||||
- **1.4.4** An entry that held for several uses graduates; mark it
|
||||
**Promoted YYYY-MM-DD** with the target.
|
||||
- **1.4.4.1** A rule for every run of the skill moves into
|
||||
[the skill](./SKILL.md).
|
||||
- **1.4.4.2** A preference that turns out to hold for all wiki
|
||||
work moves to the wiki's `MEMORY.md`.
|
||||
- **1.4.5** Never renumber ids; pages, log lines, and chats may cite
|
||||
them.
|
||||
- **1.4.6** Git is the memory's history: `git log -p MEMORIES.md` in
|
||||
the skill's folder shows when each entry changed and why.
|
||||
|
||||
## 2. Output and wording
|
||||
|
||||
What the skill produces and how it reads.
|
||||
|
||||
### 2.1 Style and format
|
||||
|
||||
### 2.2 Placement and naming
|
||||
|
||||
## 3. Inputs and sources
|
||||
|
||||
What the skill reads and where it comes from.
|
||||
|
||||
### 3.1 Where inputs come from
|
||||
|
||||
### 3.2 Quirks and parsing
|
||||
|
||||
## 4. Steps and tools
|
||||
|
||||
How the skill's commands and the machine behave.
|
||||
|
||||
### 4.1 Commands and flags
|
||||
|
||||
### 4.2 Machine and shell
|
||||
|
||||
## 5. Recurring requests
|
||||
|
||||
Requests that come back, and what the user wanted each time.
|
||||
|
||||
### 5.1 Patterns
|
||||
@@ -0,0 +1,173 @@
|
||||
---
|
||||
name: skill-memories
|
||||
version: 1.0.1
|
||||
title: specification-writer Memories
|
||||
created: 2026-11-18
|
||||
updated: 2026-11-18
|
||||
type: summary
|
||||
---
|
||||
|
||||
# specification-writer Memories
|
||||
|
||||
<!-- toc-start: headings 2..6 -->
|
||||
|
||||
- [1. How to use this file](#1-how-to-use-this-file)
|
||||
- [1.1 When to read](#11-when-to-read)
|
||||
- [1.2 When to write](#12-when-to-write)
|
||||
- [1.3 How to write](#13-how-to-write)
|
||||
- [1.4 How the memory evolves](#14-how-the-memory-evolves)
|
||||
- [2. Output and wording](#2-output-and-wording)
|
||||
- [2.1 Style and format](#21-style-and-format)
|
||||
- [2.2 Placement and naming](#22-placement-and-naming)
|
||||
- [3. Inputs and sources](#3-inputs-and-sources)
|
||||
- [3.1 Where inputs come from](#31-where-inputs-come-from)
|
||||
- [3.2 Quirks and parsing](#32-quirks-and-parsing)
|
||||
- [4. Steps and tools](#4-steps-and-tools)
|
||||
- [4.1 Commands and flags](#41-commands-and-flags)
|
||||
- [4.2 Machine and shell](#42-machine-and-shell)
|
||||
- [5. Recurring requests](#5-recurring-requests)
|
||||
- [5.1 Patterns](#51-patterns)
|
||||
|
||||
<!-- toc-end -->
|
||||
|
||||
What users want from the specification-writer skill, kept across sessions:
|
||||
standing preferences, corrections, repeated request patterns, and
|
||||
facts a run verified while using this skill. Preferences for the
|
||||
whole wiki go to the wiki's `MEMORY.md`. Knowledge from sources goes
|
||||
to pages under `wiki/`.
|
||||
|
||||
## 1. How to use this file
|
||||
|
||||
### 1.1 When to read
|
||||
|
||||
- **1.1.1** Read this file once [the skill](./SKILL.md) is loaded,
|
||||
before its first step of the session. When it is already in
|
||||
context, do not read it again.
|
||||
- **1.1.2** Apply every entry that matches the request.
|
||||
- **1.1.2.1** An entry overrides a default of the skill and an
|
||||
entry of the wiki's `MEMORY.md`, for work done with this skill
|
||||
only.
|
||||
- **1.1.2.2** An entry never overrides the boundaries in the wiki's
|
||||
`AGENTS.md`; when the two conflict, follow the boundary and ask
|
||||
the user.
|
||||
- **1.1.2.3** An entry never changes a tool contract: a command, a
|
||||
flag, or a required frontmatter field.
|
||||
- **1.1.3** Every heading and list item is numbered as
|
||||
[sectionize-markdown](../../skills/sectionize-markdown/SKILL.md)
|
||||
describes. Cite an item as `specification-writer MEMORIES.md item 2.1.3`; a
|
||||
new item takes the next free number in its subsection.
|
||||
|
||||
### 1.2 When to write
|
||||
|
||||
- **1.2.1** Write an entry when one of these happens while the skill
|
||||
is in use:
|
||||
- **1.2.1.1** The user states a requirement or preference for this
|
||||
skill that outlasts the current request ("always", "never", "from
|
||||
now on", "when you do X").
|
||||
- **1.2.1.2** The user corrects the skill's output or a step it
|
||||
took.
|
||||
- **1.2.1.3** The same kind of request comes for the second time;
|
||||
record the pattern and what the user wanted.
|
||||
- **1.2.1.4** A run verifies a reusable fact about the skill's
|
||||
inputs, hosts, or tools that the skill does not state.
|
||||
- **1.2.1.5** The user explicitly asks you to remember something
|
||||
for this skill.
|
||||
- **1.2.2** Do not write:
|
||||
- **1.2.2.1** One-off values that only apply to the current
|
||||
request.
|
||||
- **1.2.2.2** Passwords, tokens, cookies, personal data, or
|
||||
anything the user asks to keep out.
|
||||
- **1.2.2.3** Preferences that hold for any wiki work; those go to
|
||||
the wiki's `MEMORY.md`.
|
||||
- **1.2.2.4** Facts the skill or a wiki page already states; cite
|
||||
them instead.
|
||||
- **1.2.2.5** Guesses; only what the user said or a run showed.
|
||||
|
||||
### 1.3 How to write
|
||||
|
||||
- **1.3.1** Put the entry under the `###` subsection that fits.
|
||||
- **1.3.1.1** When none fits, add a `###` subsection with the next
|
||||
free number under the matching `##`, or a new `##` category with
|
||||
the next free number.
|
||||
- **1.3.1.2** Never put an entry directly under a `##`; its id
|
||||
would collide with a later subsection.
|
||||
- **1.3.2** Use the knowledge-entry shape of sectionize-markdown
|
||||
section 4: a header line with the source tag and a short title,
|
||||
one child per fact, and a last child with the ref and the date.
|
||||
- **1.3.3** Source tags: `user` (the user said it), `run` (a command
|
||||
or tool run showed it), `source` (a file under `raw/` states it),
|
||||
joined with `+` when several agree.
|
||||
- **1.3.4** The ref says where to check the fact: the user's request
|
||||
and its date, the command and its output line, or a page or raw
|
||||
path.
|
||||
- **1.3.5** Write the entry in the same turn, then tell the user
|
||||
which item was added or changed, for example "Saved to specification-writer
|
||||
MEMORIES.md item 2.1.1".
|
||||
- **1.3.6** Bump `version` (patch for a changed entry, minor for a
|
||||
new entry or subsection) and set `updated` in the frontmatter on
|
||||
every change.
|
||||
- **1.3.7** Append `- YYYY-MM-DD - specification-writer memory: <item id> <title>`
|
||||
to `wiki/log.md`, and bump that file too.
|
||||
- **1.3.8** The change lands in the save of the current ingest cycle
|
||||
or housekeeping pass.
|
||||
- **1.3.8.1** With no cycle running, save it on its own with
|
||||
`fiona-assistant git save --description "specification-writer memory: <item id> <title>"`.
|
||||
|
||||
An entry looks like this:
|
||||
|
||||
```text
|
||||
- **2.1.1** [user] "Reports open with the verdict"
|
||||
- **2.1.1.1** The report starts with pass or fail, then the evidence.
|
||||
- **2.1.1.2** Applies to every run of this skill.
|
||||
- **2.1.1.3** Ref: user request YYYY-MM-DD; added YYYY-MM-DD.
|
||||
```
|
||||
|
||||
### 1.4 How the memory evolves
|
||||
|
||||
- **1.4.1** Before adding an entry, look for a near-duplicate in the
|
||||
same category; extend it instead and keep its id and its earliest
|
||||
date.
|
||||
- **1.4.2** A finding that contradicts an entry becomes its next
|
||||
child, titled `OVERRIDE: ...`, with the new facts and its own ref.
|
||||
- **1.4.3** An entry that no longer applies is marked
|
||||
**Superseded YYYY-MM-DD** with the reason; it is not deleted.
|
||||
- **1.4.4** An entry that held for several uses graduates; mark it
|
||||
**Promoted YYYY-MM-DD** with the target.
|
||||
- **1.4.4.1** A rule for every run of the skill moves into
|
||||
[the skill](./SKILL.md).
|
||||
- **1.4.4.2** A preference that turns out to hold for all wiki
|
||||
work moves to the wiki's `MEMORY.md`.
|
||||
- **1.4.5** Never renumber ids; pages, log lines, and chats may cite
|
||||
them.
|
||||
- **1.4.6** Git is the memory's history: `git log -p MEMORIES.md` in
|
||||
the skill's folder shows when each entry changed and why.
|
||||
|
||||
## 2. Output and wording
|
||||
|
||||
What the skill produces and how it reads.
|
||||
|
||||
### 2.1 Style and format
|
||||
|
||||
### 2.2 Placement and naming
|
||||
|
||||
## 3. Inputs and sources
|
||||
|
||||
What the skill reads and where it comes from.
|
||||
|
||||
### 3.1 Where inputs come from
|
||||
|
||||
### 3.2 Quirks and parsing
|
||||
|
||||
## 4. Steps and tools
|
||||
|
||||
How the skill's commands and the machine behave.
|
||||
|
||||
### 4.1 Commands and flags
|
||||
|
||||
### 4.2 Machine and shell
|
||||
|
||||
## 5. Recurring requests
|
||||
|
||||
Requests that come back, and what the user wanted each time.
|
||||
|
||||
### 5.1 Patterns
|
||||
+63
-6
@@ -24,13 +24,15 @@ from phronesis import version
|
||||
from phronesis.formatting import format_list
|
||||
|
||||
USAGE = ("phronesis [-h] [-l | --list] [--version] [--update] "
|
||||
"[--harness <name>] [<category|skill>] [--install | --project] [-f]")
|
||||
"[--harness <name>] [<category|skill>] [--install | --uninstall] "
|
||||
"[--project] [-f]")
|
||||
|
||||
PARSER_DESCRIPTION = "One CLI, a chest of skills (SPEC.md)."
|
||||
|
||||
PARSER_EPILOG = ("Forms: phronesis lists every skill; phronesis <category> filters "
|
||||
"the list; phronesis <skill> shows one skill; phronesis <skill> "
|
||||
"--install | --project installs it; phronesis --update refreshes "
|
||||
"--install installs it and --uninstall removes it, --project "
|
||||
"scopes either to the project; phronesis --update refreshes "
|
||||
"every installed skill.")
|
||||
|
||||
|
||||
@@ -57,8 +59,10 @@ def build_parser() -> PhronesisParser:
|
||||
help="update every skill recorded in the state file")
|
||||
parser.add_argument("--install", action="store_true",
|
||||
help="install <skill> globally for the harness")
|
||||
parser.add_argument("--uninstall", action="store_true",
|
||||
help="remove <skill> from the harness (global, or the project with --project)")
|
||||
parser.add_argument("--project", action="store_true",
|
||||
help="install <skill> in the project only")
|
||||
help="scope --install or --uninstall to the project only")
|
||||
parser.add_argument("-f", "--force", action="store_true",
|
||||
help="install or update without the confirmation prompt")
|
||||
harness_action = parser.add_argument("--harness", metavar="<name>",
|
||||
@@ -87,11 +91,22 @@ def lookup_skill(name: str) -> registry.Skill:
|
||||
raise UsageError(f"unknown skill {name!r}; {hint}")
|
||||
|
||||
|
||||
MEMORY_FILE = "MEMORIES.md"
|
||||
|
||||
|
||||
def copy_skill(skill: registry.Skill, target_dir: pathlib.Path) -> pathlib.Path:
|
||||
"""Copy the whole bundled skill directory into target_dir/<name> (SPEC item 6.1)."""
|
||||
"""Copy the bundled skill directory; the memory file is add-only (SPEC item 6.8)."""
|
||||
destination = target_dir / skill.name
|
||||
target_dir.mkdir(parents=True, exist_ok=True)
|
||||
shutil.copytree(skill.source_dir, destination, dirs_exist_ok=True)
|
||||
shutil.copytree(skill.source_dir, destination, dirs_exist_ok=True,
|
||||
ignore=shutil.ignore_patterns(MEMORY_FILE))
|
||||
memories = destination / MEMORY_FILE
|
||||
bundled_memories = skill.source_dir / MEMORY_FILE
|
||||
if not memories.is_file() and bundled_memories.is_file():
|
||||
shutil.copy2(bundled_memories, memories)
|
||||
legacy = destination / skill.name # nested copy from a pre-0.3.0 --update
|
||||
if legacy.is_dir():
|
||||
shutil.rmtree(legacy)
|
||||
return destination / "SKILL.md"
|
||||
|
||||
|
||||
@@ -132,6 +147,38 @@ def install_skill(skill: registry.Skill, harness: harnesses.Harness, scope: str,
|
||||
return 0
|
||||
|
||||
|
||||
def uninstall_skill(name: str, harness: harnesses.Harness, scope: str) -> int:
|
||||
"""Remove one installed skill, with a skill-directory safety guard (SPEC item 6.6)."""
|
||||
if scope == "global":
|
||||
target_dir = harness.global_dir()
|
||||
else:
|
||||
target_dir = harness.project_dir(pathlib.Path.cwd())
|
||||
target = target_dir / name
|
||||
skill_md = target / "SKILL.md"
|
||||
if not skill_md.is_file():
|
||||
raise UsageError(f"{name!r} is not installed for {harness.name} "
|
||||
f"in {scope} scope; nothing to remove")
|
||||
try:
|
||||
data = registry.parse_frontmatter(skill_md.read_text(encoding="utf-8"),
|
||||
origin=str(skill_md))
|
||||
except registry.RegistryError as error:
|
||||
raise UsageError(f"refusing to remove {target}: {error}") from error
|
||||
if str(data["name"]) != name:
|
||||
raise UsageError(f"refusing to remove {target}: its SKILL.md name "
|
||||
f"{data['name']!r} does not match the directory")
|
||||
shutil.rmtree(target)
|
||||
path = state.state_path()
|
||||
entries = state.load(path)
|
||||
kept = [entry for entry in entries
|
||||
if (entry.get("name"), entry.get("harness"), entry.get("scope"))
|
||||
!= (name, harness.name, scope)]
|
||||
if len(kept) != len(entries):
|
||||
state.save(kept, path)
|
||||
print(f"removed {name} {data['version']} ({harness.name}, {scope}) "
|
||||
f"-> {skill_md}")
|
||||
return 0
|
||||
|
||||
|
||||
def update_all() -> int:
|
||||
"""Update every installed skill from the state file (SPEC section 7)."""
|
||||
path = state.state_path()
|
||||
@@ -145,7 +192,8 @@ def update_all() -> int:
|
||||
print(f"phronesis: skill {entry['name']!r} is no longer bundled; kept as is",
|
||||
file=sys.stderr)
|
||||
continue
|
||||
copy_skill(skill, pathlib.Path(entry["path"]).parent)
|
||||
# path is <skills root>/<name>/SKILL.md: the root is two levels up
|
||||
copy_skill(skill, pathlib.Path(entry["path"]).parent.parent)
|
||||
print(f"updated {skill.name} {entry['version']} -> {skill.version} "
|
||||
f"({entry['harness']}, {entry['scope']})")
|
||||
state.refresh_version(entries, entry, skill.version)
|
||||
@@ -167,6 +215,15 @@ def dispatch(parsed: argparse.Namespace) -> int:
|
||||
return update_all()
|
||||
if parsed.install and parsed.project:
|
||||
raise UsageError("pick one of --install or --project, not both")
|
||||
if parsed.install and parsed.uninstall:
|
||||
raise UsageError("pick one of --install or --uninstall, not both")
|
||||
if parsed.uninstall:
|
||||
if len(parsed.words) != 1:
|
||||
raise UsageError("usage: phronesis <skill> --uninstall [--project] "
|
||||
"[--harness <name>]")
|
||||
scope = "project" if parsed.project else "global"
|
||||
harness = harnesses.lookup(parsed.harness)
|
||||
return uninstall_skill(parsed.words[0], harness, scope)
|
||||
if parsed.install or parsed.project:
|
||||
if len(parsed.words) != 1:
|
||||
raise UsageError("usage: phronesis <skill> --install | --project [-f] "
|
||||
|
||||
+167
-3
@@ -1,10 +1,12 @@
|
||||
"""CLI tests: list, filter, install, prompt, force, and update (SPEC sections 3, 6, 7)."""
|
||||
import json
|
||||
import shutil
|
||||
|
||||
import pytest
|
||||
|
||||
from phronesis import cli
|
||||
from phronesis import harnesses
|
||||
from phronesis import registry
|
||||
from phronesis import state
|
||||
|
||||
|
||||
@@ -160,14 +162,34 @@ def test_short_force_flag_matches_long(config, capsys):
|
||||
|
||||
def test_update_refreshes_installed_skills(config, capsys):
|
||||
path = state.state_path()
|
||||
skills_root = config.parent / "home" / ".vibe" / "skills"
|
||||
state.save([{"name": "python-tdd", "version": "1.0.0", "harness": "vibe",
|
||||
"scope": "global",
|
||||
"path": str(config.parent / "home" / ".vibe" / "skills" / "python-tdd" / "SKILL.md"),
|
||||
"path": str(skills_root / "python-tdd" / "SKILL.md"),
|
||||
"installed": "2026-01-01"}], path)
|
||||
code, out, _ = run(capsys, "--update")
|
||||
(skills_root / "python-tdd").mkdir(parents=True)
|
||||
(skills_root / "python-tdd" / "SKILL.md").write_text("-old one-\n",
|
||||
encoding="utf-8")
|
||||
code, out, err = run(capsys, "--update")
|
||||
assert code == 0
|
||||
assert "1.0.0 -> 1.2.0" in out
|
||||
assert state.load(path)[0]["version"] == "1.2.0"
|
||||
installed = (skills_root / "python-tdd" / "SKILL.md").read_text(
|
||||
encoding="utf-8")
|
||||
assert "-old one-" not in installed
|
||||
assert installed == registry.SKILLS["python-tdd"].skill_md.read_text(
|
||||
encoding="utf-8")
|
||||
|
||||
|
||||
def test_update_heals_a_legacy_nested_copy(config, capsys):
|
||||
skills_root = config.parent / "home" / ".vibe" / "skills"
|
||||
run(capsys, "python-tdd", "--install")
|
||||
legacy = skills_root / "python-tdd" / "python-tdd"
|
||||
shutil.copytree(registry.SKILLS["python-tdd"].source_dir, legacy)
|
||||
code, _, _ = run(capsys, "--update")
|
||||
assert code == 0
|
||||
assert not legacy.exists()
|
||||
assert (skills_root / "python-tdd" / "SKILL.md").is_file()
|
||||
|
||||
|
||||
def test_update_nothing_installed(config, capsys):
|
||||
@@ -188,13 +210,15 @@ def test_update_warns_for_unbundled_skill(config, capsys):
|
||||
|
||||
def test_update_reinstalls_a_missing_target(config, capsys, tmp_path):
|
||||
path = state.state_path()
|
||||
skills_root = config.parent / "home" / ".vibe" / "skills"
|
||||
state.save([{"name": "python-tdd", "version": "1.1.0", "harness": "vibe",
|
||||
"scope": "global",
|
||||
"path": str(config.parent / "home" / ".vibe" / "skills" / "python-tdd" / "SKILL.md"),
|
||||
"path": str(skills_root / "python-tdd" / "SKILL.md"),
|
||||
"installed": "2026-01-01"}], path)
|
||||
code, out, _ = run(capsys, "--update")
|
||||
assert code == 0
|
||||
assert "1.1.0 -> 1.2.0" in out
|
||||
assert (skills_root / "python-tdd" / "SKILL.md").is_file()
|
||||
|
||||
|
||||
def test_state_entries_unique_by_scope(config, capsys, tmp_path, monkeypatch):
|
||||
@@ -213,3 +237,143 @@ def test_installed_json_is_plain_json(config, capsys):
|
||||
assert set(data) == {"skills"}
|
||||
assert set(data["skills"][0]) == {"name", "version", "harness", "scope",
|
||||
"path", "installed"}
|
||||
|
||||
|
||||
# --- uninstall (SPEC items 6.6, 6.7, 8.4)
|
||||
|
||||
|
||||
def test_uninstall_removes_skill_and_state(config, capsys):
|
||||
run(capsys, "python-tdd", "--install")
|
||||
target = config.parent / "home" / ".vibe" / "skills" / "python-tdd"
|
||||
code, out, _ = run(capsys, "python-tdd", "--uninstall")
|
||||
assert code == 0
|
||||
assert "removed python-tdd 1.2.0 (vibe, global)" in out
|
||||
assert not target.exists()
|
||||
assert state.load(state.state_path()) == []
|
||||
|
||||
|
||||
def test_uninstall_project_scoped(config, capsys, tmp_path, monkeypatch):
|
||||
work = tmp_path / "work"
|
||||
work.mkdir()
|
||||
monkeypatch.chdir(work)
|
||||
run(capsys, "python-tdd", "--project")
|
||||
code, _, _ = run(capsys, "python-tdd", "--uninstall", "--project")
|
||||
assert code == 0
|
||||
assert not (work / ".vibe" / "skills" / "python-tdd").exists()
|
||||
assert state.load(state.state_path()) == []
|
||||
|
||||
|
||||
def test_uninstall_needs_the_skill_installed(config, capsys):
|
||||
code, _, err = run(capsys, "python-tdd", "--uninstall")
|
||||
assert code == 2
|
||||
assert "not installed" in err
|
||||
|
||||
|
||||
def test_uninstall_refuses_a_non_skill_directory(config, capsys):
|
||||
target = config.parent / "home" / ".vibe" / "skills" / "not-a-skill"
|
||||
target.mkdir(parents=True)
|
||||
(target / "SKILL.md").write_text("random notes, no front matter",
|
||||
encoding="utf-8")
|
||||
code, _, err = run(capsys, "not-a-skill", "--uninstall")
|
||||
assert code == 2
|
||||
assert "refusing to remove" in err
|
||||
assert (target / "SKILL.md").is_file()
|
||||
|
||||
|
||||
def test_uninstall_refuses_a_name_mismatch(config, capsys):
|
||||
skill_md_run = run(capsys, "python-tdd", "--install")
|
||||
target_dir = config.parent / "home" / ".vibe" / "skills" / "python-tdd"
|
||||
other = target_dir.parent / "other-name"
|
||||
other.mkdir()
|
||||
shutil.copytree(target_dir, other, dirs_exist_ok=True)
|
||||
code, _, err = run(capsys, "other-name", "--uninstall")
|
||||
assert code == 2
|
||||
assert "does not match the directory" in err
|
||||
assert (other / "SKILL.md").is_file()
|
||||
|
||||
|
||||
def test_uninstall_works_without_a_state_entry(config, capsys):
|
||||
target = config.parent / "home" / ".vibe" / "skills" / "python-tdd"
|
||||
target.mkdir(parents=True)
|
||||
body = registry.SKILLS["python-tdd"].skill_md.read_text(encoding="utf-8")
|
||||
(target / "SKILL.md").write_text(body, encoding="utf-8")
|
||||
code, out, _ = run(capsys, "python-tdd", "--uninstall")
|
||||
assert code == 0
|
||||
assert "removed" in out
|
||||
assert not target.exists()
|
||||
|
||||
|
||||
def test_install_and_uninstall_are_exclusive(config, capsys):
|
||||
code, _, err = run(capsys, "python-tdd", "--install", "--uninstall")
|
||||
assert code == 2
|
||||
assert "pick one of --install or --uninstall" in err
|
||||
|
||||
|
||||
def test_uninstall_of_unbundled_name_is_allowed(config, capsys):
|
||||
target = config.parent / "home" / ".vibe" / "skills" / "retired-skill"
|
||||
target.mkdir(parents=True)
|
||||
(target / "SKILL.md").write_text(
|
||||
"---\nname: retired-skill\nversion: 0.9.0\ndescription: gone\n"
|
||||
"category: misc\n---\n", encoding="utf-8")
|
||||
code, out, _ = run(capsys, "retired-skill", "--uninstall")
|
||||
assert code == 0
|
||||
assert not target.exists()
|
||||
|
||||
|
||||
# --- MEMORIES.md is add-only (SPEC items 4.7, 6.8, 6.9, 7.6)
|
||||
|
||||
|
||||
def test_every_bundled_skill_ships_a_memory_template():
|
||||
for name, skill in registry.SKILLS.items():
|
||||
assert (skill.source_dir / "MEMORIES.md").is_file(), name
|
||||
|
||||
|
||||
def test_install_adds_the_memory_template(config, capsys):
|
||||
run(capsys, "python-tdd", "--install")
|
||||
memories = (config.parent / "home" / ".vibe" / "skills" / "python-tdd"
|
||||
/ "MEMORIES.md")
|
||||
assert memories.is_file()
|
||||
assert "python-tdd Memories" in memories.read_text(encoding="utf-8")
|
||||
|
||||
|
||||
def test_reinstall_preserves_a_locally_edited_memory(config, capsys):
|
||||
run(capsys, "python-tdd", "--install")
|
||||
memories = (config.parent / "home" / ".vibe" / "skills" / "python-tdd"
|
||||
/ "MEMORIES.md")
|
||||
memories.write_text("my precious local notes\n", encoding="utf-8")
|
||||
code, _, _ = run(capsys, "python-tdd", "--install", "--force")
|
||||
assert code == 0
|
||||
assert memories.read_text(encoding="utf-8") == "my precious local notes\n"
|
||||
|
||||
|
||||
def test_update_preserves_a_locally_edited_memory(config, capsys):
|
||||
run(capsys, "python-tdd", "--install")
|
||||
memories = (config.parent / "home" / ".vibe" / "skills" / "python-tdd"
|
||||
/ "MEMORIES.md")
|
||||
memories.write_text("keep me\n", encoding="utf-8")
|
||||
state_path = state.state_path()
|
||||
entries = state.load(state_path)
|
||||
entries[0]["version"] = "1.0.0"
|
||||
state.save(entries, state_path)
|
||||
run(capsys, "--update")
|
||||
assert memories.read_text(encoding="utf-8") == "keep me\n"
|
||||
assert state.load(state_path)[0]["version"] == "1.2.0"
|
||||
|
||||
|
||||
def test_update_adds_a_missing_memory_file(config, capsys):
|
||||
run(capsys, "python-tdd", "--install")
|
||||
memories = (config.parent / "home" / ".vibe" / "skills" / "python-tdd"
|
||||
/ "MEMORIES.md")
|
||||
memories.unlink()
|
||||
run(capsys, "--update")
|
||||
assert memories.is_file()
|
||||
assert "python-tdd Memories" in memories.read_text(encoding="utf-8")
|
||||
|
||||
|
||||
def test_uninstall_takes_the_memory_with_it(config, capsys):
|
||||
run(capsys, "python-tdd", "--install")
|
||||
memories = (config.parent / "home" / ".vibe" / "skills" / "python-tdd"
|
||||
/ "MEMORIES.md")
|
||||
assert memories.is_file()
|
||||
run(capsys, "python-tdd", "--uninstall")
|
||||
assert not memories.exists()
|
||||
|
||||
@@ -42,10 +42,24 @@ def test_skills_loads_the_bundled_python_tdd():
|
||||
assert (skill.source_dir / "SKILL.md").is_file()
|
||||
|
||||
|
||||
def test_skills_loads_the_bundled_linux_server_hardening():
|
||||
assert "linux-server-hardening" in registry.SKILLS
|
||||
skill = registry.SKILLS["linux-server-hardening"]
|
||||
assert skill.version == "1.2.0"
|
||||
assert skill.category == "security"
|
||||
assert skill.description
|
||||
assert (skill.source_dir / "SKILL.md").is_file()
|
||||
assert (skill.source_dir / "MEMORIES.md").is_file()
|
||||
|
||||
|
||||
def test_categories_list_the_packed_skills():
|
||||
assert "python-tdd" in registry.CATEGORIES[registry.SKILLS["python-tdd"].category]
|
||||
assert "linux-server-hardening" in registry.CATEGORIES["security"]
|
||||
|
||||
|
||||
def test_skills_in_category_filters_by_label():
|
||||
assert registry.skills_in_category("development") == {"python-tdd": registry.SKILLS["python-tdd"]}
|
||||
assert registry.skills_in_category("security") == {
|
||||
"linux-server-hardening": registry.SKILLS["linux-server-hardening"],
|
||||
}
|
||||
assert registry.skills_in_category("nonesuch") == {}
|
||||
|
||||
Reference in New Issue
Block a user