@gavin-hu/my-pi-agent 0.17.0 → 0.19.0

package/skills/project-docs/references/discovery.md

@@ -0,0 +1,127 @@
+# Discover the project's documents
+
+A document is a convention before it is a file: which documents exist, what each one
+promises, how a version is spelled, and when an entry is written are all things a
+project chose. Read what it chose. Do not import a template where the project says
+something else, and do not average two sources — when they disagree, ask.
+
+Find these five things, in this order. The first one locates the rest.
+
+## 1. The document set
+
+The documents this skill looks for, in the order it looks, and where a project keeps
+them. A project that has only some of them is normal: the skill maintains what exists,
+and whether to adopt a missing one is the maintainer's decision rather than an edit.
+
+- **The front door** — `README.md` first, then `README.rst`, `README`, or `docs/README.md`.
+  A mirror (`README.zh-CN.md`, `README.ja.md`) is part of the front door, not a
+  separate document: it carries the same sections, table rows, and links.
+- **The plan of record** — `ROADMAP.md`, then `ROADMAP`, `docs/roadmap.md`, a
+  `ROADMAP` section in the front door, or an issue tracker label the project's docs
+  name. A project with none is maintained from the changelog and the tree alone; say so.
+- **The record of what shipped** — `CHANGELOG.md`, then `CHANGELOG`, `CHANGES.md`,
+  `HISTORY.md`, `NEWS.md`, `docs/CHANGELOG.md`, `docs/changelog.md`. The bundled script
+  takes the first name in that order. Several changelogs belonging to several packages
+  are a scope question, not a choice: ask which package is in scope, and never treat one
+  package's file as a copy of another's.
+- **The contributor path** — `CONTRIBUTING.md`, then `.github/CONTRIBUTING.md`,
+  `docs/contributing.md`, and the instruction file the project's agent reads
+  (`AGENTS.md`, `CLAUDE.md`), which usually states the rules the other three obey.
+
+Deep guides (`docs/`, `documentation/`) are where detail belongs. Their existence is
+the reason the front door can stay short: it summarizes and links, and the skill must
+not move a guide's content up into it, or copy the front door's catalog down.
+
+These rules are written in Markdown's vocabulary because most projects write their docs
+in it. Read the format the project actually uses — reStructuredText, AsciiDoc, plain
+text — and fix it in that format: a heading anchor, a link reference, and a fenced
+example are spelled differently in each, and converting a document is not this skill's
+job.
+
+## 2. The version's single source
+
+One file decides the version: `package.json`, `pyproject.toml`, `Cargo.toml`, a
+`VERSION` file, or a `version` module. Everything else repeats it — the newest dated
+changelog heading, a tag, a badge, a lockfile. Read the source and the repeats
+together; a version that disagrees in one place is the most common stale claim a
+release leaves behind.
+
+## 3. The changelog's local conventions
+
+- **Who writes the file** — a preamble that says "generated", a `.changeset/` or
+  `.changes/` directory, a release workflow step that writes the changelog, or a
+  generator named in the manifest or its config: `semantic-release`, `release-please`,
+  `changesets`, `git-cliff`, `goreleaser`, `cargo-release`, `standard-version`. Where a
+  tool owns the file, the entry is written upstream — in the commit message's
+  convention, in a changeset fragment, or in the generator's config — and never by hand.
+- **The preamble** — whether it names Keep a Changelog, Semantic Versioning, a
+  different convention, and whether unreleased entries are kept in the file at all.
+- **The category names and their order** — Keep a Changelog's set is `Added`,
+  `Changed`, `Deprecated`, `Removed`, `Fixed`, `Security`, in that order, and a
+  project may use a subset, add its own, or reorder them. Copy the spelling exactly:
+  `Fix` is not `Fixed`.
+- **The bullet's shape** — read the newest *released* section, not the first one. Note
+  the scope prefix (`- \`core\`: …`, `- [core] …`, or none), whether a bullet may run
+  several sentences, the wrap column, and whether backticks or bold carry the scope.
+- **Whether the entry ships with the change** — `CONTRIBUTING.md`, the instruction
+  file, and a pull-request template say it in one line. Silence is not permission to
+  defer: ask, because a changelog maintained per release is a different procedure.
+- **The release procedure** — a release document outranks everything here:
+  `docs/release.md`, `RELEASING.md`, `CONTRIBUTING.md`'s release section, a
+  `publish.yml` job, or a `release` script in the manifest. Read it for the link-ref
+  update, the tag format, and the push and publish order.
+
+## 4. The roadmap's rules
+
+- **The item form** — how an item is written and whether it carries an id: `**P1 — …**`,
+  `- [ ] …`, `R1: …`, a bare heading. Ids are what a citation elsewhere points at.
+- **The buckets and their caps** — horizon names (`Now` / `Next` / `Later`, or
+  quarters), and any limit the file states on how many items a bucket holds.
+- **The ledger, if there is one** — the table tying a promise in the front door to the
+  items that keep it; a row is open while any of its items are.
+- **What happens to a shipped item** — the stated rule, usually one line: delete it and
+  record the reason, or renumber the rest. Never tick it and leave it, unless the file
+  says to.
+- **The non-goals** — the "deliberately left thin" or "won't do" list, with the reason
+  each carries. Reversing one is a decision, not an edit.
+
+## 5. The check and the guards
+
+The project's check command (`bun run check`, `npm test`, `make check`, a CI workflow)
+is the finish line for any edit. Find the guards on these documents by name, because a
+guard states the rule better than a summary of it: `release.test.ts`,
+`changelog.test.ts`, `docs-parity.test.ts`, `roadmap.test.ts`, a link checker, or a CI
+step that compares a count in the docs with the tree.
+
+Quote a guard's name and what it holds; do not restate its rule. Run the guard
+directly while iterating — a failing guard names the rule you just broke.
+
+## State the profile
+
+Before editing, write one short paragraph: the documents found, the version's source,
+the changelog's categories and scope spelling, the roadmap's item form and caps, the
+check command, and the guards. It is how the user catches a misread in one line
+instead of in a diff. Do not invent a rule the project never stated; ask instead.
+
+## A worked example
+
+When you are in this repository, the answers are already written down:
+
+- `README.md` and `README.zh-CN.md` — the front door and its mirror; `test/docs-parity.test.ts`
+  holds the two to the same headings, table rows, and links.
+- `CHANGELOG.md` — Keep a Changelog preamble, categories in the standard order,
+  `[Unreleased]` kept in the file, scope in backticks followed by a colon.
+- `ROADMAP.md` — items as `**P1 — …**`, `Now` and `Next` capped at ten, a promise
+  ledger, and the rule that a shipped item is deleted with its reason;
+  `test/roadmap.test.ts` pins the ids, links, and caps, and cannot see that an item
+  has shipped.
+- `CONTRIBUTING.md` and `AGENTS.md` — the entry lands in the same commit as the
+  change, and a behavior change also updates the catalog table in both entry READMEs
+  and the relevant guide.
+- `docs/development.md` — the normative release procedure.
+- `test/release.test.ts` — the guard on subsection names, order, emptiness, and the
+  version pin against the newest tag.
+- `bun run check` — the finish line; `bun test test/roadmap.test.ts` for one guard alone.
+
+The paths are named, not linked: a skill is installed into projects that do not
+contain them, so a link would point nowhere from the place it is read.

