diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 750f7bb..6832839 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -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//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 `. +7. Commit with a semantic message, e.g. `feat: add skill `. A new category is announced to users the moment the skill is bundled, since `phronesis` lists it live. diff --git a/SPEC.md b/SPEC.md index 58ee003..ff27558 100644 --- a/SPEC.md +++ b/SPEC.md @@ -175,6 +175,11 @@ python-tdd 1.2.0 development directory path. - **4.6** Every category in use is offered by completion and by the `` 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 @@ -225,6 +230,13 @@ python-tdd 1.2.0 development `(name, harness, scope)` is dropped (SPEC item 8.3), and one line is printed: `removed (, ) -> `. 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 @@ -240,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 + `//` 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 @@ -281,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//SKILL.md`. +- **9.3** `frontmatter` requires the SPEC item 4.2 keys, checks the + SPEC item 4.3 formats on every `skill//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 diff --git a/autotest.py b/autotest.py index 2a692f6..8e4affa 100644 --- a/autotest.py +++ b/autotest.py @@ -138,12 +138,14 @@ def check_frontmatter(path: pathlib.Path) -> int: def check_skills_dir() -> int: - """Every skill// directory must contain a SKILL.md.""" + """Every skill// 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 diff --git a/pyproject.toml b/pyproject.toml index bdcbf66..f9510e2 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta" [project] name = "phronesis" -version = "0.2.0" +version = "0.3.0" description = "A chest of skills: list them, install them into an agent harness (vibe, ...)" readme = "README.md" requires-python = ">=3.11" diff --git a/skill/fiona/MEMORIES.md b/skill/fiona/MEMORIES.md new file mode 100644 index 0000000..41438a7 --- /dev/null +++ b/skill/fiona/MEMORIES.md @@ -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 + + + +- [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) + + + +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: ` + 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 diff --git a/skill/python-tdd/MEMORIES.md b/skill/python-tdd/MEMORIES.md new file mode 100644 index 0000000..a5c4bd4 --- /dev/null +++ b/skill/python-tdd/MEMORIES.md @@ -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 diff --git a/skill/sectionize-markdown/MEMORIES.md b/skill/sectionize-markdown/MEMORIES.md new file mode 100644 index 0000000..b034446 --- /dev/null +++ b/skill/sectionize-markdown/MEMORIES.md @@ -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 diff --git a/skill/specification-writer/MEMORIES.md b/skill/specification-writer/MEMORIES.md new file mode 100644 index 0000000..f07e0b7 --- /dev/null +++ b/skill/specification-writer/MEMORIES.md @@ -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 diff --git a/src/phronesis/cli.py b/src/phronesis/cli.py index d474773..e173522 100644 --- a/src/phronesis/cli.py +++ b/src/phronesis/cli.py @@ -91,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" @@ -181,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) diff --git a/test/test_cli.py b/test/test_cli.py index 0f59e4c..c442c85 100644 --- a/test/test_cli.py +++ b/test/test_cli.py @@ -162,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): @@ -190,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): @@ -296,3 +318,62 @@ def test_uninstall_of_unbundled_name_is_allowed(config, capsys): 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()