From f62a654c9733e8c8960322aac991bc15629544c8 Mon Sep 17 00:00:00 2001 From: chen <23054115+cwkang1998@users.noreply.github.com> Date: Mon, 16 Nov 2026 05:34:57 +0700 Subject: [PATCH 1/3] ci: validate the manifest, check the docs, and run skill script tests Port upstream's checks from cursor/plugins. scripts/validate-plugin.mjs checks the OMP manifest in package.json: a kebab-case name, a semantic version, an omp manifest, and that each declared path exists. OMP publishes no manifest schema, so it checks the fields OMP's loader reads. scripts/check-pstack-docs.mjs ports check-pstack-docs.mjs to README.md. It checks /skill: commands, links and anchors, count claims, agent and model names, and that the README links every skill, playbook, and agent. It also flags $, which OMP does not run. The README gains playbook, skill, principle, and agent tables, reusing upstream's rows where the fork has the same skill. It now invokes skills with /skill:. test:skills runs skills/*/scripts/test/*.test.ts like upstream's CI. The statechart symlink test now builds its fixture from the real temp path, so it passes on macOS, where /var is a symlink. .github/workflows/validate.yml runs every check on pull requests and pushes to main. The sync workflow runs the new checks before it opens its pull request. --- .github/workflows/upstream-sync.yml | 11 ++ .github/workflows/validate.yml | 49 ++++++ README.md | 183 ++++++++++++++++++++- package.json | 3 + scripts/check-pstack-docs.mjs | 146 ++++++++++++++++ scripts/validate-plugin.mjs | 61 +++++++ scripts/verify.mjs | 2 +- skills/statechart/scripts/test/cli.test.ts | 4 +- 8 files changed, 453 insertions(+), 6 deletions(-) create mode 100644 .github/workflows/validate.yml create mode 100755 scripts/check-pstack-docs.mjs create mode 100755 scripts/validate-plugin.mjs diff --git a/.github/workflows/upstream-sync.yml b/.github/workflows/upstream-sync.yml index 7cf6c2b..2e774ba 100644 --- a/.github/workflows/upstream-sync.yml +++ b/.github/workflows/upstream-sync.yml @@ -29,12 +29,23 @@ jobs: - name: Apply safe upstream update run: node scripts/sync-upstream.mjs --apply + - name: Validate plugin manifest + run: npm run validate + - name: Verify package run: npm run verify + - name: Check docs + run: npm run check:docs + - name: Test updater run: npm run test:sync + - name: Test skill scripts + run: | + npm install --no-save --prefix skills/statechart/scripts + npm run test:skills + - name: Set up Bun uses: oven-sh/setup-bun@v2 diff --git a/.github/workflows/validate.yml b/.github/workflows/validate.yml new file mode 100644 index 0000000..5065c11 --- /dev/null +++ b/.github/workflows/validate.yml @@ -0,0 +1,49 @@ +name: Validate package + +on: + pull_request: + push: + branches: + - main + +permissions: + contents: read + +jobs: + validate: + runs-on: ubuntu-latest + timeout-minutes: 15 + steps: + - uses: actions/checkout@v4 + + - uses: actions/setup-node@v4 + with: + node-version: 22 + + - name: Install dependencies + run: npm install --no-save --prefix skills/statechart/scripts + + - name: Validate plugin manifest + run: npm run validate + + - name: Verify package + run: npm run verify + + - name: Check docs + run: npm run check:docs + + - name: Test updater + run: npm run test:sync + + - name: Test skill scripts + run: npm run test:skills + + - uses: oven-sh/setup-bun@v2 + + - name: Test bundled scripts + run: | + bun install --cwd skills/poteto-mode/scripts --frozen-lockfile + bun test watch-pr check-plan.test.ts + bunx tsc --project skills/poteto-mode/scripts/watch-pr/tsconfig.json --noEmit --strict + bun install --cwd skills/statechart-dashboard/scripts --frozen-lockfile + bun test skills/statechart-dashboard/scripts diff --git a/README.md b/README.md index 2f925e2..7a6df94 100644 --- a/README.md +++ b/README.md @@ -68,7 +68,7 @@ After installing, start a fresh OMP session in the project you want to work on. Run the setup skill once: ```text -$setup-pstack +/skill:setup-pstack ``` It detects the models and task agents your OMP session actually exposes, lets @@ -82,7 +82,7 @@ when they differ. Then route your first real task through the main workflow: ```text -$poteto-mode add a small feature and prove it works end to end +/skill:poteto-mode add a small feature and prove it works end to end ``` The setup skill may offer to create a project verification skill when the project @@ -90,6 +90,162 @@ has no existing way to exercise the real application. Accept that offer when you want repeatable behavioral proof; otherwise setup finishes without changing the project. Read `skills/setup-pstack/SKILL.md` for the complete setup contract. +## Playbooks + +[`/skill:poteto-mode`](./skills/poteto-mode/SKILL.md) matches each task to one of +twenty-three playbooks and opens a todo list from its steps. + +
+The twenty-three playbooks + +| playbook | for | +|---|---| +| [investigation](./skills/poteto-mode/playbooks/investigation.md) | a read-only question. how does x work, why was y built this way, are we sure. | +| [bug fix](./skills/poteto-mode/playbooks/bug-fix.md) | reproduce a defect, root-cause it, and fix with runtime evidence. | +| [perf](./skills/poteto-mode/playbooks/perf-issue.md) | trace a measured slowness and improve it against a baseline. | +| [hillclimb](./skills/poteto-mode/playbooks/hillclimb.md) | sustained, scientific improvement of one metric against a target, looping hypotheses with before/after measurement and one commit per accepted win. | +| [runtime forensics](./skills/poteto-mode/playbooks/runtime-forensics.md) | diagnose a live symptom (leak, idle-cpu spin, glitch) from instrumentation. | +| [trace forensics](./skills/poteto-mode/playbooks/trace-forensics.md) | diagnose a captured profiling artifact (cpuprofile, trace, spindump, heap snapshot). | +| [feature](./skills/poteto-mode/playbooks/feature.md) | new or changed behavior, built from a named data shape. | +| [refactoring](./skills/poteto-mode/playbooks/refactoring.md) | a behavior-preserving change to structure or shape. | +| [prototype](./skills/poteto-mode/playbooks/prototype.md) | a throwaway sketch to make a design or behavioral decision cheaply, or to settle an empirical fork by observing it. | +| [visual parity](./skills/poteto-mode/playbooks/visual-parity.md) | pixel-exact ui equivalence between two implementations. | +| [authoring a skill](./skills/poteto-mode/playbooks/authoring-a-skill.md) | writing or editing a SKILL.md. | +| [eval](./skills/poteto-mode/playbooks/eval.md) | test how a skill or prompt change affects agent behavior, blinded. | +| [babysit](./skills/poteto-mode/playbooks/babysit.md) | drive a pr or a stack to merge-ready: conflicts, review threads, ci. | +| [shipping](./skills/poteto-mode/playbooks/shipping.md) | independently verify a green stack, then land the contiguous verified run bottom-up through github by default or origin when available. | +| [autonomous run](./skills/poteto-mode/playbooks/autonomous-run.md) | drive a long task to completion without stopping. | +| [orchestrate](./skills/poteto-mode/playbooks/orchestrate.md) | a standing project handed to one coordinator chat: multi-day, many stacked prs, fleets of subagents. | +| [autopilot-full](./skills/poteto-mode/playbooks/autopilot-full.md) | run independent prs to merged with one owner per pr. a swarm verifies each code-ready head, and every later change to the patch gets a fresh check. | +| [autopilot-stack](./skills/poteto-mode/playbooks/autopilot-stack.md) | autopilot-full without the merge. build and verify prs for the operator to review and land, stacking a pr only on a pr it builds on. | +| [session pickup](./skills/poteto-mode/playbooks/session-pickup.md) | resume or take over a prior agent's in-flight work. | +| [pause safely](./skills/poteto-mode/playbooks/pause-safely.md) | suspend in-flight work cleanly so it can be resumed later. | +| [multi-phase plan](./skills/poteto-mode/playbooks/multi-phase-plan.md) | work that spans phases or stacked PRs. | +| [worktree cleanup](./skills/poteto-mode/playbooks/worktree-cleanup.md) | reclaim disk by pruning merged or abandoned worktrees and stale ios simulators, safety-gated. | +| [opening a pr](./skills/poteto-mode/playbooks/opening-a-pr.md) | open a ready pr from small ordered commits with a conventional commits title and a briefing-style body. invoked at the end of every other playbook. | + +
+ +## Skills + +`/skill:poteto-mode` runs most of these when a step needs them. Use the table when +you want one directly. + +
+All skills + +| skill | use it when | +|---|---| +| [`/skill:poteto-mode`](./skills/poteto-mode/SKILL.md) | default entry point for any non-trivial task. | +| [`/skill:poteto-help`](./skills/poteto-help/SKILL.md) | you're new to pstack, or unsure which skill, playbook, or principle fits. finds out what you're trying to do, answers that part, and hands you a prompt to type. runs only when you type `/skill:poteto-help`. | +| [`/skill:in-your-own-words`](./skills/in-your-own-words/SKILL.md) | you want the agent to play back your goal and the problem before it starts. runs only when you type `/skill:in-your-own-words`. | +| [`/skill:sharpen`](./skills/sharpen/SKILL.md) | you want a prompt made deeper, not bigger, before you send it: what a top professional would do that you didn't ask for, the raw material they'd start from, their methods and tools, and an outside check that the result is right. hands back the rewritten prompt, which asks the agent to prototype any choice an experiment can settle and leaves product and preference choices to you. doesn't do the task. runs only when you type `/skill:sharpen`. | +| [`/skill:how`](./skills/how/SKILL.md) | you want a walkthrough of how a subsystem works. | +| [`/skill:why`](./skills/why/SKILL.md) | you want to know why something was built this way. answers from the record, not the code: the commits and pr discussions that introduced it and each later change, and other sources when that trail is thin. cites what the authors wrote, marks its own inferences, and says what the record does not answer. | +| [`/skill:recall`](./skills/recall/SKILL.md) | you're starting or resuming work and want your recent context on a topic rebuilt from your own chat history and the shared record, handed back as a tight current-state brief. | +| [`/skill:ketchup`](./skills/ketchup/SKILL.md) | you want what changed in this chat since your last message, in plain words and small visuals, with every item waiting on you listed and decidable from the reply alone, even when that makes the reply long. | +| [`/skill:ketchup-video`](./skills/ketchup-video/SKILL.md) | you want the `/skill:ketchup` catch-up as a short subtitled video of slides, with the calls waiting on you as text under it. | +| [`/skill:blast-radius`](./skills/blast-radius/SKILL.md) | you have a small-looking change and want to know what else it could break, with the one fact it's safe because of proven by running code, not asserted. | +| [`/skill:architect`](./skills/architect/SKILL.md) | you're about to write code that crosses a function boundary and want the caller's usage, types, and module shape settled first. | +| [`/skill:arena`](./skills/arena/SKILL.md) | you want N parallel attempts at the same thing, then to grab the best parts of each. | +| [`/skill:swarm`](./skills/swarm/SKILL.md) | you want N parallel workers across different slices or races, then one aggregated report. | +| [`/skill:interrogate`](./skills/interrogate/SKILL.md) | you have a diff and want different models to try to break it, keeping only findings a run proves. | +| [`/skill:automate-me`](./skills/automate-me/SKILL.md) | you want your own `-mode` skill, drafted from how you've actually worked. | +| [`/skill:make-bot-ui`](./skills/make-bot-ui/SKILL.md) | you want a page or dashboard whose buttons wake a Grok Bot over a webhook, including the sender-key handoff and Tailscale. | +| [`/skill:setup-pstack`](./skills/setup-pstack/SKILL.md) | you want to pick which models pstack uses per role. detects your models and writes a config rule. | +| [`/skill:reflect`](./skills/reflect/SKILL.md) | a long task landed and you want the recipe captured as a skill edit. | +| [`/skill:correct`](./skills/correct/SKILL.md) | you keep correcting agents for the same mistakes. mines history for mistake classes, fixes each at the highest level that works (architecture, then types, lint, and ci, then tests, with docs last), and keeps a table pairing each rule with what enforces it. | +| [`/skill:teach`](./skills/teach/SKILL.md) | you want to actually understand a change or subsystem, not just have it summarized. runs how + why and weaves one plain explanation, built up diagram by diagram. | +| [`/skill:tdd`](./skills/tdd/SKILL.md) | you're fixing a bug and there's a cheap local test path. write the failing test first, then the fix. | +| [`/skill:benchmark-checklist`](./skills/benchmark-checklist/SKILL.md) | you ran a benchmark or measured a speedup or regression. vets the number (limiter, tuning, errors, repeat runs, end-to-end relevance) before you report or act on it. | +| [`/skill:no-comments`](./skills/no-comments/SKILL.md) | strip comments before review; spawns Comment Sicko, fixes accepted findings, offers encodings for claimed constraints. | +| [`/skill:typescript-best-practices`](./skills/typescript-best-practices/SKILL.md) | you're reading or editing typescript. grounds the type-system-discipline principle in syntax. | +| [`/skill:figure-it-out`](./skills/figure-it-out/SKILL.md) | no bundled playbook fits. designs a rigorous, auditable playbook for the task. | +| [`/skill:show-me-your-work`](./skills/show-me-your-work/SKILL.md) | you want a reviewable decision trail. logs decisions to a tsv you can commit. | +| [`/skill:create-verification-skill`](./skills/create-verification-skill/SKILL.md) | your project has no scripted way to prove app behavior. generates a project-local verify skill with a feature map, for any language or platform. | +| [`/skill:maintain-verification-skill`](./skills/maintain-verification-skill/SKILL.md) | your verify skill's feature map has drifted from the app. source wave + one live pass, at most one PR of proven corrections. | +| [`/skill:create-formal-verification-skill`](./skills/create-formal-verification-skill/SKILL.md) | tests can't reach the case that breaks a race, retry, state machine, parser, or unsafe code. verifies one property with the tool that fits and generates a project-local skill to recheck it on every change. | +| [`/skill:maintain-formal-verification-skill`](./skills/maintain-formal-verification-skill/SKILL.md) | code your formal verification covers has changed since it was last checked. updates the model, harness, or properties to match the code, reruns, and says whether each failure is drift in the verification or a bug in the code. | +| [`/skill:statechart`](./skills/statechart/SKILL.md) | someone who owns the behavior needs to see it, not read a spec. checks a tla+ model, draws what the user sees as a mermaid statechart, marks each state that breaks a rule, and gives the shortest path to each one. | +| [`/skill:unslop`](./skills/unslop/SKILL.md) | you're cleaning up writing. removes AI tells. | +| [`/skill:bro`](./skills/bro/SKILL.md) | you want the last message restated in plain human language, no jargon. | +| [`/skill:technical-writing`](./skills/technical-writing/SKILL.md) | layered doc standard (Diátaxis + Google developer style + STE + Global English) for docs, RFCs, readmes, PR descriptions, commit messages. | +| [`/skill:pstack-omp`](./skills/pstack-omp/SKILL.md) | a workflow needs delegation or OMP lifecycle behavior. maps pstack roles to OMP task agents and pins each config line to its own agent. `poteto-mode` reads it for you. | +| [`/skill:orchestrate-omp`](./skills/orchestrate-omp/SKILL.md) | you want parallel discovery, specialist review, or partitioned implementation across OMP subagents. | +| [`/skill:statechart-dashboard`](./skills/statechart-dashboard/SKILL.md) | you ran `/skill:statechart` and want every chart with its rules, report, spec, and notes in one offline Chrome page. | +| [`/skill:domain-modeling`](./skills/domain-modeling/SKILL.md) | you're settling codebase terminology, editing a GLOSSARY.md, or recording an ADR. | +| [`/skill:grill-me`](./skills/grill-me/SKILL.md) | you want a relentless interview to sharpen a plan or design. runs only when you ask. | +| [`/skill:grill-with-docs`](./skills/grill-with-docs/SKILL.md) | the `/skill:grill-me` interview, writing the glossary and ADRs as it goes. | +| [`/skill:grilling`](./skills/grilling/SKILL.md) | the interview the grill skills load. runs only when you ask to be grilled. | +| [`/skill:wizard`](./skills/wizard/SKILL.md) | a step only a human can do, such as provisioning, credentials, CI secrets, or a third-party dashboard. generates an interactive bash walkthrough. | +| [`/skill:rust-best-practices`](./skills/rust-best-practices/SKILL.md) | you're reading or editing rust. | +| [`/skill:setup-benny`](./skills/setup-benny/SKILL.md) | you're installing benny, or changing its slack, tracker, repository, routing, control, model, or budget settings. | +| [`/skill:triage-issue-reports`](./skills/triage-issue-reports/SKILL.md) | benny's triage automation runs it on a slack issue report. not for direct use. | +| [`/skill:reproduce-and-fix-issues`](./skills/reproduce-and-fix-issues/SKILL.md) | benny's repro automation runs it on a triaged bug. not for direct use. | + +
+ +## Principles + +Twenty-four short skills, one principle each. `poteto-mode` indexes them inline +and reads that index at task start. + +
+All twenty-four principles + +| principle | group | rule | +|---|---|---| +| [laziness-protocol](./skills/principle-laziness-protocol/SKILL.md) | core | Bias toward deletion and the smallest change that solves the problem. | +| [foundational-thinking](./skills/principle-foundational-thinking/SKILL.md) | core | Apply before writing logic: choosing core types and data structures, sequencing scaffold-vs-feature work, asking what concurrent actors share. Get the data structures right so downstream code becomes obvious. | +| [redesign-from-first-principles](./skills/principle-redesign-from-first-principles/SKILL.md) | core | Redesign as if the requirement had been a foundational assumption from day one, instead of bolting it on. | +| [attack-the-premise](./skills/principle-attack-the-premise/SKILL.md) | core | Apply when two or more fixes that share one premise have failed the same gate. Write the premise down and test it directly before you write another fix that assumes it. | +| [subtract-before-you-add](./skills/principle-subtract-before-you-add/SKILL.md) | core | Remove dead weight, redundant validators, and stub references first, then build on the simpler base. | +| [minimize-reader-load](./skills/principle-minimize-reader-load/SKILL.md) | core | Count layers between question and answer, and hidden state in the reader's head; collapse one-caller wrappers and shrink mutable scope. | +| [outcome-oriented-execution](./skills/principle-outcome-oriented-execution/SKILL.md) | core | Apply during planned rewrites and migrations with explicit phase boundaries. Converge on the target architecture; don't preserve smooth intermediate states with throwaway compatibility code. | +| [experience-first](./skills/principle-experience-first/SKILL.md) | core | Choose user delight over implementation convenience; ship fewer polished features over more rough ones. | +| [exhaust-the-design-space](./skills/principle-exhaust-the-design-space/SKILL.md) | core | Build 2-3 competing prototypes and compare side by side before committing. | +| [build-the-lever](./skills/principle-build-the-lever/SKILL.md) | core | Apply to any non-trivial work, not just bulk work: edits, migrations, analyses, checks. Build the tool that does it or proves it (codemod, script, generator, or a skill your subagents follow) instead of working by hand. The tool is the artifact a reviewer can rerun. | +| [model-the-domain](./skills/principle-model-the-domain/SKILL.md) | architecture | Encode the domain in a structure instead of scattered conditionals. | +| [boundary-discipline](./skills/principle-boundary-discipline/SKILL.md) | architecture | Concentrate guards at system boundaries (CLI, config, network, external APIs); trust internal types and keep business logic in pure functions. | +| [type-system-discipline](./skills/principle-type-system-discipline/SKILL.md) | architecture | Make illegal states unrepresentable, brand semantic primitives, parse external data at boundaries, exhaust variants, derive from authoritative schemas. | +| [make-operations-idempotent](./skills/principle-make-operations-idempotent/SKILL.md) | architecture | Converge to the same end state regardless of partial prior runs. | +| [migrate-callers-then-delete-legacy-apis](./skills/principle-migrate-callers-then-delete-legacy-apis/SKILL.md) | architecture | Migrate callers and delete the old API in the same wave instead of preserving compatibility layers. | +| [separate-before-serializing-shared-state](./skills/principle-separate-before-serializing-shared-state/SKILL.md) | architecture | Eliminate the sharing first; serialize structurally only when one shared writer is a real invariant. | +| [prove-it-works](./skills/principle-prove-it-works/SKILL.md) | verification | Apply after completing a task, before declaring done. Verify against the real artifact (run the feature, read the actual value, inspect the diff), not a proxy, self-report, or 'it compiles.'. | +| [fix-root-causes](./skills/principle-fix-root-causes/SKILL.md) | verification | Trace each symptom back to the first place the system went wrong and fix it there. A guard is a fix only when the state it handles is legitimate. | +| [sequence-verifiable-units](./skills/principle-sequence-verifiable-units/SKILL.md) | verification | Apply to multi-step work (sweeps, migrations, runs of similar edits) and to how you stack commits and PRs. Break work into small units that each end in a verifiable state, check each before the next, and order delivery so the sequence proves itself to a reviewer. | +| [test-behavior-not-implementation](./skills/principle-test-behavior-not-implementation/SKILL.md) | verification | Apply when you write, change, or keep a test. Assert what the code's users can observe, so the test fails when that behavior breaks and keeps passing when only the internals change. | +| [explain-the-number](./skills/principle-explain-the-number/SKILL.md) | verification | Apply before you trust, report, or act on a number you measured: a speedup, a regression, a throughput, a latency, or an eval result. Find what limits it, and rule out that it measured something other than the work you think. | +| [guard-the-context-window](./skills/principle-guard-the-context-window/SKILL.md) | delegation | Route bulk to subagents; keep summaries in the main thread, not raw payloads. | +| [never-block-on-the-human](./skills/principle-never-block-on-the-human/SKILL.md) | delegation | Proceed, present the result, let the human course-correct after the fact; reserve confirmation for irreversible actions. | +| [encode-lessons-in-structure](./skills/principle-encode-lessons-in-structure/SKILL.md) | meta | Encode the rule as a lint, metadata flag, runtime check, or script instead of more text. | + +
+ +## Agents + +The adapter routes pstack roles to OMP's bundled task agents and to these agents. +Each `pstack-*` agent carries one line of the model config and runs on that line's +model through `task.agentModelOverrides`. + +| agent | role | +|---|---| +| [`planner`](./agents/planner.md) | technical planning, architecture, decomposition, and sequencing. | +| [`designer`](./agents/designer.md) | visual, interaction, and product design. | +| [`librarian`](./agents/librarian.md) | read-only, source-verified research on external libraries, APIs, protocols, and repository history. | +| [`poteto-agent`](./agents/poteto-agent.md) | runs one delegated implementation brief under the active playbook. | +| [`comment-sicko`](./agents/comment-sicko.md) | read-only comment reviewer. `/skill:no-comments` spawns it. | +| [`pstack-hardest`](./agents/pstack-hardest.md) | the `hardest tasks` line. | +| [`pstack-judgment`](./agents/pstack-judgment.md) | the `judgment and prose` line. | +| [`pstack-reflect-tooling`](./agents/pstack-reflect-tooling.md) | the `reflect tooling` line. read-only. | +| [`pstack-swarm-worker`](./agents/pstack-swarm-worker.md) | the `swarm workers` line. | +| [`pstack-runner-1`](./agents/pstack-runner-1.md) | entry 1 of the runner lines. | +| [`pstack-runner-2`](./agents/pstack-runner-2.md) | entry 2 of the runner lines. | +| [`pstack-runner-3`](./agents/pstack-runner-3.md) | entry 3 of the runner lines. | +| [`pstack-judge-1`](./agents/pstack-judge-1.md) | entry 1 of the `arena cross-judge pool` line. read-only. | +| [`pstack-judge-2`](./agents/pstack-judge-2.md) | entry 2 of the `arena cross-judge pool` line. read-only. | +| [`pstack-judge-3`](./agents/pstack-judge-3.md) | entry 3 of the `arena cross-judge pool` line. read-only. | + ## Automatic upstream updates `.github/workflows/upstream-sync.yml` checks the original pstack `main` branch @@ -104,7 +260,8 @@ The updater: and upstream edits land around them. 4. Leaves conflict markers where upstream and the OMP port changed the same lines, and exits with status 2 until they are resolved. -5. Runs verification, updater tests, Bun tests, and strict TypeScript checking. +5. Runs the manifest, package, docs, updater, and skill script checks, the Bun + tests, and strict TypeScript checking. 6. Opens a pull request only after those checks pass. Run it locally: @@ -120,9 +277,12 @@ silently overwrites them. ## Development and verification -```bash +npm run validate npm run verify +npm run check:docs npm run test:sync +npm install --no-save --prefix skills/statechart/scripts +npm run test:skills bun install --cwd skills/poteto-mode/scripts --frozen-lockfile bun test watch-pr check-plan.test.ts bunx tsc --project skills/poteto-mode/scripts/watch-pr/tsconfig.json --noEmit --strict @@ -130,6 +290,21 @@ bun install --cwd skills/statechart-dashboard/scripts --frozen-lockfile bun test skills/statechart-dashboard/scripts ``` +`.github/workflows/validate.yml` runs these on every pull request and on pushes to +`main`. The scripts follow the checks upstream runs in `cursor/plugins`. + +`npm run validate` checks the OMP manifest in `package.json`: a kebab-case name, a +semantic version, an `omp` manifest, and that every path it declares exists. OMP +publishes no manifest schema, so these are the fields its plugin loader reads. + +`npm run check:docs` checks this README against the tree. Every `/skill:` command +and relative link must resolve, anchors must match a heading, counts such as +"twenty-three playbooks" must match, and the README must link every skill, +playbook, and agent. A new skill needs a row in the tables above. + +`npm run test:skills` runs every `skills/*/scripts/test/*.test.ts` suite with +Node's test runner. + `npm run verify` checks that every skill and agent has matching frontmatter, that links, `skill://` references, and named skills resolve, and that no merge conflict markers remain. It also checks that the adapter's Model routing table diff --git a/package.json b/package.json index 67b734f..e9eb58e 100644 --- a/package.json +++ b/package.json @@ -35,8 +35,11 @@ "upstream.lock.json" ], "scripts": { + "validate": "node scripts/validate-plugin.mjs", "verify": "node scripts/verify.mjs", + "check:docs": "node scripts/check-pstack-docs.mjs", "test:sync": "node --test scripts/sync-upstream.test.mjs", + "test:skills": "node --disable-warning=ExperimentalWarning --test skills/*/scripts/test/*.test.ts", "sync:check": "node scripts/sync-upstream.mjs --check", "sync:apply": "node scripts/sync-upstream.mjs --apply" } diff --git a/scripts/check-pstack-docs.mjs b/scripts/check-pstack-docs.mjs new file mode 100755 index 0000000..9ace0b0 --- /dev/null +++ b/scripts/check-pstack-docs.mjs @@ -0,0 +1,146 @@ +#!/usr/bin/env node + +// Lists the package's skills, playbooks, and agents from the tree and checks what README.md says about them: skill +// commands, relative links and anchors, counts, agent and model names, and that the README links each one. Ported +// from cursor/plugins scripts/check-pstack-docs.mjs. Exits 1 when the docs drift from the tree. + +import { existsSync, readdirSync, readFileSync, statSync } from "node:fs"; +import { dirname, join, posix } from "node:path"; +import { fileURLToPath } from "node:url"; + +const ROOT = join(dirname(fileURLToPath(import.meta.url)), ".."); +const SETUP = join(ROOT, "skills", "setup-pstack", "SKILL.md"); +const ADAPTER = join(ROOT, "skills", "pstack-omp", "SKILL.md"); + +const SMALL = "zero one two three four five six seven eight nine ten eleven twelve thirteen fourteen fifteen sixteen seventeen eighteen nineteen".split(" "); +const TENS = ["", "", "twenty", "thirty", "forty", "fifty", "sixty", "seventy", "eighty", "ninety"]; +// "The twenty-three playbooks" claims the whole set. "Three playbooks scale it up" names a subset, so it is not checked. +const CLAIM = /\b(?:(all|has|of|ships|the|with) )?(\d+|[a-z]+(?:-[a-z]+)?) (short )?(skills|principles|playbooks|agents)\b/gi; +// OMP runs a skill as /skill:. $ is another harness's syntax and does nothing in OMP. +const COMMAND = /(?<=^|[\s`(|"'>])\/skill:([a-z][a-z0-9-]*)(?![\w/<-])/gm; +const FOREIGN_COMMAND = /(?<=^|[\s`(|"'>])\$([a-z][a-z0-9-]*)(?![\w/<-])/gm; +const LINK = /\]\(]+)>?(?:\s+"[^"]*")?\)/g; +const AGENT = /agent: "([^"]+)"/g; +const MODEL_ID = /\b(?:claude-[a-z]+|grok|gpt)-\d(?:[\w.-]*\w)?/g; +const MODEL_PROSE = /\b(opus|sonnet|grok) (\d+(?:\.\d+)?)\b/gi; + +function names(dir, keep) { + return existsSync(dir) ? readdirSync(dir).filter((name) => keep(join(dir, name))).sort() : []; +} +const isSkill = (path) => existsSync(join(path, "SKILL.md")); +const isMarkdown = (path) => path.endsWith(".md") && statSync(path).isFile(); + +const skills = names(join(ROOT, "skills"), isSkill); +const principles = skills.filter((name) => name.startsWith("principle-")); +const commands = skills.filter((name) => !name.startsWith("principle-")); +const playbooks = names(join(ROOT, "skills", "poteto-mode", "playbooks"), isMarkdown).map((name) => name.slice(0, -3)); +const agents = names(join(ROOT, "agents"), isMarkdown).map((name) => name.slice(0, -3)); +// The adapter's closed roster also holds the task agents OMP bundles. +const roster = readFileSync(ADAPTER, "utf8").match(/roster is closed:\n\n```text\n([\s\S]*?)\n```/)?.[1].split("\n") ?? []; +const docs = ["README.md"]; +const text = new Map(docs.map((doc) => [doc, readFileSync(join(ROOT, doc), "utf8")])); +const setup = readFileSync(SETUP, "utf8"); + +const problems = []; +const lineOf = (doc, index) => text.get(doc).slice(0, index).split("\n").length; +const fail = (doc, index, message) => problems.push(`${doc}:${lineOf(doc, index)} ${message}`); + +function toNumber(word) { + if (/^\d+$/.test(word)) return Number(word); + const [tens, unit] = word.toLowerCase().split("-"); + if (unit === undefined && SMALL.includes(tens)) return SMALL.indexOf(tens); + const ones = unit === undefined ? 0 : SMALL.indexOf(unit); + return TENS.indexOf(tens) > 1 && ones >= 0 && ones < 10 ? TENS.indexOf(tens) * 10 + ones : undefined; +} + +function anchors(path) { + const seen = new Map(); + const found = new Set(); + let fenced = false; + for (const line of readFileSync(join(ROOT, path), "utf8").split("\n")) { + if (/^\s*(```|~~~)/.test(line)) fenced = !fenced; + const heading = !fenced && line.match(/^#{1,6}\s+(.*?)\s*$/); + if (!heading) continue; + const plain = heading[1].replace(/\[([^\]]*)\]\([^)]*\)/g, "$1").replace(/[`*]/g, ""); + const slug = plain.trim().toLowerCase().replace(/[^\p{L}\p{N}\s_-]/gu, "").replace(/\s/g, "-"); + const repeat = seen.get(slug) ?? 0; + seen.set(slug, repeat + 1); + found.add(repeat ? `${slug}-${repeat}` : slug); + } + return found; +} + +const expected = { + skills: [skills.length, commands.length], + principles: [principles.length], + playbooks: [playbooks.length], + agents: [agents.length], +}; +const named = new Set(); +let mentions = 0; +let links = 0; + +for (const [doc, body] of text) { + for (const { 0: match, 1: whole, 2: word, 3: short, 4: noun, index } of body.matchAll(CLAIM)) { + const claimed = toNumber(word); + const kind = short ? "principles" : noun.toLowerCase(); + if ((whole || short) && claimed !== undefined && !expected[kind].includes(claimed)) { + fail(doc, index, `says "${match}", but the tree has ${expected[kind].join(" or ")}`); + } + } + for (const { 1: name, index } of body.matchAll(COMMAND)) { + mentions++; + if (skills.includes(name)) named.add(name); + else fail(doc, index, `names /skill:${name}, which no skill in this package provides`); + } + for (const { 1: name, index } of body.matchAll(FOREIGN_COMMAND)) { + if (skills.includes(name)) fail(doc, index, `names $${name}, but OMP runs skills as /skill:${name}`); + } + for (const { 1: href, index } of body.matchAll(LINK)) { + if (/^[a-z][a-z0-9+.-]*:/i.test(href)) continue; + links++; + const [target, anchor] = href.split("#"); + const path = target ? posix.normalize(posix.join(posix.dirname(doc), target)).replace(/\/$/, "") : doc; + const skill = path.match(/^skills\/([^/]+)\/SKILL\.md$/); + if (skill) named.add(skill[1]); + if (!existsSync(join(ROOT, path))) fail(doc, index, `links to ${href}, which does not exist`); + else if (anchor && path.endsWith(".md") && !anchors(path).has(anchor)) { + fail(doc, index, `links to ${href}, but ${path} has no heading with that anchor`); + } + } + for (const { 1: name, index } of body.matchAll(AGENT)) { + if (!agents.includes(name) && !roster.includes(name)) { + fail(doc, index, `names agent "${name}", which agents/ does not ship and the adapter's roster does not list`); + } + } + for (const { 0: id, index } of body.matchAll(MODEL_ID)) { + if (!setup.includes(id)) fail(doc, index, `names model ${id}, which setup-pstack does not use`); + } + for (const { 0: match, 1: family, 2: version, index } of body.matchAll(MODEL_PROSE)) { + const prefix = family.toLowerCase() === "grok" ? `grok-${version}` : `claude-${family.toLowerCase()}-${version.replace(".", "-")}`; + if (!setup.includes(prefix)) fail(doc, index, `says "${match}", but setup-pstack has no ${prefix} default`); + } +} + +const readme = text.get("README.md"); +for (const skill of skills) { + if (!readme.includes(`(./skills/${skill}/SKILL.md)`)) problems.push(`README.md does not list skill ${skill}`); +} +for (const playbook of playbooks) { + if (!readme.includes(`(./skills/poteto-mode/playbooks/${playbook}.md)`)) problems.push(`README.md does not list playbook ${playbook}`); +} +for (const agent of agents) { + if (!readme.includes(`(./agents/${agent}.md)`)) problems.push(`README.md does not link agent ${agent}`); +} + +console.log( + `tree: ${skills.length} skills (${commands.length} commands, ${principles.length} principles), ` + + `${playbooks.length} playbooks, ${agents.length} agents`, +); +console.log( + `docs: ${docs.length} files, ${mentions} /skill: mentions, ${links} relative links, ` + + `${commands.filter((name) => named.has(name)).length} of ${commands.length} commands named`, +); +for (const problem of problems) console.log(`FAIL ${problem}`); +console.log(`${problems.length} problems`); +if (problems.length > 0) process.exit(1); diff --git a/scripts/validate-plugin.mjs b/scripts/validate-plugin.mjs new file mode 100755 index 0000000..037a23e --- /dev/null +++ b/scripts/validate-plugin.mjs @@ -0,0 +1,61 @@ +#!/usr/bin/env node + +// Checks the OMP plugin manifest in package.json. Ported from cursor/plugins scripts/validate-plugins.mjs. OMP +// publishes no manifest schema and its loader validates nothing, so this checks the fields the loader reads. + +import { existsSync, readFileSync } from "node:fs"; +import { dirname, relative, resolve } from "node:path"; +import { fileURLToPath } from "node:url"; + +const root = resolve(dirname(fileURLToPath(import.meta.url)), ".."); +// The plugin name pattern from cursor/plugins schemas/plugin.schema.json. +const NAME = /^[a-z0-9]([a-z0-9.-]*[a-z0-9])?$/; +const SEMVER = /^\d+\.\d+\.\d+(?:[-+][0-9A-Za-z.-]+)?$/; + +let errors = 0; + +function fail(message) { + console.error(`ERROR: ${message}`); + errors++; +} + +let manifest; +try { + manifest = JSON.parse(readFileSync(resolve(root, "package.json"), "utf-8")); +} catch (error) { + fail(`package.json does not parse: ${error.message}`); + process.exit(1); +} + +if (typeof manifest.name !== "string" || !NAME.test(manifest.name)) { + fail(`package.json name "${manifest.name}" is not a kebab-case plugin identifier`); +} + +// OMP records the installed version from package.json. +if (typeof manifest.version !== "string" || !SEMVER.test(manifest.version)) { + fail(`package.json version "${manifest.version}" is not a semantic version`); +} + +// OMP's runtime plugin loading skips a package that has no omp (or legacy pi) manifest. +if (manifest.omp === null || typeof manifest.omp !== "object" || Array.isArray(manifest.omp)) { + fail("package.json has no omp manifest, so OMP loads nothing from this package"); +} else { + for (const [key, value] of Object.entries(manifest.omp)) { + if (!Array.isArray(value)) continue; + for (const entry of value) { + const path = resolve(root, entry); + if (relative(root, path).startsWith("..")) { + fail(`package.json omp.${key} entry "${entry}" points outside the package`); + } else if (!existsSync(path)) { + fail(`package.json omp.${key} entry "${entry}" does not exist`); + } + } + } +} + +if (errors > 0) { + console.error(`\nValidation failed with ${errors} error(s).`); + process.exit(1); +} else { + console.log("Plugin manifest validated successfully."); +} diff --git a/scripts/verify.mjs b/scripts/verify.mjs index 0d5a01f..aab2f79 100644 --- a/scripts/verify.mjs +++ b/scripts/verify.mjs @@ -29,7 +29,7 @@ function frontmatter(source) { const skillDirs = (await readdir(skillsRoot, { withFileTypes: true })).filter((entry) => entry.isDirectory()).map((entry) => entry.name); const skillFiles = await filesUnder(skillsRoot); -const markdownFiles = [...skillFiles, ...(await filesUnder(agentsRoot)), join(root, "README.md")].filter((path) => path.endsWith(".md")); +const markdownFiles = [...skillFiles, ...(await filesUnder(agentsRoot))].filter((path) => path.endsWith(".md")); for (const name of skillDirs) { const path = join(skillsRoot, name, "SKILL.md"); diff --git a/skills/statechart/scripts/test/cli.test.ts b/skills/statechart/scripts/test/cli.test.ts index 11f06a6..187fe92 100644 --- a/skills/statechart/scripts/test/cli.test.ts +++ b/skills/statechart/scripts/test/cli.test.ts @@ -114,7 +114,9 @@ const launcherTools = () => { }; const linkedLauncher = () => { - const links = fs.mkdtempSync(path.join(os.tmpdir(), "statechart-links-")); + // The relative link must be computed from the directory the kernel resolves it in, so start from the real path + // (macOS's temp directory sits under /var, a symlink to /private/var). + const links = fs.mkdtempSync(path.join(fs.realpathSync(os.tmpdir()), "statechart-links-")); const [first, second] = [path.join(links, "a"), path.join(links, "b")]; fs.mkdirSync(first); fs.mkdirSync(second); From e6c500b36eadeca6f59a26f647148d65fd5ef420 Mon Sep 17 00:00:00 2001 From: chen <23054115+cwkang1998@users.noreply.github.com> Date: Mon, 16 Nov 2026 05:50:49 +0700 Subject: [PATCH 2/3] fix(ci): address review of the ported checks Restore the README code fence, and have verify scan README.md again for skill:// and named-skill references. validate-plugin uses the semver.org pattern and checks every relative path in the omp manifest, including string fields and feature entries. check-pstack-docs flags /name and /pstack:name as well as $name, and drops upstream's model-name check, since setup-pstack has no default models to compare with. The sync workflow opens a draft pull request listing the docs failures when only the docs check fails, so a new upstream skill gets its README row on that branch. --- .github/workflows/upstream-sync.yml | 32 +++++++++++++++++++++++------ README.md | 12 ++++++++--- scripts/check-pstack-docs.mjs | 22 ++++++-------------- scripts/validate-plugin.mjs | 28 +++++++++++++++---------- scripts/verify.mjs | 2 +- 5 files changed, 59 insertions(+), 37 deletions(-) diff --git a/.github/workflows/upstream-sync.yml b/.github/workflows/upstream-sync.yml index 2e774ba..cda8c47 100644 --- a/.github/workflows/upstream-sync.yml +++ b/.github/workflows/upstream-sync.yml @@ -35,8 +35,13 @@ jobs: - name: Verify package run: npm run verify + # A new upstream skill needs a README row that only a person can write, so a docs failure opens a draft + # pull request to add it on instead of failing the run. - name: Check docs - run: npm run check:docs + id: docs + continue-on-error: true + shell: bash + run: npm run -s check:docs 2>&1 | tee "$RUNNER_TEMP/docs-check.txt" - name: Test updater run: npm run test:sync @@ -57,15 +62,30 @@ jobs: bun install --cwd skills/statechart-dashboard/scripts --frozen-lockfile bun test skills/statechart-dashboard/scripts + - name: Write pull request body + shell: bash + run: | + { + echo "Automated update from the pinned authoritative Cursor pstack source." + echo + echo "The updater three-way merges OMP adaptations with upstream and fails" + echo "before opening a pull request when they conflict." + if [ "${{ steps.docs.outcome }}" = failure ]; then + echo + echo "README.md does not match the synced tree yet. Fix these on this branch before merging:" + echo + echo '```text' + grep '^FAIL' "$RUNNER_TEMP/docs-check.txt" + echo '```' + fi + } > "$RUNNER_TEMP/pr-body.md" + - name: Open update pull request uses: peter-evans/create-pull-request@v7 with: commit-message: "chore: sync upstream pstack" title: "chore: sync upstream pstack" - body: | - Automated update from the pinned authoritative Cursor pstack source. - - The updater three-way merges OMP adaptations with upstream and fails - before opening a pull request when they conflict. + body-path: ${{ runner.temp }}/pr-body.md + draft: ${{ steps.docs.outcome == 'failure' }} branch: automation/upstream-pstack delete-branch: true diff --git a/README.md b/README.md index 7a6df94..cfc7ac9 100644 --- a/README.md +++ b/README.md @@ -152,7 +152,7 @@ you want one directly. | [`/skill:interrogate`](./skills/interrogate/SKILL.md) | you have a diff and want different models to try to break it, keeping only findings a run proves. | | [`/skill:automate-me`](./skills/automate-me/SKILL.md) | you want your own `-mode` skill, drafted from how you've actually worked. | | [`/skill:make-bot-ui`](./skills/make-bot-ui/SKILL.md) | you want a page or dashboard whose buttons wake a Grok Bot over a webhook, including the sender-key handoff and Tailscale. | -| [`/skill:setup-pstack`](./skills/setup-pstack/SKILL.md) | you want to pick which models pstack uses per role. detects your models and writes a config rule. | +| [`/skill:setup-pstack`](./skills/setup-pstack/SKILL.md) | you want to pick which models pstack uses per role. detects your models, writes `.pstack/config.md`, and sets each agent's `task.agentModelOverrides` entry. | | [`/skill:reflect`](./skills/reflect/SKILL.md) | a long task landed and you want the recipe captured as a skill edit. | | [`/skill:correct`](./skills/correct/SKILL.md) | you keep correcting agents for the same mistakes. mines history for mistake classes, fixes each at the highest level that works (architecture, then types, lint, and ci, then tests, with docs last), and keeps a table pairing each rule with what enforces it. | | [`/skill:teach`](./skills/teach/SKILL.md) | you want to actually understand a change or subsystem, not just have it summarized. runs how + why and weaves one plain explanation, built up diagram by diagram. | @@ -262,7 +262,10 @@ The updater: lines, and exits with status 2 until they are resolved. 5. Runs the manifest, package, docs, updater, and skill script checks, the Bun tests, and strict TypeScript checking. -6. Opens a pull request only after those checks pass. +6. Opens a pull request only after those checks pass. When only the docs check + fails, for example because upstream added a skill the README tables do not + list yet, it opens the pull request as a draft with the failures in its body. + Add the missing rows on that branch before merging. Run it locally: @@ -277,6 +280,7 @@ silently overwrites them. ## Development and verification +```bash npm run validate npm run verify npm run check:docs @@ -300,7 +304,9 @@ publishes no manifest schema, so these are the fields its plugin loader reads. `npm run check:docs` checks this README against the tree. Every `/skill:` command and relative link must resolve, anchors must match a heading, counts such as "twenty-three playbooks" must match, and the README must link every skill, -playbook, and agent. A new skill needs a row in the tables above. +playbook, and agent. It also flags a package skill written as `$name`, `/name`, +or `/pstack:name`, which OMP does not run. A new skill needs a row in the tables +above. `npm run test:skills` runs every `skills/*/scripts/test/*.test.ts` suite with Node's test runner. diff --git a/scripts/check-pstack-docs.mjs b/scripts/check-pstack-docs.mjs index 9ace0b0..fc27b9a 100755 --- a/scripts/check-pstack-docs.mjs +++ b/scripts/check-pstack-docs.mjs @@ -1,7 +1,7 @@ #!/usr/bin/env node // Lists the package's skills, playbooks, and agents from the tree and checks what README.md says about them: skill -// commands, relative links and anchors, counts, agent and model names, and that the README links each one. Ported +// commands, relative links and anchors, counts, agent names, and that the README links each one. Ported // from cursor/plugins scripts/check-pstack-docs.mjs. Exits 1 when the docs drift from the tree. import { existsSync, readdirSync, readFileSync, statSync } from "node:fs"; @@ -9,20 +9,18 @@ import { dirname, join, posix } from "node:path"; import { fileURLToPath } from "node:url"; const ROOT = join(dirname(fileURLToPath(import.meta.url)), ".."); -const SETUP = join(ROOT, "skills", "setup-pstack", "SKILL.md"); const ADAPTER = join(ROOT, "skills", "pstack-omp", "SKILL.md"); const SMALL = "zero one two three four five six seven eight nine ten eleven twelve thirteen fourteen fifteen sixteen seventeen eighteen nineteen".split(" "); const TENS = ["", "", "twenty", "thirty", "forty", "fifty", "sixty", "seventy", "eighty", "ninety"]; // "The twenty-three playbooks" claims the whole set. "Three playbooks scale it up" names a subset, so it is not checked. const CLAIM = /\b(?:(all|has|of|ships|the|with) )?(\d+|[a-z]+(?:-[a-z]+)?) (short )?(skills|principles|playbooks|agents)\b/gi; -// OMP runs a skill as /skill:. $ is another harness's syntax and does nothing in OMP. +// OMP runs a skill as /skill:. Other harnesses' forms ($, /, /pstack:) reach the model as plain +// text, so the skill never loads. const COMMAND = /(?<=^|[\s`(|"'>])\/skill:([a-z][a-z0-9-]*)(?![\w/<-])/gm; -const FOREIGN_COMMAND = /(?<=^|[\s`(|"'>])\$([a-z][a-z0-9-]*)(?![\w/<-])/gm; +const FOREIGN_COMMAND = /(?<=^|[\s`(|"'>])(?:\$|\/(?:pstack:)?)([a-z][a-z0-9-]*)(?![\w/<-])/gm; const LINK = /\]\(]+)>?(?:\s+"[^"]*")?\)/g; const AGENT = /agent: "([^"]+)"/g; -const MODEL_ID = /\b(?:claude-[a-z]+|grok|gpt)-\d(?:[\w.-]*\w)?/g; -const MODEL_PROSE = /\b(opus|sonnet|grok) (\d+(?:\.\d+)?)\b/gi; function names(dir, keep) { return existsSync(dir) ? readdirSync(dir).filter((name) => keep(join(dir, name))).sort() : []; @@ -39,7 +37,6 @@ const agents = names(join(ROOT, "agents"), isMarkdown).map((name) => name.slice( const roster = readFileSync(ADAPTER, "utf8").match(/roster is closed:\n\n```text\n([\s\S]*?)\n```/)?.[1].split("\n") ?? []; const docs = ["README.md"]; const text = new Map(docs.map((doc) => [doc, readFileSync(join(ROOT, doc), "utf8")])); -const setup = readFileSync(SETUP, "utf8"); const problems = []; const lineOf = (doc, index) => text.get(doc).slice(0, index).split("\n").length; @@ -93,8 +90,8 @@ for (const [doc, body] of text) { if (skills.includes(name)) named.add(name); else fail(doc, index, `names /skill:${name}, which no skill in this package provides`); } - for (const { 1: name, index } of body.matchAll(FOREIGN_COMMAND)) { - if (skills.includes(name)) fail(doc, index, `names $${name}, but OMP runs skills as /skill:${name}`); + for (const { 0: match, 1: name, index } of body.matchAll(FOREIGN_COMMAND)) { + if (skills.includes(name)) fail(doc, index, `names ${match}, but OMP runs skills as /skill:${name}`); } for (const { 1: href, index } of body.matchAll(LINK)) { if (/^[a-z][a-z0-9+.-]*:/i.test(href)) continue; @@ -113,13 +110,6 @@ for (const [doc, body] of text) { fail(doc, index, `names agent "${name}", which agents/ does not ship and the adapter's roster does not list`); } } - for (const { 0: id, index } of body.matchAll(MODEL_ID)) { - if (!setup.includes(id)) fail(doc, index, `names model ${id}, which setup-pstack does not use`); - } - for (const { 0: match, 1: family, 2: version, index } of body.matchAll(MODEL_PROSE)) { - const prefix = family.toLowerCase() === "grok" ? `grok-${version}` : `claude-${family.toLowerCase()}-${version.replace(".", "-")}`; - if (!setup.includes(prefix)) fail(doc, index, `says "${match}", but setup-pstack has no ${prefix} default`); - } } const readme = text.get("README.md"); diff --git a/scripts/validate-plugin.mjs b/scripts/validate-plugin.mjs index 037a23e..26f4b23 100755 --- a/scripts/validate-plugin.mjs +++ b/scripts/validate-plugin.mjs @@ -10,7 +10,9 @@ import { fileURLToPath } from "node:url"; const root = resolve(dirname(fileURLToPath(import.meta.url)), ".."); // The plugin name pattern from cursor/plugins schemas/plugin.schema.json. const NAME = /^[a-z0-9]([a-z0-9.-]*[a-z0-9])?$/; -const SEMVER = /^\d+\.\d+\.\d+(?:[-+][0-9A-Za-z.-]+)?$/; +// The semver.org regular expression. +const SEMVER = + /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-((?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*)(?:\.(?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*))*))?(?:\+([0-9a-zA-Z-]+(?:\.[0-9a-zA-Z-]+)*))?$/; let errors = 0; @@ -40,17 +42,21 @@ if (typeof manifest.version !== "string" || !SEMVER.test(manifest.version)) { if (manifest.omp === null || typeof manifest.omp !== "object" || Array.isArray(manifest.omp)) { fail("package.json has no omp manifest, so OMP loads nothing from this package"); } else { - for (const [key, value] of Object.entries(manifest.omp)) { - if (!Array.isArray(value)) continue; - for (const entry of value) { - const path = resolve(root, entry); - if (relative(root, path).startsWith("..")) { - fail(`package.json omp.${key} entry "${entry}" points outside the package`); - } else if (!existsSync(path)) { - fail(`package.json omp.${key} entry "${entry}" does not exist`); - } + // OMP reads paths from string and array fields, feature entries included, and documents no field list, so check + // every relative path anywhere in the manifest. + const checkPaths = (value, at) => { + if (typeof value === "string") { + if (!/^\.\.?\//.test(value)) return; + const path = resolve(root, value); + if (relative(root, path).startsWith("..")) fail(`package.json ${at} "${value}" points outside the package`); + else if (!existsSync(path)) fail(`package.json ${at} "${value}" does not exist`); + } else if (Array.isArray(value)) { + value.forEach((entry, index) => checkPaths(entry, `${at}[${index}]`)); + } else if (value !== null && typeof value === "object") { + for (const [key, entry] of Object.entries(value)) checkPaths(entry, `${at}.${key}`); } - } + }; + checkPaths(manifest.omp, "omp"); } if (errors > 0) { diff --git a/scripts/verify.mjs b/scripts/verify.mjs index aab2f79..0d5a01f 100644 --- a/scripts/verify.mjs +++ b/scripts/verify.mjs @@ -29,7 +29,7 @@ function frontmatter(source) { const skillDirs = (await readdir(skillsRoot, { withFileTypes: true })).filter((entry) => entry.isDirectory()).map((entry) => entry.name); const skillFiles = await filesUnder(skillsRoot); -const markdownFiles = [...skillFiles, ...(await filesUnder(agentsRoot))].filter((path) => path.endsWith(".md")); +const markdownFiles = [...skillFiles, ...(await filesUnder(agentsRoot)), join(root, "README.md")].filter((path) => path.endsWith(".md")); for (const name of skillDirs) { const path = join(skillsRoot, name, "SKILL.md"); From 65ec88ca39c16dd49650ef3cb5ba13179387ec8e Mon Sep 17 00:00:00 2001 From: chen <23054115+cwkang1998@users.noreply.github.com> Date: Mon, 16 Nov 2026 05:54:15 +0700 Subject: [PATCH 3/3] fix(ci): check OMP's manifest path fields and keep docs-failure sync PRs in draft validate-plugin checks extensions, skills, tools, hooks, and commands at the top level and in each feature, whatever the path's spelling, so bare and absolute paths no longer slip through. The sync workflow puts the whole docs-check log in the PR body, so a checker crash with no FAIL lines still opens the PR, and uses always-true so an existing sync PR also returns to draft. --- .github/workflows/upstream-sync.yml | 6 +++--- scripts/validate-plugin.mjs | 28 ++++++++++++++++------------ 2 files changed, 19 insertions(+), 15 deletions(-) diff --git a/.github/workflows/upstream-sync.yml b/.github/workflows/upstream-sync.yml index cda8c47..9633600 100644 --- a/.github/workflows/upstream-sync.yml +++ b/.github/workflows/upstream-sync.yml @@ -72,10 +72,10 @@ jobs: echo "before opening a pull request when they conflict." if [ "${{ steps.docs.outcome }}" = failure ]; then echo - echo "README.md does not match the synced tree yet. Fix these on this branch before merging:" + echo "The docs check failed. Fix README.md on this branch before merging:" echo echo '```text' - grep '^FAIL' "$RUNNER_TEMP/docs-check.txt" + cat "$RUNNER_TEMP/docs-check.txt" echo '```' fi } > "$RUNNER_TEMP/pr-body.md" @@ -86,6 +86,6 @@ jobs: commit-message: "chore: sync upstream pstack" title: "chore: sync upstream pstack" body-path: ${{ runner.temp }}/pr-body.md - draft: ${{ steps.docs.outcome == 'failure' }} + draft: ${{ steps.docs.outcome == 'failure' && 'always-true' || 'false' }} branch: automation/upstream-pstack delete-branch: true diff --git a/scripts/validate-plugin.mjs b/scripts/validate-plugin.mjs index 26f4b23..9fa7114 100755 --- a/scripts/validate-plugin.mjs +++ b/scripts/validate-plugin.mjs @@ -42,21 +42,25 @@ if (typeof manifest.version !== "string" || !SEMVER.test(manifest.version)) { if (manifest.omp === null || typeof manifest.omp !== "object" || Array.isArray(manifest.omp)) { fail("package.json has no omp manifest, so OMP loads nothing from this package"); } else { - // OMP reads paths from string and array fields, feature entries included, and documents no field list, so check - // every relative path anywhere in the manifest. - const checkPaths = (value, at) => { - if (typeof value === "string") { - if (!/^\.\.?\//.test(value)) return; - const path = resolve(root, value); - if (relative(root, path).startsWith("..")) fail(`package.json ${at} "${value}" points outside the package`); - else if (!existsSync(path)) fail(`package.json ${at} "${value}" does not exist`); - } else if (Array.isArray(value)) { - value.forEach((entry, index) => checkPaths(entry, `${at}[${index}]`)); - } else if (value !== null && typeof value === "object") { - for (const [key, entry] of Object.entries(value)) checkPaths(entry, `${at}.${key}`); + // The manifest fields OMP resolves to files or directories, at the top level and in each optional feature. + const PATH_FIELDS = ["extensions", "skills", "tools", "hooks", "commands"]; + const checkPaths = (fields, at) => { + for (const field of PATH_FIELDS) { + if (fields[field] === undefined) continue; + const entries = Array.isArray(fields[field]) ? fields[field] : [fields[field]]; + entries.forEach((entry, index) => { + const label = `${at}.${field}${Array.isArray(fields[field]) ? `[${index}]` : ""}`; + if (typeof entry !== "string") return fail(`package.json ${label} is not a path`); + const path = resolve(root, entry); + if (relative(root, path).startsWith("..")) fail(`package.json ${label} "${entry}" points outside the package`); + else if (!existsSync(path)) fail(`package.json ${label} "${entry}" does not exist`); + }); } }; checkPaths(manifest.omp, "omp"); + for (const [name, feature] of Object.entries(manifest.omp.features ?? {})) { + if (feature !== null && typeof feature === "object") checkPaths(feature, `omp.features.${name}`); + } } if (errors > 0) {