package/skills/project-docs/references/readme.md

@@ -0,0 +1,80 @@
+# Readme
+
+The front door is the only document a reader is guaranteed to see, so it carries two
+burdens at once: it must be *enough* on its own, and it must not become the manual. This
+mode keeps it true to the tree without letting it grow.
+
+Read [`discovery.md`](./discovery.md) first for the file, its mirror, and the guides it
+links to.
+
+## What belongs on the front door
+
+- What the thing is, in one or two sentences a stranger can act on.
+- Install, and the first command that proves the install worked.
+- The catalog: one row per capability, grouped by what the reader is trying to do.
+- Configuration that a reader must choose before the first run, and where the rest
+  lives.
+- Links onward to the guides, and the license.
+
+What does not belong: a tool's parameter table, an exhaustive options list, an internal
+architecture, or a tutorial. When a row needs three sentences of mechanism, the
+mechanism belongs in a guide and the row links to it — do not copy the guide up, and do
+not let the row become a summary of a summary.
+
+## Rows and counts belong to the tree
+
+Where the project has a catalog of capabilities, each row follows the tree:
+- Every row names something that exists and is spelled the way the code spells it: the
+  tool, the command, the flag, the file. A renamed tool with an unchanged row is a
+  broken promise to the reader who types it.
+- Every count the page states — extensions, tools, skills, themes, formats — is read
+  from the tree. A project with a guard that derives it has the number already: change
+  the tree, or the guard, never the number in the prose.
+- A capability with no row is invisible; a row with no capability is a lie. Both
+  directions, in the same pass.
+
+## Examples must run
+
+Run the quickstart as written, in a clean directory, before editing anything else on the
+page. The first command is the most expensive promise on the page: a broken one costs
+the reader the whole document. Then check the worked example — an import, a
+configuration snippet, a call — against the current surface, and prefer the shortest
+form that still runs.
+
+## The mirror, where the project has one
+
+A translated front door is the same document in another language: the same sections,
+the same table rows in the same order, the same relative links. Prose is translated;
+structure is not. A project with one language has no mirror to check, and adding one is
+not this mode's job. A row added to one and not the other is a finding, and the count on
+both sides is the tree's.
+
+## Screenshots and assets
+
+An image is a claim about a surface. Recapture it when the surface changed — and only
+then, because a stale frame is worse than no frame and a fresh frame is expensive to
+produce. Check that the alt text describes what the frame now shows, that the image is
+referenced by a relative path, and that an image whose feature was removed is deleted
+rather than left unreferenced.
+
+## Report
+
+Say which rows, counts, examples, and images moved, and which claims you could not check
+without running the product. A front door that matches the tree already is a valid
+result; say what you verified — the command you ran, the counts you derived — and stop.
+
+## In this repository
+
+- `README.md` is the front door and `README.zh-CN.md` mirrors it section for section;
+  `test/docs-parity.test.ts` holds the two to the same headings, table rows, and links,
+  and derives the catalog's counts from the tree.
+- `test/extension-load.test.ts` pins every count the pages state — extensions, tools,
+  skills, themes — against what actually loads and ships, and requires a row in both
+  entry READMEs for every packaged skill.
+- `assets/` holds the frames the pages show; `bun run screenshots` recaptures one, and a
+  frame is only recaptured when its surface changed.
+- Deep detail lives in `docs/extensions/<name>.md`, `lib/README.md`, and `docs/`; the
+  front door links there and does not restate them.
+
+The paths are named, not linked: a skill is installed into projects that do not
+contain them, so a link would point nowhere from the place it is read.

