Commit Graph
4 Commits
Author SHA1 Message Date
Willie c60bb23ba7 docs: tell Codex what to review and fix findings by class
Codex reviews often took four to six rounds because each round found
one more place where the same bug class was unhandled, and it re-raised
cases outside the supported workflows that only our internal wiki ruled
out. AGENTS.md now carries code review rules Codex reads: supported
scope, one finding per bug class with every location, and re-reviews
limited to new commits. The pull request workflow now fixes every
instance of a confirmed class at once and, after three rounds, explains
why findings keep coming instead of only stopping.
2026-10-16 11:00:13 +08:00
Willie fc1785673b docs: review-round limits and move-skill proposal (#510) (#516)
* docs(wiki): cap Codex review rounds and require a state matrix before review

PR #513 reached 7+ Codex rounds because each round surfaced one more
state dimension (project mode, tracked installs, followed links, legacy
keys, lock pins) that the change had never listed. Every round costs the
maintainer a review cycle.

Require a state matrix and a consumer sweep before the first review,
separate findings worth code from unrealistic combinations, and stop at
three rounds unless a finding shows data loss or a broken supported
workflow.

* docs(proposals): add move installed skill proposal for #510

Moving an installed skill with mv strands its install record, and the
documented workaround (uninstall + install --into) re-downloads and
drops audit acceptances and lock pins. Propose one explicit move
operation shared by the CLI, the Web API and the dashboard.

Records the maintainer decisions: no auto-sync, followed links refused,
target filters warn only, whole-folder move in v1, --force limited to
name collisions.

* fix(proposals): cover nested skills, bare tracked checkouts and duplicate destinations

Codex review of the move proposal found three gaps in the folder-move
design:

- A skill directory that contains nested skills was planned as one
  skill, so descendants would move on disk but keep their old records,
  pins and audit acceptances. Plan now expands descendants too.
- Refusals were derived from discovered skills only, so a tracked
  checkout with no discoverable skill would move along with its folder.
  Preflight now walks the whole tree for checkouts and links.
- Two inputs converging on one destination path were treated as a
  forceable flat-name collision and left the batch half-moved. They are
  now a separate, non-forceable duplicate_dest refusal.

* fix(proposals): keep nested records through reconcile, warn both filter directions, refuse overlapping roots

Second Codex round on the move proposal found three more gaps:

- The reconcile walk stops at an installed parent and then prunes every
  record it did not see, so a moved nested skill would lose its record
  and audit acceptances. Reconcile must keep records below a live
  installed record.
- Target filter warnings only covered rules that stop matching. A move
  into a folder that an exclude pattern covers (or an include newly
  adds) changes sync output too, so compare the effective filter result
  before and after.
- Batches such as `move foo foo/sub archive` planned the same subtree
  twice. Overlapping source roots are now refused before any rename.
2026-10-10 23:36:33 +08:00
Willie ad7a518420 docs(wiki): follow Codex's first review right after opening a PR
The polling instructions read as applying only after an `@codex review`
comment, so an agent could open a pull request and hand Codex's initial
findings back to the user instead of following them up itself.
2026-10-04 22:19:22 +08:00
Willie 3ba95ef49e feat(plugin): add npm packages from pi.dev through Pi (#363)
* chore(design): export dashboard tokens for design tools

Mockup tools read a design system's tokens.json rather than our CSS, so
designs drifted from the dashboard's Clean theme. The script derives the
tokens from components.css, and CI runs its test so a new color
variable without a usage note fails instead of silently going missing.

* feat(plugin): add npm packages from pi.dev through Pi

Pi packages on pi.dev are npm packages, which Plugins could not add:
it only took local or Git sources, so users had to install them with Pi
and import them. `plugin add npm:<package>` now hands them to
`pi install` for Pi targets and records the binding like an import.

Skillshare can't fetch or review an npm package, and Pi runs its install
scripts, so the preview says so, discover refuses npm sources, and only
targets that run pi itself take them. Pi keeps one entry per package
name, so another version replaces it in place and keeps its extension
filters; Skillshare records the new entry so a reinstall restores them,
and refuses a package another Skillshare package already manages, since
removing one would remove both. Pinned versions are skipped on update
because pi update keeps them.

The dashboard accepts npm sources, a pasted `pi install` command or a
pi.dev address, lists only Pi targets, and the Pi Extensions tab links
to adding a package with that target selected. Pi packages show Pi's
mark in the plugin list.

A blocked change now keeps its own reason when the Agent's CLI is also
missing, and the message key always matches the message the CLI prints.

* fix(plugin): keep npm package names and accept pi by path

The default name of an npm package went through the file-path rule, which
cut its last dot segment as an extension: npm:foo.bar was recorded as foo,
and adding npm:foo.bar@1.2.3 later derived foo.bar and was refused as
another package managing the same Pi entry. npm names are now taken from
the package spec.

A Pi account whose CLI is an absolute path to pi was treated as running
another executable, so it could not take npm packages. It now uses the
same path- and platform-aware check as the Pi Extensions tab.

* docs(wiki): add a pull-requests topic for Codex review rounds

Handling Codex's review was only known from practice: confirm each
finding, fix it with a failing test first, reply in its thread, ask for
another review, and follow up until it answers. Writing it down keeps
agents from resolving threads, amending pushed commits, or stopping at
the 👀 that only means the review is still running.

* feat(ui): give the Extras AGENTS.md and Memory tabs one layout

The two tabs shared a page but looked like different products: the header
shifted between them, notes sat in a joined box with an icon toolbar, and
agents showed as an icon strip in a side card. Switching tabs felt jarring.

Memory now follows the AGENTS.md layout: a sticky list column with search,
the note's name with Edit and a More actions menu, the same preview box,
and Use with agents as one row per tool under the note. Long notes open
collapsed like shared files do. The AGENTS.md list gains a search box and
the same sticky column. The Memory tab label stays English in every locale,
like AGENTS.md. Docs and screenshots follow the new layout.

* chore(docs): add a script that serves the Memory screenshot homes

The Memory how-to screenshots came from demo homes that were never
recorded, so reshooting them meant rebuilding the data by hand. The script
rebuilds the fresh and the populated home inside the devcontainer, serves
each behind the Vite dev server, and hands the port back to air afterwards.

* fix(plugin): refuse npm sources Pi can't resolve

validNpmSource accepted specs such as npm:foo/bar, npm:foo@ and names
containing "..", which Pi's own parser rejects. They passed preview, and
Apply recorded a pending binding before pi install failed, leaving an
entry every later sync retried. Validate with the same grammar the Pi
settings reader uses, which also covers a scope without a package name.

* fix(ui): show the default name when adding an npm package to Pi

The name field for an npm source was blank, so it looked like a name was
missing. Leaving it empty records the package name without its version or
scope, as the git flow already shows; the field now shows that name as its
placeholder.
2026-10-04 00:43:43 +08:00