diff --git a/README.md b/README.md index 1f4b6e4..2ea1562 100644 --- a/README.md +++ b/README.md @@ -62,7 +62,11 @@ 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 | ## Checks @@ -77,7 +81,8 @@ phronesis/ matches the directory, `version` is `x.y.z`, `category` is kebab - **markdown** — markdownlint on every `.md` file, via `pymarkdownlnt` with front-matter support; `md013` (line length) and `md033` (inline - HTML) are ignored + HTML) are ignored, and md025 treats front-matter `title` keys as + headings off, so skills with a `title` plus one `#` stay clean - **pytest** — the suite in `test/` with 75 percent coverage floor Run all checks: diff --git a/SPEC.md b/SPEC.md index eec8d0e..cc1aa0e 100644 --- a/SPEC.md +++ b/SPEC.md @@ -271,6 +271,10 @@ python-tdd 1.2.0 development - **9.5** `requirements.txt` pins the check dependencies and the test dependencies; the runtime dependencies live in `pyproject.toml` (SPEC item 10.2). +- **9.6** The markdown check configures md025's `front_matter_title` + search with a pattern that never matches, so a `title` key in + skill front matter is not an implicit second top-level heading; + a genuine duplicate h1 still fails the check. ## 10. Packaging diff --git a/autotest.py b/autotest.py index 9bd3c09..2a692f6 100644 --- a/autotest.py +++ b/autotest.py @@ -152,6 +152,8 @@ def check_markdown(paths: list[pathlib.Path]) -> int: errors = 0 for path in paths: api = PyMarkdownApi().enable_extension_by_identifier("front-matter") + # a 'title' key in front matter is not an implicit second h1 (SPEC item 9.6) + api.set_string_property("plugins.md025.front_matter_title", "^$") for failure in api.scan_path(str(path)).scan_failures: if failure.rule_id.lower() in MARKDOWN_IGNORE: continue diff --git a/skill/fiona/SKILL.md b/skill/fiona/SKILL.md new file mode 100644 index 0000000..7d8516c --- /dev/null +++ b/skill/fiona/SKILL.md @@ -0,0 +1,1187 @@ +--- +name: fiona +category: productivity +description: Operate an llm-wiki with the fiona-assistant CLI. +author: nvaldez +version: 2.2.0 +updated: 2026-10-14 +--- + +# Fiona + +**F**ocused **I**ntelligence **O**rganizer for **N**otes and **A**nalysis + +You maintain an llm-wiki. The command for that work is +`fiona-assistant`. Page conventions live in +[schema](../../../wiki/schema.md). Markdown rule names are in +[markdown rules](./markdown_rules.md). + +Every paragraph and list item below has its own number. Cite a rule +by that number, for example `section 2.1.3`. + +- [1. Load llm-wiki-mod](#1-load-llm-wiki-mod) +- [2. You own the wiki](#2-you-own-the-wiki) +- [3. Before a command](#3-before-a-command) +- [4. Install](#4-install) +- [5. Which command](#5-which-command) +- [6. wiki](#6-wiki) +- [7. librarian](#7-librarian) +- [8. mdoctor](#8-mdoctor) +- [9. fmlint](#9-fmlint) +- [10. python-ruff](#10-python-ruff) +- [11. json-lint](#11-json-lint) +- [12. git](#12-git) +- [13. How to read a run](#13-how-to-read-a-run) +- [14. Work loop](#14-work-loop) +- [15. Frontmatter](#15-frontmatter) +- [16. Checks with no own command](#16-checks-with-no-own-command) +- [17. Do not call](#17-do-not-call) +- [18. Ingest cycle](#18-ingest-cycle) +- [19. Housekeeping](#19-housekeeping) + +## 1. Load llm-wiki-mod + +**1.1** [llm-wiki-mod](./llm-wiki-mod.md) is a core part of wiki +management: raw sources, the wiki, the schema, and ingest, query, +and lint. + +**1.2** If it is not already in context, read it before any wiki +work. When it is already loaded, do not read it again. + +## 2. You own the wiki + +**2.1** You are responsible for this wiki: what it says, how it is +organized, how pages link, and its history. The `fiona-assistant` +tools own nothing. They do the repeated, mechanical work cheaply, +so your tokens go to reading sources and making judgments. A tool +is a helper you direct, not an authority you defer to. + +- **2.1.1** A clean tool run is evidence, not a verdict. + `wiki sanity` passing means the style, frontmatter, and links are + valid. It does not mean a page is true, current, complete, or in + the right place. Read the pages. +- **2.1.2** Treat tool output as a draft. When a tool gets something + wrong, such as a bad title, a lost table, or the wrong folder, fix + the result within the rules (section 18.4), or re-run it with + better arguments. +- **2.1.3** Decisions stay with you: what a page says, what it links + to, which claims conflict, how confident the page is, and when a + source is too complex for a converter (section 18.3). +- **2.1.4** When no tool fits, do the work yourself. Do not bend a + tool to a job it was not built for, and do not invent flags + (section 17). +- **2.1.5** When a tool fails or misbehaves, tell the user the + command and its output. Do not work around it silently. + +### 2.2. Write reusable scripts + +**2.2.1** When you repeat the same mechanical step and no +`fiona-assistant` command covers it, write a script under +[utils/scripts](../../scripts/map.md) instead of redoing it by hand +each time. Tokens spent once on a script are saved on every later +run, and the next session can reuse it. + +**2.2.2** How to write one: + +- **2.2.2.1** Read the [script map](../../scripts/map.md) first. + Extend an existing script before writing a new one. +- **2.2.2.2** One job per script. Name the file in `snake_case.py`. +- **2.2.2.3** Use the standard library first. A third-party import + must already be installed with `fiona-assistant`, or be approved + by the user. +- **2.2.2.4** Start with a module docstring: purpose, inputs, + outputs, and one example call. Parse arguments with `argparse`, + so `--help` works. +- **2.2.2.5** Take the wiki root as an argument, defaulting to `.`. + Print results on stdout, with `--json` when you will parse them. + Send diagnostics through `logging` to stderr. +- **2.2.2.6** Keep it deterministic. No network access unless that + is the script's job and the user agreed. Never write under `raw/` + or `personal/`. A script that writes files offers `--dry-run`. +- **2.2.2.7** Add a row to the [script map](../../scripts/map.md). + Run `fiona-assistant python-ruff chklint utils/scripts`. Append a + line to `wiki/log.md`. +- **2.2.2.8** When a script proves useful in general, suggest to the + user that it become a `fiona-assistant` command. + +### 2.3. Save after every ingest cycle and housekeeping pass + +**2.3.1** When an ingest cycle ends (section 18.5, with sanity +passing), run: + +```text +fiona-assistant git save --description "ingest : " +``` + +**2.3.2** After a housekeeping pass (lint fixes, index, log, or TOC +updates, page moves, template updates), with sanity passing, read +`git diff` for the files `fiona-assistant git status` lists. + +- **2.3.2.1** **Metadata.** On each added or modified page, + frontmatter matches section 15. `name`, `version`, and `updated` + are set. A page under `wiki/` also has `confidence`, `llm`, + `contested`, and `contradictions`. +- **2.3.2.2** **Integrity.** The body still holds the claims, links, + tables, and index or log entries from before this pass. A lint + fix, a move, or a template merge did not drop or garble them. + +**2.3.3** When a check fails, fix the page and run sanity again. +When you cannot tell whether a page is intact, ask before saving. +Then run: + +```text +fiona-assistant git save --description "housekeeping: " +``` + +**2.3.4** This is a standing instruction. You do not need to ask +each time. It is the step that makes the wiki's history usable: + +- **2.3.4.1** **One source, one commit.** The raw copy, the page, + the index entry, the log line, and every concept or entity page + the source changed land together. `git log` becomes the record of + what entered the wiki, when, and from where. +- **2.3.4.2** **Reviewable.** The user can run `git show` on that + commit and see exactly how one source changed the wiki, and check + your synthesis against it. +- **2.3.4.3** **Recoverable.** A bad refinement can be undone or + restored without losing other work. That only holds when each + cycle is its own commit. Batched or skipped saves mix sources, so + one undo drops unrelated work. +- **2.3.4.4** **Proof behind the log.** `wiki/log.md` says what + happened. The commit holds the before and after state that proves + it. + +**2.3.5** Before either save, run `fiona-assistant git status`. +`save` stages everything in the tree. When it shows changes that are +not from this cycle, ask the user before saving. + +**2.3.6** A housekeeping pass also reads `git diff` and applies the +metadata and integrity checks in section 2.3.2. + +**2.3.7** When sanity fails, fix it first, or ask. + +**2.3.8** A duplicate ingest writes nothing, so `save` refusing a +clean tree is expected. + +**2.3.9** This standing instruction covers `save` only. `snapshot`, +`restore`, `clean`, and `undo` still need the user's request. + +## 3. Before a command + +**3.1** Run from the wiki root, the directory that contains +`fiona-settings.json`, or pass that directory as the argument. + +**3.2** Optional directories default to `.`. The CLI does not search +parent directories for the wiki root. + +**3.3** `librarian toc file *` looks for `fiona-settings.json` in +the current directory, then in subdirectories. + +**3.4** `personal/` is read-only, including the directory itself. +Never create, edit, or delete there. + +**3.5** `raw/` is the archive: you may add a new source file +(section 18.3), but never edit, move, or delete a file already +there. Never point a fixer at either `personal/` or `raw/`. + +**3.6** `librarian` and `mdoctor` also exist as their own console +scripts. Call them through `fiona-assistant` so one binary covers +every tool below. + +**3.7** Human reports go to stdout. Diagnostics go to stderr. Do not +treat stderr warnings as the lint report. + +**3.8** Set `LOG_LEVEL=DEBUG` when a run needs a trace. + +## 4. Install + +**4.1** Install the package: + +```text +python -m pip install fiona-assistant +``` + +**4.2** `fiona-assistant` with no command prints help and exits 0. + +## 5. Which command + +**5.1** Find the question, then run its command. Prefix every row +with `fiona-assistant`. + +| Question | Command | +| --- | --- | +| Maintain the wiki: what needs work? | `housekeeping --json`, then section 19 | +| Is this wiki healthy? | `wiki sanity --json --non-interactive` | +| Markdown style on files I edited? | `mdoctor chklint ` | +| Auto-fix markdown style? | `mdoctor fix ` | +| Missing `name` or `version`? | `fmlint chklint ` | +| JSON settings well formed? | `json-lint chklint ` | +| Python under the wiki? | `python-ruff chklint ` | +| New files or new headings? | `librarian toc` and `librarian toc file` | +| What links to what? | `wiki graph` | +| New source, a URL or a file? | `wiki ingest --json`, then section 18 | +| Ingested pages not refined yet? | `wiki ingest --pending --json` | +| Empty directory, start a wiki? | `wiki init ` | +| Template behind the installed package? | `wiki check-update`, then `wiki update --dry-run` | +| A `*-update` file appeared? | Merge it, section 19.8 | +| Ingest or housekeeping done? | `git save --description TEXT` | + +## 6. wiki + +**6.1** `fiona-assistant wiki` with no subcommand prints help and +exits 1. + +### 6.2. init + +```text +fiona-assistant wiki init [directory] +``` + +**6.2.1** Copies the template, substitutes `2026-11-18` with +today's UTC date, creates a git repo, and commits +`Initial llm-wiki commit`. + +**6.2.2** `.gitignore` starts from the packaged default ignore +patterns and includes `personal/`. An existing `.gitignore` keeps +its lines; missing patterns are appended. + +**6.2.3** Paths matched by those default patterns are not copied. +`personal/` is gitignored. + +**6.2.4** Success stdout: + +```text +Successfully initialized llm-wiki directory at: +``` + +**6.2.5** Refuses, and writes nothing, when any of these already +exist: `AGENTS.md`, `fiona-settings.json`, `wiki/`, `ingest/`, +`README.md`. + +### 6.3. check-update + +```text +fiona-assistant wiki check-update [directory] [--json] +``` + +**6.3.1** The directory must contain `fiona-settings.json`. Exit 0 +whether or not updates exist. + +**6.3.2** Human stdout when current: `Wiki is up to date.` + +**6.3.3** When something differs, the lines that apply: + +```text +Files to update: +Conflicts (owner copy kept): + - ( ->