package/skills/project-docs/references/release.md

@@ -0,0 +1,84 @@
+# Release
+
+Only when the user asked for a specific version. A release is a promise: a tag, a
+published artifact, and a section of the changelog that says what is in it. The
+project's release document owns the whole procedure; this file adds the changelog
+steps and the order they fit into, not a competing one.
+
+## Before touching the file
+
+1. Read the project's release document — `docs/release.md`, `RELEASING.md`,
+   `CONTRIBUTING.md`'s release section, `.github/workflows/publish.yml`. It decides
+   the files to bump, the tag format, and the push and publish order.
+2. Confirm the version and the reason with the user. Say the reason in SemVer's
+   terms: a fix with no surface change is a patch, an additive surface is a minor, a
+   breaking change is a major — and ask when a project in `0.x` treats minors as the
+   breaking channel, because many do. Never infer a version from the size of the
+   diff and never raise the version in the release without the user's word for it.
+
+## Move the entries
+
+A project that keeps no changelog file — only GitHub or GitLab releases, or release
+notes a tool generates — has nothing to move: say so and stop, and do not create the
+file as part of a release. The rest of this section assumes one exists.
+
+A file a tool generates is moved by that tool, not here: `changeset version`,
+`git-cliff --tag`, `release-please`, `semantic-release`, or whatever the project's
+release document names. In that case this mode's job is to check the result — the
+version, the dated heading, the category order, the link refs — and to report the step
+that is still owed, never to edit the generated file.
+
+- Read `[Unreleased]` and check it is what the release contains: everything since
+  the last tag, nothing that already shipped.
+- Move every entry under `## [X.Y.Z] - YYYY-MM-DD`, categories in the file's own
+  order and spelling, creating only the categories that hold an entry. Keep each
+  bullet's text; a release is a move, not a rewrite.
+- Leave `[Unreleased]` present and empty, unless the file's preamble says it is
+  removed between releases. An empty heading is how the next change knows where to
+  land.
+- Update the link references: `[Unreleased]` now compares from the new tag, and the
+  new version gets a reference in the file's existing style (`compare/vOLD...vNEW`
+  or `releases/tag/vNEW`).
+- Bump the version where the project keeps it — usually one manifest, sometimes a
+  lockfile, a version file, and an install pin. The build manifest and the newest
+  dated heading must agree, or a consistency guard fails.
+- The release commit holds the changelog move, the version bump, and the link refs.
+  No behavior, no new entries, no unrelated docs: a release commit that also changes
+  code cannot be diffed as a release.
+
+## Finish
+
+- Run the project's release guard (often `release.test.ts` or a `changelog` check),
+  then the project's full check. The guard is the one test that names a version, so
+  run it directly while iterating.
+- Then, in the project's order and only with explicit approval for that push: commit,
+  tag (`vX.Y.Z`, annotated where the project does that), push the tag together with
+  the branch — a branch push that lands before its tag races the checkout that
+  asserts they agree — and publish through the project's pipeline, not a local
+  publish.
+- The release body is that section verbatim, heading included. Do not add a summary,
+  a thank-you, or a rewrite of the bullets a reader already has.
+
+## Verify a release you did not cut
+
+A release is a chain of steps, and the last one can sit for hours waiting on a
+pipeline's approval, so checking a tagged version is its own job. It touches no file:
+open the tag, read each of these, and report the line.
+
+- The tag's own manifest — `git show vX.Y.Z:package.json`, or the equivalent — because
+  the publish job proves that before it publishes, not the branch's.
+- The newest dated heading, and the project's release guard where it has one.
+- The link refs: `[Unreleased]` compares from the new tag, and `X.Y.Z` points at it.
+- Whatever the release document bumps in the same commit — an install pin, a version
+  stamped in a guide, a captured image.
+- The release body against the section the project's own tooling prints, never against
+  memory.
+- The publish run itself: a workflow that checks out `vX.Y.Z` publishes the tagged tree
+  whatever ref the dispatch named, so what remains is its environment approval and the
+  registry version after it.
+
+## After
+
+If a shipped change turns out to have no bullet, do not edit the released section.
+Record the gap to the user and add a bullet to `[Unreleased]` for the next release,
+naming the fix; a released section is a record of what was published, not a draft.

