feat v0.3.0: MEMORIES.md template in every skill, add-only install/update policy

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

Generated by Mistral Vibe.
Co-Authored-By: Mistral Vibe <vibe@mistral.ai>
This commit is contained in:
nvaldez
2026-11-19 11:35:48 +01:00
parent e913d0b67f
commit ed3d21fd54
10 changed files with 829 additions and 17 deletions
+10 -4
View File
@@ -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.
+21 -2
View File
@@ -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
`<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
@@ -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 <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
@@ -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
`<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
@@ -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/<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
+6 -4
View File
@@ -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
View File
@@ -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"
+173
View File
@@ -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
+173
View File
@@ -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
+173
View File
@@ -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
+173
View File
@@ -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
+15 -3
View File
@@ -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)
+84 -3
View File
@@ -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()