package/skills/project-docs/references/roadmap.md

@@ -0,0 +1,93 @@
+# Roadmap
+
+The roadmap is the one document that describes the tree rather than the last release,
+so it goes stale two ways: it keeps what already shipped, and it promises what the
+tree already does differently. This mode re-derives it and deletes what is done. It
+never decides what matters.
+
+Read [`discovery.md`](./discovery.md) first for the file, the item form, the buckets
+and their caps, the ledger, and the stated rule for a shipped item. A file with no ids
+and no buckets is not a defect to fix: it gets the deletion pass below, and no invented
+id scheme.
+
+## Re-derive before editing
+
+```bash
+git log --oneline <last-tag>..HEAD
+```
+
+Use `HEAD`, or the branch the project documents as its default — a project's branch is
+not always `main`. Read the changelog's newest dated heading beside it: the window is
+everything that landed, and the release is what a reader has. A project with no tags has
+no window at all: re-derive from the newest dated heading and the tree instead, and say
+that is what you did. An item is not "shipped" because a branch merged — the tree
+decides whether the promise is met, the maintainer decides whether it shipped.
+
+Then, for every item in the file, open the code it names. Three outcomes:
+
+- **The tree does it.** Delete the item, and record the reason where it was — one line
+  is enough, and it is what stops the same item being re-added next review. A file with
+  its own history or "previous `Now`" section gets the note there instead.
+- **The tree does part of it.** Rewrite the item down to the part still missing. A
+  condensed item is a finding; a deleted one that was not done is a lost promise.
+- **The tree contradicts it** — the approach changed, or the problem was solved another
+  way. Delete it with that reason. Parking it as "still available" describes a tree
+  that no longer exists.
+
+Never tick an item and leave it. A checklist with finished rows is a changelog written
+in the wrong file, and it is what the project's own rule usually forbids.
+
+## Renumber and fix every citation
+
+After a deletion, ids break in four places, and all four move in the same edit:
+
+- The item headings, so a prefix's numbers stay contiguous.
+- Every reference elsewhere in the file — a ledger row, a "if only two things ship"
+  list, a `P1–P3` range whose endpoints both still resolve.
+- Every mention in the guides, the front door, and the instruction file, which is what
+  a stale id breaks first because nothing validates it.
+- The relative links and `path:line` citations the items carry.
+
+Change an id only when a deletion forces it. Renumbering for tidiness loses the
+citations the file's readers already have.
+
+## Keep the buckets honest
+
+- A bucket over the cap the file states is a priority list that stopped being one:
+  demote an item rather than widening the cap.
+- A horizon whose exit condition has been met gets rewritten, not left as decoration.
+- A ledger row whose items have all closed is closed; an open item with no ledger row
+  gets one, or it is not part of a promise.
+
+## Numbers belong to the tree
+
+Any count the file states about the code — modules, extensions, tools, screens — is
+read from the tree, not adjusted by hand. A project that derives it in a guard has the
+count already: run the guard, and change the tree or the guard, never the number. A
+project that does not is a finding for the audit, and the fix is a guard.
+
+## Non-goals are decisions
+
+The non-goal list carries a reason per entry. When the changelog, a discussion, or the
+audit contradicts one, that is a decision for the maintainer: list it, with the
+evidence, and ask. Reversing a documented non-goal is not a roadmap edit, and an item
+that needs one reversed says so in the item.
+
+## Report
+
+Every edit named by the item it touched: deleted, rewritten, renumbered, or cited.
+Then the items that need a decision, one line each. A roadmap whose window changed and
+whose items are all still true is a valid result — say so instead of finding work to
+look thorough.
+
+## In this repository
+
+- `ROADMAP.md` states its own rules under *How items are ordered*: an item is deleted
+  when it ships, never ticked, and `Now` and `Next` hold at most ten.
+- `test/roadmap.test.ts` pins the mechanical half — id uniqueness and contiguity, the
+  links, the citations, and the caps — and cannot tell that an item has shipped, which
+  is why the file states that rule in prose.
+- `AGENTS.md` requires the deletion or renumbering in the same commit as the change.
+
+The paths are named, not linked: a skill is installed into projects that do not
+contain them, so a link would point nowhere from the place it is read.