From 0df9f5f2bc54bee720f2dc312bafda97bf0778b1 Mon Sep 17 00:00:00 2001 From: 3metaJun <251347867+3metaJun@users.noreply.github.com> Date: Tue, 6 Oct 2026 12:37:27 +0800 Subject: [PATCH 1/3] feat(upstream): sync pstack to 2cbf585 Move the pstack pin from f5bdd68 to 2cbf585 as a selective port. - Add benchmark-checklist, correct, principle-explain-the-number, and meta-help (upstream poteto-help, rewritten without Cursor commands). - Port architect red flags, fresh subagents, the hourly autopilot tick, perf mantras, PR heading format, swarm SHA briefs, and the guide refresh. - Keep a durable program objective in the autopilots and the multi-phase plan. - Route meta-agent to fresh agents per task, with a consistency test. - Refresh upstream and skill baselines, README counts, and notices. Co-Authored-By: Claude Sonnet 5.5 --- .github/workflows/validate.yml | 2 +- README.md | 15 +- THIRD_PARTY_NOTICES.md | 8 +- agents/meta-agent.md | 2 +- docs/guide/01-setup.md | 17 +- docs/guide/02-meta-mode.md | 41 +++- docs/guide/03-understand.md | 30 ++- docs/guide/04-design.md | 52 +++++ docs/guide/05-build-and-clean.md | 8 + docs/guide/06-verify-and-ship.md | 53 ++++- docs/guide/07-overnight.md | 43 +++- docs/guide/08-principles.md | 9 +- docs/guide/09-make-it-yours.md | 37 +++- docs/guide/10-recipes-and-pitfalls.md | 64 +++++- docs/guide/README.md | 20 +- docs/skill-integrity.md | 2 +- docs/upstream-sync-2cbf585.md | 67 ++++++ profiles/skill-manifest.json | 154 ++++++++----- profiles/skills.json | 4 + profiles/upstream-manifest.json | 204 ++++++++++-------- profiles/upstreams.json | 49 ++++- scripts/agent-format.test.mjs | 13 ++ skills/architect/SKILL.md | 2 +- .../architect/references/design-red-flags.md | 24 +++ skills/benchmark-checklist/SKILL.md | 39 ++++ skills/correct/SKILL.md | 31 +++ skills/how/references/explorer-prompt.md | 2 +- skills/meta-help/SKILL.md | 144 +++++++++++++ skills/meta-help/references/prompting.md | 51 +++++ skills/meta-help/references/recipes.md | 47 ++++ skills/meta-mode/SKILL.md | 8 +- skills/meta-mode/playbooks/autopilot-full.md | 10 +- skills/meta-mode/playbooks/autopilot-stack.md | 6 +- skills/meta-mode/playbooks/hillclimb.md | 4 +- .../meta-mode/playbooks/multi-phase-plan.md | 10 +- skills/meta-mode/playbooks/opening-a-pr.md | 23 +- skills/meta-mode/playbooks/perf-issue.md | 21 +- skills/principle-explain-the-number/SKILL.md | 22 ++ skills/swarm/SKILL.md | 2 +- skills/technical-writing/SKILL.md | 8 - .../references/patterns.md | 33 +-- tools/meta-mode/check-plan.mjs | 5 +- tools/meta-mode/check-plan.test.mjs | 9 + 43 files changed, 1137 insertions(+), 258 deletions(-) create mode 100644 docs/upstream-sync-2cbf585.md create mode 100644 skills/benchmark-checklist/SKILL.md create mode 100644 skills/correct/SKILL.md create mode 100644 skills/meta-help/SKILL.md create mode 100644 skills/meta-help/references/prompting.md create mode 100644 skills/meta-help/references/recipes.md create mode 100644 skills/principle-explain-the-number/SKILL.md diff --git a/.github/workflows/validate.yml b/.github/workflows/validate.yml index 11cbbd7..dfcc3df 100644 --- a/.github/workflows/validate.yml +++ b/.github/workflows/validate.yml @@ -45,7 +45,7 @@ jobs: - uses: actions/checkout@fbc6f3992d24b796d5a048ff273f7fcc4a7b6c09 # v5 with: repository: cursor/plugins - ref: f5bdd6826fd0a0d9cbc4347134c3a74a200b9d9d + ref: 2cbf58508f40de470d7490b55c51d71241928fa2 path: .upstream/cursor-plugins sparse-checkout: pstack - uses: actions/checkout@fbc6f3992d24b796d5a048ff273f7fcc4a7b6c09 # v5 diff --git a/README.md b/README.md index 0862234..1c35bfc 100644 --- a/README.md +++ b/README.md @@ -67,7 +67,7 @@ claude plugin install mstack@mstack Plugin skills are namespaced, for example `/mstack:meta-mode`, and the agents appear as `mstack:meta-agent` and `mstack:comment-reviewer`. Run `claude plugin details mstack` to see the inventory and its projected token -cost; the 50 skill descriptions add about 3,000 tokens to every session. +cost; the 54 skill descriptions add about 3,200 tokens to every session. `claude plugin marketplace update mstack` picks up new releases, because the plugin `version` tracks the npm version. @@ -420,7 +420,7 @@ target directory and restores backups if a commit fails. ## Included skills -The current bundle contains 50 skills. It includes the 47 entries in the +The current bundle contains 54 skills. It includes the 51 entries in the portable pstack tree and three skills adapted from `mattpocock/skills`: - Engineering principles for boundaries, domain modelling, idempotence, @@ -431,10 +431,15 @@ portable pstack tree and three skills adapted from `mattpocock/skills`: workflow. - `meta-mode` for routing a multi-step task through the capabilities available in the current harness. +- `meta-help` for answering questions about setup and which skill fits, + invoked as `/meta-help`. +- `benchmark-checklist` and `correct` for vetting a measured number and for + fixing repeated agent mistakes at the repository level. The bundle includes the pstack workflow and principle names. `meta-mode` is the -portable replacement for pstack's `poteto-mode`; it describes capabilities and -uses the current harness's adapter instead of naming one vendor's commands. +portable replacement for pstack's `poteto-mode`, and `meta-help` replaces +`poteto-help`. They describe capabilities and +use the current harness's adapter instead of naming one vendor's commands. Run `node scripts/validate.mjs` to print the validated skill count. @@ -465,7 +470,7 @@ To check the complete skill trees against both pinned upstreams, run: npm run skill-baseline -- --check --source /path/to/pstack --matt-source /path/to/mattpocock-skills ``` -This checks every file in all 50 skill trees, including references, playbooks, +This checks every file in all 54 skill trees, including references, playbooks, and scripts. It also checks tools moved out of skill directories. Local additions and intentional upstream omissions are recorded explicitly. Both source checkouts must be clean and at their pinned commits. `npm test` checks diff --git a/THIRD_PARTY_NOTICES.md b/THIRD_PARTY_NOTICES.md index e4cff5b..4f57033 100644 --- a/THIRD_PARTY_NOTICES.md +++ b/THIRD_PARTY_NOTICES.md @@ -5,7 +5,7 @@ The skills in this repository are adapted from the `pstack` plugin in [`cursor/plugins`](https://github.com/cursor/plugins/tree/main/pstack/skills), with the current complete snapshot pinned at commit -[`7366ac128bdf95f45e6734f412b49a4031800169`](https://github.com/cursor/plugins/commit/7366ac128bdf95f45e6734f412b49a4031800169). +[`2cbf58508f40de470d7490b55c51d71241928fa2`](https://github.com/cursor/plugins/commit/2cbf58508f40de470d7490b55c51d71241928fa2). The first port of selected skills was pinned at commit [`799151d91b6e12ee7dbd09f708eec108d7de9b3b`](https://github.com/cursor/plugins/commit/799151d91b6e12ee7dbd09f708eec108d7de9b3b). @@ -32,10 +32,11 @@ Adapted upstream skill names: - `principle-build-the-lever` The bundle also includes these principles from the current upstream tree, pinned -at commit [`7366ac128bdf95f45e6734f412b49a4031800169`](https://github.com/cursor/plugins/commit/7366ac128bdf95f45e6734f412b49a4031800169): +at commit [`2cbf58508f40de470d7490b55c51d71241928fa2`](https://github.com/cursor/plugins/commit/2cbf58508f40de470d7490b55c51d71241928fa2): - `principle-attack-the-premise` - `principle-encode-lessons-in-structure` +- `principle-explain-the-number` - `principle-exhaust-the-design-space` - `principle-experience-first` - `principle-foundational-thinking` @@ -53,7 +54,8 @@ These files use portable capability names. They do not copy the upstream Cursor-only commands or paths. The remaining pstack workflow skills are included under their original names. -The portable bundle renames `poteto-mode` to `meta-mode` and `poteto-agent` to +The portable bundle renames `poteto-mode` to `meta-mode`, `poteto-help` to +`meta-help`, and `poteto-agent` to `meta-agent`. The source inventory is recorded in `profiles/skills.json`. Source commits and renames are recorded in `profiles/upstreams.json`. The non-skill upstream artifacts are retained as follows: diff --git a/agents/meta-agent.md b/agents/meta-agent.md index 4182e2f..10049f2 100644 --- a/agents/meta-agent.md +++ b/agents/meta-agent.md @@ -1,6 +1,6 @@ --- name: meta-agent -description: Routing target for `/meta-mode` and requests for the mstack workflow. Resume an existing `meta-agent` for the conversation rather than spawning a sibling. Read the `meta-mode` skill's `SKILL.md` in full before any work, including its playbook map. +description: Routing target for `/meta-mode` and requests for the mstack workflow. Spawn a fresh `meta-agent` for each new task, and resume one only when the new work needs state that lives in that agent, such as its local checkout, its uncommitted changes, or a process it still runs, as meta-mode's Subagents section lists. Read the `meta-mode` skill's `SKILL.md` in full before any work, including its playbook map. --- # Meta subagent diff --git a/docs/guide/01-setup.md b/docs/guide/01-setup.md index fa40e47..86c417f 100644 --- a/docs/guide/01-setup.md +++ b/docs/guide/01-setup.md @@ -21,7 +21,7 @@ Run: /setup-mstack ``` -[`/setup-mstack`](../../skills/setup-mstack/SKILL.md) detects the models you have access to, shows you each role (code delegates, judgment, the review panels), and asks what you want. Answer the questions. It writes `~/.config/mstack/models.json`, the portable configuration every mstack skill reads. +[`/setup-mstack`](../../skills/setup-mstack/SKILL.md) detects the models you have access to, asks for a reasoning budget, shows you each role (code delegates, judgment, the review panels), and asks what you want. Answer the questions. It writes `~/.config/mstack/models.json`, the portable configuration every mstack skill reads. You only override what you care about. To restore a role to the parent chat model, set it to `inherit-parent` or run `/setup-mstack` again. Setup preserves other choices and Harness overrides. @@ -33,10 +33,21 @@ At the end of setup, `/setup-mstack` looks for a shared verification contract, a If it finds neither a reusable verification workflow nor a repository driver, setup offers once to run [`/create-verification-skill`](../../skills/create-verification-skill/SKILL.md). When you accept, the generator writes `.harness/verify//contract.md`, its feature map, and thin discovery wrappers. It proves one feature in the real app before handing over the result. Model setup alone does not start the app or create a team policy. -You can run `/create-verification-skill` yourself any time. [Verify and ship](./06-verify-and-ship.md#create-a-project-verification-skill) covers the proof. For a team using both native pstack and mstack, follow [the mixed-Harness adoption guide](./11-mixed-harness.md) to add the shared project workflow and CI checks. +Say no and setup moves on. You can run `/create-verification-skill` yourself any time. [Verify and ship](./06-verify-and-ship.md#create-a-project-verification-skill) covers the proof. For a team using both native pstack and mstack, follow [the mixed-Harness adoption guide](./11-mixed-harness.md) to add the shared project workflow and CI checks. + +If you're new to mstack, say yes. An agent that can check its own work keeps going until the check passes. An agent that can't hands every result back to you to check by hand. Of everything in this guide, the verification skill pays off the most. After setup, start a new session. The model configuration applies to new sessions. +## Keep the cost in check + +mstack spends extra tokens on subagents and review panels. That's the price of the rigor. To spend fewer: + +- Rerun `/setup-mstack` and pick a smaller reasoning budget or cheaper models. A strong model in the main chat with cheaper, faster models in the code roles is a good split. +- Set a role to `inherit-parent` so it runs on the chat's own model. +- Shorten a panel list. Each entry runs one subagent. +- Save `/meta-mode` for work that needs rigor. A small, obvious edit doesn't. + ## Run your first task Pick something real but small, and describe it the way you'd describe it to a colleague: @@ -47,6 +58,6 @@ Pick something real but small, and describe it the way you'd describe it to a co Watch the todo list. Its first items are the matched playbook's steps copied in, the Feature playbook for this prompt. If `/meta-mode` skips a step, the step stays in the list with `skip: `, so you can see what it chose not to do. -From here you can type normal follow-ups. `/meta-mode` is sticky. It stays on for the conversation until you opt out by saying so. +From here you can type normal follow-ups. `/meta-mode` stays active for the current task and fades as the chat moves on. When it fades, start the next task with `/meta-mode`, or pin it for the whole chat if your Harness can pin a skill or mode. Mid-chat, "new task" makes it match a fresh playbook. Next: [Route work through `/meta-mode`](./02-meta-mode.md). diff --git a/docs/guide/02-meta-mode.md b/docs/guide/02-meta-mode.md index a538838..13f3838 100644 --- a/docs/guide/02-meta-mode.md +++ b/docs/guide/02-meta-mode.md @@ -37,6 +37,37 @@ You don't write a spec. You say what's wrong or what you want, plus anything you That's a Bug fix prompt. "repro first" is a real constraint, not politeness, and the playbook honors it. Watch the todo list fill with the Bug fix steps. A skipped step stays visible with `skip: `. +## What goes in a prompt + +A useful prompt carries up to five things, and each one fits in a sentence: + +- **The goal.** Say what's wrong, or what you want. +- **The done check.** It must be able to pass or fail. "Make it better" and "work on it for an hour" aren't checks. +- **The proof you want to see.** Ask for the real command output, a video of the flow, the stored value, or a before-and-after number. +- **What you already know.** A symptom, a repro step, a log line, or a link saves the agent a search. +- **The real constraints.** "repro first", "don't change any code yet", "zero behavior change", and "let me review before proceeding" each change what the agent does. + +Here's one prompt with all five: + +```text +/meta-mode the csv export drops its last row since yesterday's deploy. failing job id is 4812. repro first, then fix. done means the 60k-row fixture exports every row. show me the row counts before and after. +``` + +Two things are worth leaving out: + +- **The how.** Say what to achieve, and leave the agent room to find a better path than the one you'd pick. The same goes for a list of skills, covered in the pitfall below. +- **Your theory of the cause, at first.** A stated guess narrows the search to wherever you pointed. Let the agent restate the problem before you share your hunch. + +For a noisy report, such as a long thread or a vague bug, make the restatement the first step: + +```text +/meta-mode read this thread. restate the underlying issue in your own words, in plain english. don't change any code yet. +``` + +A misreading shows up in the restatement, before any code exists. Correct it there, and it costs you one message instead of one wrong fix. + +## Follow up short + When the conversation already carries the context, the prompt shrinks to almost nothing. All of these are enough: ```text @@ -51,7 +82,7 @@ continue keep going until done ``` -Short works because the mode is sticky and the playbook holds the structure. Your words carry the intent, and the skill carries the rigor. +Short works because the playbook holds the structure, and `/meta-mode` stays active for the current task. [Set up mstack](./01-setup.md#run-your-first-task) says what to do when it fades. Your words carry the intent, and the skill carries the rigor. ## Switch tasks with "new task" @@ -63,15 +94,17 @@ A long chat accumulates context from the last task. When you change subjects, sa "new task" tells `/meta-mode` to re-match rather than continue the prior playbook. "don't change any code yet" pins this one to Investigation. Without those two phrases, a mode mid-Feature tends to treat your question as the next feature step. -## Give parallel work its own worktree +## Give parallel work its own machine + +If you run several agents against one repository on one computer, they will fight over the working tree, the ports, and the build output. The cleanest isolation is a worker on its own machine or remote environment, when the active Harness offers one. Each gets its own branch, so it can install dependencies, run your app, and record the result without touching your machine. Ask the parent chat to hand the work to remote workers. -If you run several agents against one repository, they will fight over the working tree. Ask for isolation up front: +When the work has to stay local, ask for a worktree up front: ```text /meta-mode new task. branch off in a fresh worktree, then port the parser change there. ``` -Each task in its own branch and worktree means no agent stomps another's files. The [Opening a PR playbook](../../skills/meta-mode/playbooks/opening-a-pr.md) already works from a worktree for code changes, so mostly you only say this when a specific base or location matters. +Each task in its own branch and worktree means no agent stomps another's files. Worktrees cost disk and machine resources, so a laptop runs only a handful at once. The [Opening a PR playbook](../../skills/meta-mode/playbooks/opening-a-pr.md) already works from a worktree for code changes, so mostly you only say this when a specific base or location matters. Worktrees accumulate. When disk gets tight, ask: diff --git a/docs/guide/03-understand.md b/docs/guide/03-understand.md index f009465..49e8506 100644 --- a/docs/guide/03-understand.md +++ b/docs/guide/03-understand.md @@ -1,9 +1,21 @@ # Understand the code before changing it -Editing code you don't understand is how subtle regressions ship. mstack gives you four ways in. `/how` explains what the code does now. `/why` digs up the reasons it's shaped that way. `/teach` blends both into one explanation. `/recall` rebuilds your own recent context on a topic. +Editing code you don't understand is how subtle regressions ship, and that's as true for the agent as for you. Agents usually fail in one of two ways. They misread what you want, or they don't have the context to do the work right. [What goes in a prompt](./02-meta-mode.md#what-goes-in-a-prompt) handles the first. This page handles the second. + +mstack gives you four ways in. `/how` explains what the code does now. `/why` digs up the reasons it's shaped that way. `/teach` blends both into one explanation. `/recall` rebuilds your own recent context on a topic. Each one also makes the agent explain itself in words you can check. That's how you supervise an agent that may know the code better than you do. ![A detective studies a machine blueprint with a magnifying glass while robots fetch case files; the evidence board behind her links clues under /how and /why.](./images/understanding.jpg) +## Start with a read-only investigation + +When the cause is unclear, ask for findings, not a fix: + +```text +/meta-mode investigate why background jobs time out every few hours. give me what we know, what data you used, and your best hypotheses. don't change any code yet. +``` + +"don't change any code yet" routes this to the [Investigation playbook](../../skills/meta-mode/playbooks/investigation.md). It runs `/how`, adds `/why` for questions about motivation, and returns a cited explanation. For a choice between options, it returns a recommendation with a trade-offs table. Asking "what data you used" makes the agent separate its evidence from its guesses. When the findings point at a fix, start the fix as a new task. + ## Trace behavior with `/how` ```text @@ -30,13 +42,27 @@ The two compose naturally. `do why first then how` is a perfectly good prompt wh [`/teach`](../../skills/teach/SKILL.md) is for when a summary isn't enough. It runs `/how` and `/why`, for a small change maybe just one of them, and weaves the findings into a plain explanation that builds up diagram by diagram. The "convince me" framing is worth stealing. It turns the explanation into an argument you can poke at instead of a tour. +It works on the agent's own choices too: + +```text +/teach me why you implemented it this way and not with a queue. what did you trade off, and why? +``` + +Teaching helps the agent as much as you. An agent that has to explain its work must read the code and back each claim with evidence, instead of stating it confidently and moving on. + ## Rebuild your own context with `/recall` ```text /recall catch me up on the export work from last week ``` -[`/recall`](../../skills/recall/SKILL.md) mines your own recent chats plus the shared record (issues, prior fixes, errors still firing) and hands back a brief on where things stand and what's next. Use it when you're returning to a topic cold. If you want to resume one specific chat, that's the Session pickup playbook below, not `/recall`. +[`/recall`](../../skills/recall/SKILL.md) mines your own recent chats plus the shared record (issues, prior fixes, errors still firing) and hands back a brief on where things stand and what's next. Your old chats hold context that a fresh agent lacks, so start new work on an old topic by loading it first, then hand over the new input: + +```text +/recall my work on the virtualized list from yesterday, then read this bug report. +``` + +If you want to resume one specific chat, that's the Session pickup playbook below, not `/recall`. ## Take over prior work with Session pickup diff --git a/docs/guide/04-design.md b/docs/guide/04-design.md index 8af310c..af4e252 100644 --- a/docs/guide/04-design.md +++ b/docs/guide/04-design.md @@ -2,6 +2,8 @@ One attempt at a hard design locks in the first shape the model thought of. `/architect` settles types and boundaries before implementation. `/arena` runs several attempts at the same brief and merges the best parts. `/interrogate` has other models try to break the result. When the job is coverage rather than design synthesis, `/swarm` fans out slices or races and aggregates their results. +The two most common design mistakes are taking the agent's first design and polishing a plan that no code has tested. This page fixes both. You plan through code: prototypes answer the open questions, a README or tutorial sets the target, and the written plan comes last. + ![Three robots draft competing bridge models at their own tables under /architect, /arena, and /interrogate panels, while a judge robot with a clipboard inspects skeptically.](./images/design.jpg) ## Settle the shape with `/architect` @@ -18,6 +20,8 @@ By default it proceeds straight from the synthesized design into implementation. /architect with checkpoint. stop and show me before implementing. ``` +The design isn't sacred once code starts. If implementation shows the same workaround in unrelated places, or types that only compile with `any` or forced casts, `/architect` treats that as proof the design is wrong. It scraps the sketch and starts over instead of patching around it. + ## Fan out attempts with `/arena` ```text @@ -66,6 +70,52 @@ Reach for it when parallelism buys coverage or lets independent checks race. `/a Read the dismissals too. The lead is a pragmatic senior engineer, not an oracle, and you can override it. +## Prototype instead of debating + +Never take the first design. Ask for a few, and pick from evidence you can see: + +```text +/meta-mode prototype a few options for the new dropdown menu. take screenshots or videos for me to compare. +``` + +The [Prototype playbook](../../skills/meta-mode/playbooks/prototype.md) builds throwaway sketches in a scratch directory, puts the variants behind one switcher, drives each one, and captures screenshots or timings. It also works for behavior and algorithms, not just UI. Prototypes are planning with code. They let the agent answer its own open questions by running something instead of asking you, and they leave room for an option you wouldn't have thought of. + +The same idea scales up to a real design. Pair `/architect` with prototypes and keep a review gate: + +```text +/meta-mode we need rate limiting for external webhooks. /architect it first, and answer open questions with prototypes. let me review before proceeding. +``` + +Don't spend reviewers on an abstract plan. `/interrogate` belongs on a diff. Point adversarial review at a plan with no code behind it and the reviewers invent theoretical risks and edge cases that will never happen. Let prototypes settle the questions, then review what got built. + +## Write the README first for shared code + +For a package or API that other code will use, start with the doc a user would read: + +```text +/meta-mode write a tutorial for how i would use the new config package first. then /teach me why it beats the current one. +``` + +Writing the tutorial first forces the caller's view. You describe the API to a hypothetical user and work back to the implementation. The doc also becomes a concrete target the agent checks its own work against. Name [`/technical-writing`](../../skills/technical-writing/SKILL.md) when the doc itself matters, so a tutorial stays a tutorial instead of drifting into reference and explanation at once. + +## Plan after the design settles + +mstack has no planning skill, on purpose. When you do want a written plan, ask for it once the design is settled: + +```text +/meta-mode turn this design into a plan. small verifiable PRs, each with its own verification steps. +``` + +The [Multi-phase plan playbook](../../skills/meta-mode/playbooks/multi-phase-plan.md) settles any remaining open questions by prototype, then writes one section per PR, each ending in proof that the change works. A passing test suite alone doesn't count as that proof. The plan is the deliverable. The playbook doesn't implement it, and it names which execution playbook should run it next. + +For a migration, state the bar in the prompt: + +```text +/meta-mode plan the migration of our ui library to the new styling system. small verifiable PRs, each with visual regression checks. the result must match the original exactly, bugs included. +``` + +"bugs included" keeps the migration from quietly fixing things on the way, which would make the old and new output impossible to compare. For a project that spans many days, you can commit the plan to the repo for a while so other agents see the work in progress. Delete it when the work lands. + ## How much design work does a task deserve? You might be wondering whether every change needs this. No. Most changes need none of it. A rough ladder: @@ -74,7 +124,9 @@ You might be wondering whether every change needs this. No. Most changes need no - A change that crosses function boundaries or moves ownership earns `/architect`, which brings `/arena` with it. - A standalone decision where independent attempts would help, like naming, formats, or an algorithm, is `/arena` directly. - A coverage matrix, set of parallel checks, or race with declared arms is `/swarm`. +- An open question you could answer by running something, like a layout, a timing, or an approach, gets a prototype, not a debate. - A contested design that's expensive to reverse gets `/architect`, then `/interrogate` before shipping. +- Work that spans several PRs gets a plan, written after the design settles. `/meta-mode` already applies this ladder. Boundary-crossing work triggers `/architect` on its own, so you reach for these directly mainly when you want more or less scrutiny than the default. diff --git a/docs/guide/05-build-and-clean.md b/docs/guide/05-build-and-clean.md index 3584869..05551e2 100644 --- a/docs/guide/05-build-and-clean.md +++ b/docs/guide/05-build-and-clean.md @@ -32,6 +32,14 @@ Each of these routes to its playbook ([Bug fix](../../skills/meta-mode/playbooks For sustained improvement of one number, there's the [Hillclimb playbook](../../skills/meta-mode/playbooks/hillclimb.md). Give it the metric, a target, and a floor on attempts, and it loops one hypothesis at a time with a frozen measurement harness. It keeps wins and reverts everything else. +Both perf playbooks run [`/benchmark-checklist`](../../skills/benchmark-checklist/SKILL.md) on their numbers. Perf issue vets its baseline and every number after it, and Hillclimb vets its harness before freezing it. [Verify and ship](./06-verify-and-ship.md#vet-a-measured-number-with-benchmark-checklist) shows when to type it yourself. + +Sometimes you want the cause before any fix. For a live symptom, such as a leak, an idle CPU spin, or a visual glitch, the [Runtime forensics playbook](../../skills/meta-mode/playbooks/runtime-forensics.md) instruments the running process. For a profile you already captured, the [Trace forensics playbook](../../skills/meta-mode/playbooks/trace-forensics.md) reads the artifact and maps the hot frame to source. Both return a diagnosis, not a fix: + +```text +/meta-mode here's a cpuprofile from the slow startup. tell me where the time goes and which source lines own it. no fix yet. +``` + ## Write the failing test first with `/tdd` When a bug has a cheap local test path, the whole prompt can be two words: diff --git a/docs/guide/06-verify-and-ship.md b/docs/guide/06-verify-and-ship.md index 457ea79..f9e407c 100644 --- a/docs/guide/06-verify-and-ship.md +++ b/docs/guide/06-verify-and-ship.md @@ -1,6 +1,8 @@ # Verify the result and open a PR -"It compiles" is not evidence. The [Prove It Works principle](../../skills/principle-prove-it-works/SKILL.md) makes the agent check the real artifact before it reports success, and your job is to make "the real artifact" checkable. This page covers stating a finish condition, generating a verification skill for your app, opening the PR, and driving it to merged. +"It compiles" is not evidence. The [Prove It Works principle](../../skills/principle-prove-it-works/SKILL.md) makes the agent check the real artifact before it reports success, and your job is to make "the real artifact" checkable. This page covers stating a finish condition, vetting a measured number, generating a verification skill for your app, opening the PR, and driving it to merged. + +Verification is the slowest step in most agent work, because it's the step that usually waits on a human. Make the agent able to do it, and you stop being the bottleneck. Skip it, and running more agents only gets you more unchecked work to review. ![A prototype plane flies a real test course while she times it with a stopwatch and robots film and checklist the run; the terminal reads verify: pass, evidence: captured.](./images/verification.jpg) @@ -17,13 +19,35 @@ Now the agent has three checks it can run, not a mood to satisfy. When the reply Match the check to the change: - A CLI change runs the real command. -- A UI change walks the changed flow in the running app. +- A UI change walks the changed flow in the running app. When it must match a reference pixel for pixel, the [Visual parity playbook](../../skills/meta-mode/playbooks/visual-parity.md) diffs screenshots against a frozen baseline instead of judging by eye. - A parser or migration replays a saved input. - A perf change compares before and after profiles. - A storage change reads back the written value. +Ask for the proof as an artifact you can inspect yourself: the failing test and then the passing one, a before-and-after video, the trace, the screenshot. If the fix already merged, ask for the same check again on main. An artifact beats a plausible explanation, because you can challenge it without replaying the whole run. + For a small diff you don't fully trust, [`/blast-radius`](../../skills/blast-radius/SKILL.md) finds what it could break elsewhere. It picks the one fact the change is safe because of and proves it by running code instead of writing an essay about it. +## Vet a measured number with `/benchmark-checklist` + +A before-and-after number is the easiest evidence to get wrong by accident. A warm cache, a debug build on one side, or work that never ran inside the timed region can each produce a convincing speedup. Before you report or act on a number, type: + +```text +/benchmark-checklist vet the export speedup before it goes in the pr +``` + +[`/benchmark-checklist`](../../skills/benchmark-checklist/SKILL.md) asks seven questions and wants evidence from a run for each: + +1. What limits the number, and why isn't it double? +2. Did every side run tuned the way production runs? +3. Does the result break a physical limit, like disk bandwidth or core count? +4. Did anything error or return wrong output? +5. Does it reproduce over alternating runs, with a median and a range? +6. Does it matter end to end, on the path a user waits on? +7. Did the work actually happen inside the timed region? + +The verdict comes back as faster, slower, no measurable difference, or inconclusive, with the run count, range, and limiter. It says inconclusive when it can't name the limiter or a side ran untuned. `/meta-mode` already runs the checklist inside the Perf issue and Hillclimb playbooks, so you type it yourself when you measured something outside them, or when someone else's number looks too good. It's the working form of the [Explain the Number principle](../../skills/principle-explain-the-number/SKILL.md). + ## Create a project verification skill The UI bullet above hides a real requirement. The agent needs a scripted way to drive your app. If your project has one, great. If not, run: @@ -40,11 +64,32 @@ The generator then renders thin `verify-` wrappers for the configured Harne Before handing over the result, the generator launches an isolated instance, runs Doctor, drives one feature, captures evidence, and cleans up. The evidence must survive cleanup. One successful feature does not prove every mapped path or every Harness. A missing required capability remains a reported gap. -A [`/swarm`](../../skills/swarm/SKILL.md) can split a full pass by feature-map entry. Give concurrent drivers separate instances, ports, and data directories. When the app cannot isolate them, keep one coordinator driving serially. +From then on, "verify it in the app" is a step any agent can execute, in this repo, with no setup conversation. Name it in the prompt when you want the proof in a specific form: + +```text +/meta-mode build the bulk-archive action. use /verify- to verify your changes and show me a video and screenshots as proof. +``` + +```text +/meta-mode repro this with /verify-. if it repros on main, fix it and show me a video as proof. +``` + +Once the verify skill works, a [`/swarm`](../../skills/swarm/SKILL.md) can split a full pass by feature-map entry and aggregate the results. Give concurrent drivers separate instances, ports, and data directories. When the app cannot isolate them, keep one coordinator driving serially. A swarm of verifiers also confirms a perf win over a big enough sample, or fuzzes the app for regressions before a PR ships. + +Treat the verification skill as infrastructure, not a one-off. Commit it, so every person and every agent on the team drives the app the same way. Then [build the lever](../../skills/principle-build-the-lever/SKILL.md). When agents keep writing throwaway scripts to click through the app, ask for a small control CLI that the skill calls instead. Agents spend fewer tokens, and every run becomes repeatable. A CLI that agents use well has these traits: + +- A few composable commands, each doing real work, rather than many thin ones. +- A `--dry-run` option on anything destructive. +- Subcommands that reveal features gradually instead of all at once. +- Error messages that say what to do instead. +- Rich `--help` text. +- Machine-readable output, such as JSON. + +While you're there, make the dev setup repeatable too: seeded data, test users, and one command that brings the environment up the same way every time. ## Keep the verification skill honest -Apps change and feature maps rot. When yours drifts, run: +Apps change and feature maps rot. Run this at least once a day, ideally from a scheduled automation so nobody has to remember: ```text /maintain-verification-skill diff --git a/docs/guide/07-overnight.md b/docs/guide/07-overnight.md index 1f304d9..b98d900 100644 --- a/docs/guide/07-overnight.md +++ b/docs/guide/07-overnight.md @@ -1,9 +1,20 @@ # Run work while you sleep -This is the payoff for everything before it. An agent you can trust to verify its own work is an agent you can leave alone with a hard task. What makes that safe isn't hope. It's a checkable finish condition, an isolated worktree, and a decision log you audit in the morning. +This is the payoff for everything before it. An agent you can trust to verify its own work is an agent you can leave alone with a hard task. What makes that safe isn't hope. It's a checkable finish condition, an isolated worktree or remote worker, and a decision log you audit in the morning. ![She waves goodnight from the door while robots keep the factory running, one updating a DECISION LOG wall board under a BUILD LOOP ACTIVE sign.](./images/overnight.jpg) +## Earn the trust before the loop + +A loop you don't trust just produces unchecked work faster, and the mess compounds with every iteration. Before you leave one running, check that it has earned it: + +- You've done the task once by hand, or watched an agent do it, so you know what good looks like. +- The agent has the tools and signals you'd use yourself: the verification skill, the profiler, the logs. +- Every stage proves its work and can stop the line when the work misses the bar. +- You've read a few transcripts and turned the repeated failures into tools, skills, or checks. + +Make the loop autonomous only after all four hold. Until then, run it while you watch. + ## The overnight contract A good handoff has the goal, the finish condition, permissions, and an escape hatch. It doesn't need to be long: @@ -26,6 +37,8 @@ Walk through what each line buys you: Because you'll review this work after stepping away, `/meta-mode` routes it through [`/figure-it-out`](../../skills/figure-it-out/SKILL.md), which designs the run's phases before any code and wires in the decision log. +To stop a run on purpose, tell the agent to pause, or that you're about to go offline or restart the Harness. The [Pause safely playbook](../../skills/meta-mode/playbooks/pause-safely.md) finishes or backs out of the current step, commits a work-in-progress checkpoint, and writes a resume note. A fresh chat picks the work up from that note through the Session pickup playbook. Saying "keep going" never triggers a pause. + ## What the loop does all night ```mermaid @@ -58,7 +71,7 @@ Before the skill hands back its summary, it spawns a reviewer on a different mod The contract above drives one task to one finish condition. Some nights hold more, a queue of independent changes or a whole program. Three playbooks scale the same trust up. -[Autopilot-full](../../skills/meta-mode/playbooks/autopilot-full.md) runs a queue of independent PRs to merged. Each PR gets one owner agent that carries it from build through merge, and no owner merges on its own verdict. A swarm of fresh verifiers checks every merge-ready head, and only a clean verdict authorizes the merge: +[Autopilot-full](../../skills/meta-mode/playbooks/autopilot-full.md) runs a queue of independent PRs to merged. Each PR gets one owner agent that carries it from build through merge, and no owner merges on its own verdict. A swarm of fresh verifiers starts a round at the owner's code-ready head and again at every later push that changes the patch. Only a clean verdict on the patch that merges authorizes the merge: ```text /meta-mode full autopilot on this queue. each item is independent. i want them merged by morning. @@ -76,6 +89,32 @@ The contract above drives one task to one finish condition. Some nights hold mor /meta-mode orchestrate the store migration. own it until every package is converted and merged. i'll check in twice a day. ``` +## Run many projects in parallel + +A coordinator agent with a persistent thread, such as a Harness project or a long-lived session, directs subagents and doesn't write code itself. When the Harness runs subagents remotely, the work continues when your laptop is closed. That's the shape the Orchestrate playbook expects. Start your prompts to the coordinator with `/meta-mode`, and the subagents it spawns follow the playbooks. + +A few habits help: + +- Give each body of work its own coordinator thread, such as a feature, a migration, a perf push, or a tech-debt cleanup. Several can run side by side. +- Point the coordinator at related finished chats and notes. They become context for every agent under it. +- Give each PR a verification swarm before it merges, and let Autopilot-stack or Autopilot-full carry the queue. +- Ask the coordinator for a plan backed by data, and have it answer open questions with prototypes before it asks you. + +One prompt can carry a whole program, from research through execution: + +```text +/meta-mode refactor this repo so its architecture is more agent friendly. use /correct and /architect on past commits and review comments to find the mistakes agents make most here. use /recall for context from past chats. answer open questions with prototypes instead of asking me. come back with a plan backed by real data. once i approve it, run it with autopilot-stack or autopilot-full, and ask me which. +``` + +## Let loops start themselves + +Every loop above still waits for you to start it. A scheduled or event-driven automation removes that step. Software maintenance splits into stages that suit this well: triage a report, reproduce it, fix it, verify the fix. Two rules keep such a line trustworthy: + +- Every stage can stop the line. Triage can decide the report is expected behavior, repro can fail to reproduce it, and the fixer can judge the change too risky. Each of those outcomes is useful, because it keeps bad work from reaching the next stage, where it costs more to undo. +- Every stage hands over evidence. Repro attaches screenshots and video of the broken state, and the fix attaches before-and-after proof. A human can then check that the agent fixed the right thing before reading a line of code. + +mstack ships this as a dormant [automation pack](../../automations/benny/README.md) for Slack issue reports. One automation triages each report. The other reproduces confirmed bugs and may prepare a small draft fix. Point an agent at its [`FOR_AGENTS.md`](../../automations/benny/FOR_AGENTS.md) and name the target repository to set it up. + **Pitfall:** a duration is not a finish condition. "work on this for 4 hours" gives the agent nothing to check, and you'll wake up to four hours of motion instead of a result. Give the loop a predicate that can pass or fail. Next: [Steer with principle names](./08-principles.md). diff --git a/docs/guide/08-principles.md b/docs/guide/08-principles.md index 9d4e918..03f9d5d 100644 --- a/docs/guide/08-principles.md +++ b/docs/guide/08-principles.md @@ -1,6 +1,6 @@ # Steer with principle names -mstack ships 23 principles as individual skills. `/meta-mode` reads their index at the start of every multi-step task, applies the ones the task triggers, and names each applied principle in its reply along with the decision it changed. +mstack ships 24 principles as individual skills. `/meta-mode` reads their index at the start of every multi-step task, applies the ones the task triggers, and names each applied principle in its reply along with the decision it changed. You don't invoke principles. You use their names to steer. Each name points at a complete rule the agent has already read, so one phrase redirects the work more precisely than a paragraph of instructions. @@ -26,7 +26,7 @@ separate before serializing shared state. give each attempt its own worktree, no Each phrase lands because the rule behind it is specific. The agent still has to say, in its reply, which decision the rule changed. A principle citation with no decision behind it is the tell that it name-dropped instead of applying. -## The 23, briefly +## The 24, briefly The core principles decide how much to build and when to rethink the design: @@ -39,7 +39,7 @@ The core principles decide how much to build and when to rethink the design: - [Outcome-Oriented Execution](../../skills/principle-outcome-oriented-execution/SKILL.md) converges rewrites on the target design instead of preserving throwaway compatibility states. - [Experience First](../../skills/principle-experience-first/SKILL.md) chooses the user's result over implementation convenience. - [Exhaust the Design Space](../../skills/principle-exhaust-the-design-space/SKILL.md) builds two or three competing prototypes when there's no precedent. -- [Build the Lever](../../skills/principle-build-the-lever/SKILL.md) builds the script that does or proves the work, so a reviewer can rerun it. +- [Build the Lever](../../skills/principle-build-the-lever/SKILL.md) builds the script that does or proves the work, so a reviewer can rerun it. When an agent keeps doing the same thing by hand, have it write the tool or skill it wishes it had. If a script can do a step the same way every time, use the script, and save agents for the judgment calls. The architecture principles decide where state, validation, and compatibility live: @@ -56,6 +56,7 @@ The verification principles define what counts as proof: - [Fix Root Causes](../../skills/principle-fix-root-causes/SKILL.md) reproduces and traces to the cause before changing code. - [Sequence Work into Verifiable Units](../../skills/principle-sequence-verifiable-units/SKILL.md) ends each small unit in a check before starting the next. - [Test Behavior, Not Implementation](../../skills/principle-test-behavior-not-implementation/SKILL.md) calls the code the way its users do and asserts a literal expected value, and deletes a test that would still pass if every imported function returned `undefined`. +- [Explain the Number](../../skills/principle-explain-the-number/SKILL.md) names what limits a measured number and rules out that it measured something else, before anyone trusts or reports it. [`/benchmark-checklist`](../../skills/benchmark-checklist/SKILL.md) turns it into seven questions you answer from real runs. The delegation principles keep parallel work sane: @@ -64,7 +65,7 @@ The delegation principles keep parallel work sane: And one meta principle: -- [Encode Lessons in Structure](../../skills/principle-encode-lessons-in-structure/SKILL.md) turns advice you've repeated twice into a lint, check, or script. +- [Encode Lessons in Structure](../../skills/principle-encode-lessons-in-structure/SKILL.md) turns advice you've repeated twice into a lint, check, or script. [`/correct`](../../skills/correct/SKILL.md) applies it to a whole repo, as shown in [Make it yours](./09-make-it-yours.md#fix-the-environment-with-correct). Don't memorize the list. Skim it now, then come back when you catch the agent doing something a name here would have prevented. That's how the vocabulary sticks. diff --git a/docs/guide/09-make-it-yours.md b/docs/guide/09-make-it-yours.md index 5d4ebea..26b7ee9 100644 --- a/docs/guide/09-make-it-yours.md +++ b/docs/guide/09-make-it-yours.md @@ -1,6 +1,8 @@ # Make it yours -meta-mode is one person's style. The machinery underneath, playbooks, routing, model roles, works just as well wearing yours. This page covers generating a personal mode, capturing lessons from a session, authoring a focused skill, and testing a skill change before you trust it. +meta-mode is one person's style. The machinery underneath, playbooks, routing, model roles, works just as well wearing yours. This page covers generating a personal mode, capturing lessons from a session, fixing the repo so agents stop repeating mistakes, authoring a focused skill, and testing a skill change before you trust it. + +Start smaller than you think. You don't need many skills on day one, or even this whole plugin. Prompt plainly, watch where agents fail, and add a skill or a check when the same failure shows up twice. ## Generate your own mode with `/automate-me` @@ -28,6 +30,25 @@ Right after a task that taught you something, run: [`/reflect`](../../skills/reflect/SKILL.md) sends the transcript to three parallel reviewers, then a synthesizer sorts the proposals into `Accepted`, `Rejected`, and `Backlog` and waits for your approval before any skill changes. Approve a proposal only if it would change a future decision. One weird session is an anecdote, not a rule. +## Fix the environment with `/correct` + +When you correct agents for the same mistake again and again, the fix belongs in the repo, not in your next prompt. Rank the options by how well they hold: + +1. Make the mistake impossible with architecture or a better data structure. +2. Block it with types, or with a lint or CI check whose error names the fix. +3. Catch it with a test. +4. Write it down as a doc or agent rule. Nothing fails when an agent skips a rule, so this comes last. + +Human review isn't on the list. A reviewer who must catch the same mistake on every PR is the problem this fixes. [`/correct`](../../skills/correct/SKILL.md) does the work: + +```text +/correct agents keep calling the database client directly instead of going through the repository layer +``` + +It reads recent commits, reverts, review comments, and comments that explain workarounds, then groups the mistakes into classes. A class counts once it has happened twice. It fixes the most frequent classes one commit each, at the highest level that works, and proves each new check fails on a real past mistake. It also keeps a table in the agent instruction file that pairs each rule with what enforces it, so a rule that nothing enforces shows up as a repeat. The reply lists each class with its evidence, the level chosen, and why a higher level didn't work. + +Run it with no argument and it finds the classes from history on its own. `/reflect` and `/correct` split the work. `/reflect` improves skills from one session. `/correct` changes the repo so a mistake class can't come back. Pair it with `/architect` when the fix is a new boundary. [Run many projects in parallel](./07-overnight.md#run-many-projects-in-parallel) has a prompt that does both across a whole repo. + ## Author a focused skill When you already know the workflow you want to capture: @@ -52,16 +73,28 @@ Skills aren't the only prose you ship. For docs, RFCs, readmes, PR descriptions, ## Test a skill change blind -A skill edit affects every future session, so test it like the experiment it is: +A skill edit affects every future session, so test it like the experiment it is. The same goes for adopting someone else's skill. Check that it makes the agent better on your work before you keep it. ```text /meta-mode run the eval playbook on this skill change. same task for both variants, candidates stay blind. ``` +When a skill keeps missing and you know what it should do, change and test it in one task: + +```text +/meta-mode update the review skill so it flags missing migrations, and eval the change. +``` + +Asking for the eval up front keeps the edit honest. A fix written from one bad session tends to overfit that session, and over many edits the skill drifts. The eval catches the drift before it ships. + The [Eval playbook](../../skills/meta-mode/playbooks/eval.md) is built around one failure mode, the observer effect. An agent that knows it's being evaluated behaves differently. So candidate agents get an organic-looking task in sanitized directories, never the words "eval" or "candidate", and never each other's existence. One judge scores all outputs under neutral labels, and chain-following gets graded from which files each candidate actually read, not from what it claims. Read every output yourself before accepting the verdict. If you disagree with the judge, suspect the rubric before you suspect your judgment. +## Build a bot UI with `/make-bot-ui` + +One situational skill is for Grok Bot users. [`/make-bot-ui`](../../skills/make-bot-ui/SKILL.md) builds a small page whose buttons wake a bot over a webhook routine. For example, you could swipe through a review queue and have each swipe ask the bot to act on that item. A server on your machine holds the webhook's sender key, so the key never reaches the browser or the chat. The skill also covers exposing the page on Tailscale. + **Pitfall:** don't edit a skill mid-task because it's misbehaving. Fix it in its own PR and keep the task moving. A skill edit that ships tangled into feature work is invisible to review and impossible to evaluate. Next: [Recipes and pitfalls](./10-recipes-and-pitfalls.md). diff --git a/docs/guide/10-recipes-and-pitfalls.md b/docs/guide/10-recipes-and-pitfalls.md index 6477791..ff161b0 100644 --- a/docs/guide/10-recipes-and-pitfalls.md +++ b/docs/guide/10-recipes-and-pitfalls.md @@ -12,6 +12,30 @@ use /how first to understand how this initialization works. then use /why to fig Mechanics first, history second. Each skill's report tells you which sources it searched, so you know what the answer is grounded in. +## Restate a noisy report before touching code + +```text +/meta-mode read this thread. restate the underlying issue in your own words, in plain english. don't change any code yet. +``` + +A misreading shows up in the restatement, where it costs one message to correct. Keep your own theory to yourself until the agent has stated its own. + +## Prototype before you pick + +```text +/meta-mode prototype a few options for the settings layout. put them behind a switcher and send me screenshots of each. +``` + +You pick from things that run, not from descriptions. The agent answers its own layout and timing questions along the way. + +## Turn a settled design into a plan + +```text +/meta-mode turn this design into a plan. small verifiable PRs, each with its own proof. +``` + +Ask only after the design settles. The plan is the deliverable, and it names the playbook that will execute it. + ## Get a second opinion on a design ```text @@ -44,6 +68,38 @@ The qualifiers do real work. "don't change anything yet" keeps it read-only, and "if there's a cheap test path" matters. Forcing a test through brittle mocks proves less than running the real command, and the playbook is allowed to say so. +## Repro and fix a report with proof + +```text +/meta-mode repro this with /verify-. if it repros on main, fix it and show me a video as proof. +``` + +"if it repros on main" lets the run stop early when the bug is already gone. The video lets you check the fix before you read the diff. + +## Vet a number before you post it + +```text +/benchmark-checklist vet this 40% speedup before it goes in the pr description +``` + +You get faster, slower, no measurable difference, or inconclusive, with the run count, the range, and what limits the number. + +## Stop correcting the same mistake + +```text +/correct agents keep adding new config flags without registering them in the schema +``` + +The fix lands in the repo as architecture, a type, a lint, or a test, so the next agent can't make the mistake. + +## Ask how without starting the work + +```text +/meta-help how do i pick a model for each role? +``` + +You get an answer, a prompt to send, and a link to the source. Nothing runs until you send that prompt. + ## Keep a run honest while you're away ```text @@ -82,7 +138,13 @@ That's the whole prompt. [`/bro`](../../skills/bro/SKILL.md) restates the last m - **Enumerating skills in the prompt.** "use /how then /architect then /arena" reorders steps the playbook already sequences. State the goal and constraints. Name a skill only to override a default. - **A vague finish condition.** "make it better" gives `/loop` nothing to check. Give a command or artifact that can pass or fail. -- **Parallel agents in one worktree.** They overwrite each other and the diff becomes archaeology. Say "own worktree per attempt" and the isolation is free. +- **Leading with your theory of the cause.** The agent searches wherever you pointed. Ask it to restate the problem first, then share your hunch. +- **Taking the first design.** One attempt locks in the first shape the model thought of. Ask for prototypes or `/architect` and pick from evidence. +- **Polishing an abstract plan.** Adversarial review of a plan with no code behind it invents risks that will never happen. Settle the open questions with prototypes, then review what got built. +- **Parallel agents in one worktree.** They overwrite each other and the diff becomes archaeology. Run them on separate machines, or say "own worktree per attempt". +- **Looping before you trust the loop.** A loop that can't verify its own work only makes unchecked work faster. Get the verification skill working first. +- **Trusting an unvetted number.** A warm cache or a skipped code path can fake a speedup. Run `/benchmark-checklist` before the number goes anywhere. +- **Correcting the same mistake by hand.** A correction in chat helps one run. `/correct` fixes the repo so no later run repeats it. - **Using `/arena` for coverage.** `/arena` repeats one design or code brief, then picks a base and grafts the best parts. `/swarm` partitions slices or declared race arms and aggregates one report. - **Accepting every review comment.** Bots and humans both file real catches and noise in one list. `/interrogate` sorts findings into act-on and dismissed buckets with reasons, and you can override either way. - **Treating `auto` as a model slug.** `auto` requests the Harness default; `inherit-parent` requests the chat model through documented native inheritance. A new CLI process needs `--parent-model ` to use the chat model. [Setup](./01-setup.md) covers the roles. diff --git a/docs/guide/README.md b/docs/guide/README.md index 2ef4495..a9bcd56 100644 --- a/docs/guide/README.md +++ b/docs/guide/README.md @@ -6,13 +6,13 @@ Here's what you'll learn: 1. [Set up mstack](./01-setup.md). Install the plugin and pick your models. 2. [Route work through `/meta-mode`](./02-meta-mode.md). Give it a goal and watch it pick a playbook. -3. [Understand the code](./03-understand.md). `/how`, `/why`, `/teach`, and `/recall` before you edit anything. -4. [Design the change](./04-design.md). `/architect`, `/arena`, `/swarm`, and `/interrogate` before code locks in a shape. +3. [Understand the code](./03-understand.md). A read-only investigation, then `/how`, `/why`, `/teach`, and `/recall` before you edit anything. +4. [Design the change](./04-design.md). `/architect`, `/arena`, `/swarm`, `/interrogate`, prototypes, and plans before code locks in a shape. 5. [Build and clean the change](./05-build-and-clean.md). The build playbooks, `/tdd`, `/unslop`, and `/no-comments`. -6. [Verify and ship](./06-verify-and-ship.md). Prove behavior on the real app, then open a focused PR and drive it to merged. -7. [Run work while you sleep](./07-overnight.md). An overnight contract, a decision log you can audit, and the playbooks that scale past one agent. -8. [Steer with principle names](./08-principles.md). The 23 names that redirect an agent mid-task. -9. [Make it yours](./09-make-it-yours.md). Your own mode, plus how to test a skill change. +6. [Verify and ship](./06-verify-and-ship.md). Prove behavior on the real app, vet numbers with `/benchmark-checklist`, then open a focused PR and drive it to merged. +7. [Run work while you sleep](./07-overnight.md). Trust before loops, an overnight contract, a decision log you can audit, and coordinator threads and automations that scale past one agent. +8. [Steer with principle names](./08-principles.md). The 24 names that redirect an agent mid-task. +9. [Make it yours](./09-make-it-yours.md). Your own mode, `/correct` for repeated mistakes, and how to test a skill change. 10. [Recipes and pitfalls](./10-recipes-and-pitfalls.md). Prompts to copy and mistakes to skip. 11. [Mix pstack and mstack in one repository](./11-mixed-harness.md). Share verification facts, isolate work, and check evidence across Harnesses. @@ -20,6 +20,14 @@ Here's what you'll learn: Read the pages in order the first time. After that, each page stands alone. +When you're stuck, or can't tell which skill fits, type [`/meta-help`](../../skills/meta-help/SKILL.md) with your question: + +```text +/meta-help which skill should i use to review this branch? +``` + +It answers, hands you a prompt to send, and links the skill or guide page the answer came from. It doesn't start the work, because an mstack run spends real tokens, so you send the prompt when you're ready. + ## If you only remember one thing Give the agent a goal and a way to check it, in your own words: diff --git a/docs/skill-integrity.md b/docs/skill-integrity.md index e76202a..5bb565e 100644 --- a/docs/skill-integrity.md +++ b/docs/skill-integrity.md @@ -42,7 +42,7 @@ lock. It leaves adapted content untouched. Artifact synchronization preserves its existing transaction behavior and never refreshes skill baselines. The earlier `canonicalSkills` block in `profiles/upstream-manifest.json` still -checks the 47 pstack entry documents. When changing one of those entries, update +checks the 51 pstack entry documents. When changing one of those entries, update that existing target digest in the same review. The new manifest covers the complete trees and the three Matt Pocock skills alongside that check. diff --git a/docs/upstream-sync-2cbf585.md b/docs/upstream-sync-2cbf585.md new file mode 100644 index 0000000..9144f3a --- /dev/null +++ b/docs/upstream-sync-2cbf585.md @@ -0,0 +1,67 @@ +# Upstream sync to pstack 2cbf585 + +The pstack pin moves from `f5bdd68` to +[`2cbf585`](https://github.com/cursor/plugins/commit/2cbf58508f40de470d7490b55c51d71241928fa2). +This is a selective port. mstack keeps its portable adapters, its role-based +model configuration, and its own autopilot policy. + +## Ported + +- New skills `benchmark-checklist` and `principle-explain-the-number`, which + vet a measured number before anyone reports or acts on it. `meta-mode` + triggers the checklist on a benchmark and indexes the principle. The Perf + issue and Hillclimb playbooks run it. +- New skill `correct`, which fixes repeated agent mistakes at the highest level + that works: architecture, types, lint, tests, then docs. +- New skill `meta-help` (upstream `poteto-help`) with its prompting and recipe + references. It was rewritten without Cursor commands, Custom Modes, or the + `pstack-models.mdc` rule. It points at the installer, `/setup-mstack`, + `~/.config/mstack/models.json`, and the Harness's own loop and pinning + features. Upstream's `poteto-help` is typed-only, which mstack cannot enforce + because its portable frontmatter has no way to disable model invocation. The + description is narrow instead, and the skill answers without starting work. +- `architect` assumes the next contributor is an agent, and + `design-red-flags.md` gains four red flags: split ownership, two ways to do + one task, importable internals, and a hand-synced list. +- Fresh subagents by default in `meta-mode`, a one-hour audit tick in the + autopilots and the multi-phase plan (`check-plan.mjs` pins it, with a new + test), an owner pushes after every verifiable unit, `children.tsv`, status + messages only for new tracked changes, and the full-autonomy wording for + decisions the grant covers. +- `agents/meta-agent.md` now tells callers to spawn a fresh agent per task, and a test keeps it consistent with `meta-mode`. +- Opening a PR: `##` section headings, a built-in PR tool first, and the + "Size and stacks" and "Readiness" wording. +- Perf issue replaces its eight strategy families with seven mantras tried in + order. Hillclimb orders hypotheses by them. +- `swarm` briefs name exact SHAs and measurement method, and a result without + them is respawned once, then recorded as a gap. A worker reports every + provable issue. +- `technical-writing` drops its fetch-date source lines. `typescript-best-practices` + takes the schema-first cast guidance. +- The upstream guide refresh for `/correct`, `/benchmark-checklist`, prompting + tips, `/meta-help`, and the 24 principles. The Cursor-specific wording is + rewritten through replacements in `profiles/upstreams.json`. The four guide + pages that carry mstack's mixed-Harness and verification-contract text were + merged by hand, and their reviewed digests are recorded in + `profiles/upstream-manifest.json`. + +## Not ported + +- Model slug and `pstack-models.mdc` changes in `arena`, `architect`, `how`, + `why`, `interrogate`, `reflect`, `setup-mstack`, and the `meta-mode` task + defaults. mstack reads roles from `~/.config/mstack/models.json`, and the + reasoning budget is already handled by `model-budget.mjs`. +- The `log.sh` header-append fix. mstack's Node logger already creates the file + exclusively. +- Prompt pruning that mstack's skills had already taken or rewrote, such as + `blast-radius`, `tdd`, `unslop`, and the five affected principles. +- Upstream's rule that lets an owner skip a second rebase when a later trunk move is textually clean and touches disjoint paths. Disjoint files can still break each other, so the owner rebases again and waits for CI. +- Upstream's removal of the `/goal` arm in Autopilot-full, Autopilot-stack, and the multi-phase plan. mstack is portable and relied on the goal for restart recovery, so on the operator's go the root writes the program objective (queue and order, verification rule, who merges, done condition) to `program.md` beside the decision trail, and to the Harness's goal mechanism when it has one. Every audit tick re-reads it with the playbook, and its done condition ends the recurring wake. `check-plan.mjs` pins the objective and has a test. +- `profiles/legacy-skill-digests.json`. It records released tags used to + recognize unmodified old installs and has no entry for a new skill. + +## Verification + +The repository tests cover packaging, inventory, link and frontmatter checks, +the `check-plan` cadence, and both source baselines. They do not show that a +model follows the new instructions. diff --git a/profiles/skill-manifest.json b/profiles/skill-manifest.json index 1dd8a6b..efbc5ce 100644 --- a/profiles/skill-manifest.json +++ b/profiles/skill-manifest.json @@ -1,15 +1,15 @@ { "version": 1, "sources": { - "pstack": "f5bdd6826fd0a0d9cbc4347134c3a74a200b9d9d", + "pstack": "2cbf58508f40de470d7490b55c51d71241928fa2", "mattpocock/skills": "6654f6b60cd9d5be8b54c6fafe44346dabeb3b76" }, "files": { "skills/architect/references/design-red-flags.md": { "upstream": "pstack", "source": "skills/architect/references/design-red-flags.md", - "sourceDigest": "905066f9bbac81c573c2b325be47751d2c0f9325e0a0772bd4384e82dafe9336", - "targetDigest": "905066f9bbac81c573c2b325be47751d2c0f9325e0a0772bd4384e82dafe9336" + "sourceDigest": "d0e639e4cc588ec865f930d3a4111faad60987ae36925917e319d7ceca7c69ce", + "targetDigest": "d0e639e4cc588ec865f930d3a4111faad60987ae36925917e319d7ceca7c69ce" }, "skills/architect/references/rationale-template.md": { "upstream": "pstack", @@ -26,13 +26,13 @@ "skills/architect/SKILL.md": { "upstream": "pstack", "source": "skills/architect/SKILL.md", - "sourceDigest": "897a59beaa3cab107d98c256206e062cc4a5e9421a45b9d462fbded19291fea5", - "targetDigest": "cc8a035aa7a2aa417676c4e364b86f4a3e2b85748bf2d0916402105b011a1083" + "sourceDigest": "741901140ee382ebf93263a7ed03c6ee3719e578416d81afcd195876fa16c496", + "targetDigest": "76c299297a79236fa519d401716a6ad1845ecc1a3f4fdff2aa052309261651aa" }, "skills/arena/SKILL.md": { "upstream": "pstack", "source": "skills/arena/SKILL.md", - "sourceDigest": "8d431f7b1aa19daf6300366fc876c4d1aadac06417ec5502407345ffaf4e90d9", + "sourceDigest": "e3a1f6c49a08b7e0b92134e53300d146f1f22ba83386d2019926e736df421851", "targetDigest": "f100383e190b806567015d2cbbaf90b9a1b0151ae60b08aa6185fc6eca3c9552" }, "skills/automate-me/SKILL.md": { @@ -41,10 +41,16 @@ "sourceDigest": "1510979b0b71b54284427a19c09918f8b1fdfc168f9b7f9e30098793a5ec88ef", "targetDigest": "6ab6c4c4a4b50a7cb182149408bd1758229d4386fbb8b1a66cf6927847b02c27" }, + "skills/benchmark-checklist/SKILL.md": { + "upstream": "pstack", + "source": "skills/benchmark-checklist/SKILL.md", + "sourceDigest": "6a767e788a60428fa14e645ee10fe2e49896e514ff654f668b1d824deb9038e8", + "targetDigest": "3fc701eecd146557b75c0e7d26929ca5d5469632def12ef032109710ae23c1c0" + }, "skills/blast-radius/SKILL.md": { "upstream": "pstack", "source": "skills/blast-radius/SKILL.md", - "sourceDigest": "20cb2945f5fe62055166f745107274af5f19428ca033e53a9b8bc69650d3ded1", + "sourceDigest": "5f02db9101ccf26c20254718f0fcd5c2c7ac5d4292b0e0923d0944ac47237aff", "targetDigest": "72113714dc5e7ef634a8b220e3a8dacea7b0e82d1f24136c13e04013749ef41a" }, "skills/bro/SKILL.md": { @@ -73,6 +79,12 @@ "sourceDigest": "2c20617f87ec8af6a434859f381b2f061a69b530444e74eb39e78bb016a6d1e2", "targetDigest": "2033d2660df023eddc9a72d840daf997bbbe15e9e768228948dbde906e03cf80" }, + "skills/correct/SKILL.md": { + "upstream": "pstack", + "source": "skills/correct/SKILL.md", + "sourceDigest": "bf482bacc972b3f124a4af8bf9364b4b3e280cb5845e44c326ea4f4565e5c904", + "targetDigest": "b7af9686e96f242ddd7d0c12731dd8c4347f4eff1c6d404dc87403d87076d492" + }, "skills/create-verification-skill/references/feature-map-example/create-note.md": { "upstream": "pstack", "source": "skills/create-verification-skill/references/feature-map-example/create-note.md", @@ -127,7 +139,7 @@ "skills/figure-it-out/SKILL.md": { "upstream": "pstack", "source": "skills/figure-it-out/SKILL.md", - "sourceDigest": "e041c64a39f1084a20e60ee99762c4dbd3ec8be56ed33fd68ea867b8bd8bd3e4", + "sourceDigest": "0eb9485f0e7d84fee56b5d0f0af0faf4635e3ca87c8cba3970c01293b76ecc19", "targetDigest": "37c25a3c0b354da74e33a2a291fc21e62140304eee2447ed73400bc2759402ec" }, "skills/how/references/explainer-prompt.md": { @@ -139,19 +151,19 @@ "skills/how/references/explorer-prompt.md": { "upstream": "pstack", "source": "skills/how/references/explorer-prompt.md", - "sourceDigest": "3a6965276d23be7d8da6c305bfd5d7bf29d2aef09e5dae4119463ac72022a02d", - "targetDigest": "3a6965276d23be7d8da6c305bfd5d7bf29d2aef09e5dae4119463ac72022a02d" + "sourceDigest": "a3b44a6e5bb16a6d4d1cac19db8ed5322ffd5f5f5d45baca4e73990ca096f8be", + "targetDigest": "a3b44a6e5bb16a6d4d1cac19db8ed5322ffd5f5f5d45baca4e73990ca096f8be" }, "skills/how/SKILL.md": { "upstream": "pstack", "source": "skills/how/SKILL.md", - "sourceDigest": "06b714dbd830bc829bfb89e33a1c39daf6d72ea412e488ea9d65f5f33b885a0c", + "sourceDigest": "d31805589c7f6a63a6db6c9fadebbd79fb9660682cf1654e9b2e5e1e7cd30bc0", "targetDigest": "a3e2acb068e126bad1ddadb4b16bb14154d5687fffc8ce2fe8209660b83c2e4b" }, "skills/interrogate/references/code-quality-review.md": { "upstream": "pstack", "source": "skills/interrogate/references/code-quality-review.md", - "sourceDigest": "623d3d8122d075c303b562783b471a732992e84166b318f85ab6d6c118b13304", + "sourceDigest": "79162fda183eafd40d51661fbb5e151c7ba250f89e506ba17f5bd135dcbd50a8", "targetDigest": "79162fda183eafd40d51661fbb5e151c7ba250f89e506ba17f5bd135dcbd50a8" }, "skills/interrogate/references/lead-judgment.md": { @@ -163,19 +175,19 @@ "skills/interrogate/references/reviewer-prompt.md": { "upstream": "pstack", "source": "skills/interrogate/references/reviewer-prompt.md", - "sourceDigest": "a397cc61102add709803d917fb23d726920525bf23e7c06dc4ed0b5cbeb00e54", + "sourceDigest": "e0598e254792b56de39bb16b1e6db559b03a522fdc54b98f942d254090920ae6", "targetDigest": "e0598e254792b56de39bb16b1e6db559b03a522fdc54b98f942d254090920ae6" }, "skills/interrogate/references/rubric.md": { "upstream": "pstack", "source": "skills/interrogate/references/rubric.md", - "sourceDigest": "59e9b7cc4556e735e1b859a7dd1f7637b013a2426a84825ac1c51979942c158a", + "sourceDigest": "a85aa801abbaf14434f00579440abc0d8e2723227ba8bf57de7cca8d6e7d2f25", "targetDigest": "a85aa801abbaf14434f00579440abc0d8e2723227ba8bf57de7cca8d6e7d2f25" }, "skills/interrogate/SKILL.md": { "upstream": "pstack", "source": "skills/interrogate/SKILL.md", - "sourceDigest": "2867910309e81411123ae4edca68ffca5795e66521d3f3bc0876f6213b542fb9", + "sourceDigest": "59d498c3e9848a24b2d105eb3f05b808aa4152adf4cb1de7bbb6aff4f4cd9b68", "targetDigest": "ab2508809da00eac47444b102cd7d11730f15b2476cd6cd947e330cc08814e78" }, "skills/maintain-verification-skill/SKILL.md": { @@ -190,6 +202,24 @@ "sourceDigest": "3624c8ef16cf2e48deb2a4049e72c6962a9431c8d6c6af90e7bd7ea0375224ec", "targetDigest": "2f04984c34d64ad8119eac43f24298d480528b14a9876d672aee0c942aa0c2da" }, + "skills/meta-help/references/prompting.md": { + "upstream": "pstack", + "source": "skills/poteto-help/references/prompting.md", + "sourceDigest": "463f450c44a60afd001a2f69fdf8a5dea174351f339369b12ec3c41515e564d3", + "targetDigest": "230e756e5cdfdcadb63145a267c17e56eb59d8b3b805e1884d27c69fb5660f55" + }, + "skills/meta-help/references/recipes.md": { + "upstream": "pstack", + "source": "skills/poteto-help/references/recipes.md", + "sourceDigest": "1872323419a3e5c7783b1933f7a180ca26c25a6e1f4ec83bd65e091ebbfb812b", + "targetDigest": "1b58ae71b25c6b0ad64debeb4567c4f6e0aabc5e7881bdb463b624b3a4617389" + }, + "skills/meta-help/SKILL.md": { + "upstream": "pstack", + "source": "skills/poteto-help/SKILL.md", + "sourceDigest": "5fc65e4c30c52edcde690d18904e3a8cf6ba6c2424c672d1a5cb6d29ab28645c", + "targetDigest": "ee598f1639882e7f1c10b821f41cc94224bb5d6aa940306d31ae06cc42bfde9a" + }, "skills/meta-mode/playbooks/authoring-a-skill.md": { "upstream": "pstack", "source": "skills/poteto-mode/playbooks/authoring-a-skill.md", @@ -205,25 +235,25 @@ "skills/meta-mode/playbooks/autopilot-full.md": { "upstream": "pstack", "source": "skills/poteto-mode/playbooks/autopilot-full.md", - "sourceDigest": "2042a89a0399b5fe700110bc03746899536c10f0df186e9fb15bbd4a2f6dfce5", - "targetDigest": "80b6f7d54b4430a1ee416ff2da72330bc480243afebab85a488b77b7bc8ab7d2" + "sourceDigest": "05ca30a16242c19d0c78ba1e88cca66f858d75252cb154fd740099fe292de802", + "targetDigest": "ebdc7ef1e8fc52e0b91303770541ce905b372eed8e5293e644c9bc6f59a2ca7d" }, "skills/meta-mode/playbooks/autopilot-stack.md": { "upstream": "pstack", "source": "skills/poteto-mode/playbooks/autopilot-stack.md", - "sourceDigest": "60e0d997f7b369004a02089c71b9091d3f8e9bc0b4a3c1142598380faa7722fd", - "targetDigest": "33c6e9c2e2db8b62bbe3f394eb7161a2895cbe4bcd915cbbc28db69250d4fafa" + "sourceDigest": "007c0a3b12011954a224f54773ef4ad7b75918be0a311914c1b51ad4e794c1e5", + "targetDigest": "80962e7db35f9ad2a0c4a363280f2f181a4e02df819f664fb8e7b8d8dbd4a4a2" }, "skills/meta-mode/playbooks/babysit.md": { "upstream": "pstack", "source": "skills/poteto-mode/playbooks/babysit.md", - "sourceDigest": "51be21872152f97612d37258273269b88212b6696432d25d678cac30f02f4157", + "sourceDigest": "a0346c37c2313f36a863b80f66ee7b98059c2242adf74fc7b3e48abdb9ec6f5a", "targetDigest": "d52fed9c782e79df75e2e0f4f6344bc764e7aded1e5b8ac880ffdcc69dc9768f" }, "skills/meta-mode/playbooks/bug-fix.md": { "upstream": "pstack", "source": "skills/poteto-mode/playbooks/bug-fix.md", - "sourceDigest": "e958c67d5454fc12d76ec645b50dfd85c423082aac13a49e2913ef2815948216", + "sourceDigest": "018bbc146ae19145caa6c7e70591fee081b64447dda1c1c4b681c9974d928b13", "targetDigest": "8872387c8893159c2557929af3c2b35270b245ace9aa04b76f3d8f622b526d2d" }, "skills/meta-mode/playbooks/eval.md": { @@ -235,14 +265,14 @@ "skills/meta-mode/playbooks/feature.md": { "upstream": "pstack", "source": "skills/poteto-mode/playbooks/feature.md", - "sourceDigest": "430dae0fd736554ff7dffc3ef0644c9f0c845e25742f69e598c35b9b89660301", + "sourceDigest": "3a62cc4a8cbcf144bb9dd05f05420a15be0d38b784d3b141bb730a5852f50a62", "targetDigest": "f9ac3784c615c1e84d40ec30ede16872988dcb8364d480343e4d98b7961f06c2" }, "skills/meta-mode/playbooks/hillclimb.md": { "upstream": "pstack", "source": "skills/poteto-mode/playbooks/hillclimb.md", - "sourceDigest": "bc1fc4052c1ee918a56115a219cbcbbc4c147fa1a8080e77c7d58068eecac299", - "targetDigest": "1581e5ef7551e1495b7737bf344612707540ee96e69755e1c8e729b25617608a" + "sourceDigest": "244f289898fe67a458065e90fe8217c916c5acf61cdee8975ade3f9831a12e91", + "targetDigest": "656c3f4c2e78d227e90eda89f4262f251db7f4e6f1e8ad13095cc9f1d86564e5" }, "skills/meta-mode/playbooks/investigation.md": { "upstream": "pstack", @@ -253,14 +283,14 @@ "skills/meta-mode/playbooks/multi-phase-plan.md": { "upstream": "pstack", "source": "skills/poteto-mode/playbooks/multi-phase-plan.md", - "sourceDigest": "b823e05b64bbef84ae5169717c5fab1d9ab5079625996271e3aa7abcdce7b8ad", - "targetDigest": "b4771a313aa64ea72edec9133aa4f88795ee755f78240952fdc1f19d450f62a4" + "sourceDigest": "27d310e3fc3937a60b8fcbe1318f9d249a7477a722907bf85b3e4eb3dc436b11", + "targetDigest": "eaa8d7e9f3b907c96acf9067c433eb40b6a32119ab3d8c373a57f1653b9565a5" }, "skills/meta-mode/playbooks/opening-a-pr.md": { "upstream": "pstack", "source": "skills/poteto-mode/playbooks/opening-a-pr.md", - "sourceDigest": "b173ff9638ff62f91f6813c1a0ed3417cdf9f6545a659be0c1fb1f42130e0e66", - "targetDigest": "81cc0748aa97accbee24b743fd03852f20f31722c857569e2b7030d8dcea071f" + "sourceDigest": "ab40de7163c1c6e274f46ee559b2e53ef45673703f601f13f4931c199e6fb90f", + "targetDigest": "a44b4ea2e72e5249eb0ebe26fe9d64317285cc9eb2fd84382e50329e30fc89be" }, "skills/meta-mode/playbooks/orchestrate.md": { "upstream": "pstack", @@ -271,14 +301,14 @@ "skills/meta-mode/playbooks/pause-safely.md": { "upstream": "pstack", "source": "skills/poteto-mode/playbooks/pause-safely.md", - "sourceDigest": "7d5fc10e144265f1b35f8157926541e738c1de64b6a85b3e61b51cf268c3dffd", + "sourceDigest": "77968cfe5f4a71a8cd33e0ae8ffcdbd88dd693a212c240457773e6c40c96c21d", "targetDigest": "50f1fa76fcdbf92db5a772a0470a128850c960c9eb68156846cc4f5a503f863b" }, "skills/meta-mode/playbooks/perf-issue.md": { "upstream": "pstack", "source": "skills/poteto-mode/playbooks/perf-issue.md", - "sourceDigest": "b2ee9aed1466583361cb61b4e8d79ebb3b61f7f9f6540be7633852afacab1d89", - "targetDigest": "708f59dbe6d969ef8388b575b0b4a614133fb24e207541184eb0d3b62f8e0bb3" + "sourceDigest": "2b88ad0f880e4d4d755ac19fe52414d6631d6baa816d060f53cf0a7429d7e14a", + "targetDigest": "c452f37e6461e22eb5accf5231a92c1fee17813e702a815207cab614cf52c3e4" }, "skills/meta-mode/playbooks/prototype.md": { "upstream": "pstack", @@ -289,7 +319,7 @@ "skills/meta-mode/playbooks/refactoring.md": { "upstream": "pstack", "source": "skills/poteto-mode/playbooks/refactoring.md", - "sourceDigest": "53bac1f1fe886600dd1991b5511b7975e6a206168038f9d282d88e45408e93cf", + "sourceDigest": "50f4f7d3d301551f8b8a57c3303c99958c5ca630ae0d0051823b6987c0eb5b96", "targetDigest": "81761553c8cb8a76beb38184b2c2f2a0d419aa64c987cc7896f4771cd7d4e021" }, "skills/meta-mode/playbooks/runtime-forensics.md": { @@ -307,7 +337,7 @@ "skills/meta-mode/playbooks/shipping.md": { "upstream": "pstack", "source": "skills/poteto-mode/playbooks/shipping.md", - "sourceDigest": "c301902136e0a9a0a55403c35374f6f5738e501aee66c27458dc197b87557550", + "sourceDigest": "19f3f6803a7bbe9ff04f624b03e3b55f07ac0a05e991aa00d5fe51239b920b2a", "targetDigest": "d898c5b32402a3e22a213311d33527423c57cb81b050c8e1e36d42cd2d85a24c" }, "skills/meta-mode/playbooks/trace-forensics.md": { @@ -347,8 +377,8 @@ "skills/meta-mode/SKILL.md": { "upstream": "pstack", "source": "skills/poteto-mode/SKILL.md", - "sourceDigest": "b3c505602b82fb3641a3983e9c46fb974881faa12ece1af804fae27afb7be532", - "targetDigest": "32363f67837dfe03bc5fd1b58ba940f2cfde2dfe46bce808416ad7cd4f63fd90" + "sourceDigest": "404c0ef4a78e93451b2ab555ca532e7197b5cf87de29205b6f7109dbee5d9c4d", + "targetDigest": "08d339fcc5315f9e24bf2f810d3b3505bd98efb6930e30a2a4d4769575197024" }, "skills/no-comments/SKILL.md": { "upstream": "pstack", @@ -392,6 +422,12 @@ "sourceDigest": "58903529d733b1c1a7c9ccf127d45ef3c7d0d9f0b81164a4dc6b80efe6f2912b", "targetDigest": "3013367ce42fabb55799ffbcc51ad20b2ae7ec1b898bad4ac4ceaa2f093edbe1" }, + "skills/principle-explain-the-number/SKILL.md": { + "upstream": "pstack", + "source": "skills/principle-explain-the-number/SKILL.md", + "sourceDigest": "5aac99e7ce0bb1b37e2579acf4fe88c32a1456d9d46afd4a57cfe1df9092e89c", + "targetDigest": "0a5cb3579a30e4da9d1635f5ceb11f773e551ec8626ac9c38b5db3985d3ac26b" + }, "skills/principle-fix-root-causes/SKILL.md": { "upstream": "pstack", "source": "skills/principle-fix-root-causes/SKILL.md", @@ -407,7 +443,7 @@ "skills/principle-guard-the-context-window/SKILL.md": { "upstream": "pstack", "source": "skills/principle-guard-the-context-window/SKILL.md", - "sourceDigest": "9f60e2c79b35f865cb103462f9128c6760b70f603475d1e535e5930f61840f66", + "sourceDigest": "d2cef147862576e3d709b7afc149d85196245e8338b9c7eef337c95fba412b3e", "targetDigest": "7a0a9540d4c0e8053ace79628d0a493444a82d1bbe1d8e94c8e561606c3d2912" }, "skills/principle-laziness-protocol/SKILL.md": { @@ -443,19 +479,19 @@ "skills/principle-never-block-on-the-human/SKILL.md": { "upstream": "pstack", "source": "skills/principle-never-block-on-the-human/SKILL.md", - "sourceDigest": "d82bce9ab9193249d1ec0d514202d89602f0fd3d312174d622c2dd222bae5a2e", + "sourceDigest": "f2764bb9338cbfc788c903cf4b9cd0a5f4042d3a04dd6d59cbd525d9beaadd0a", "targetDigest": "90cd48f4082367fe70fc1659fec5a8d0e76a40cb7f9be4797b4b460cec28a4dd" }, "skills/principle-outcome-oriented-execution/SKILL.md": { "upstream": "pstack", "source": "skills/principle-outcome-oriented-execution/SKILL.md", - "sourceDigest": "beedcaed75572a6a1662d47f16da203c2bd2c9dbffbbd678d4ba187d67b7e670", + "sourceDigest": "10eb91633aa570355ba4bb37088fcade2b22e498df7a58edc749e65bc5a78e2d", "targetDigest": "922ade1be5f671575b3c93367c3d08c9dbb2f7444a42bacbfb834656724d61ac" }, "skills/principle-prove-it-works/SKILL.md": { "upstream": "pstack", "source": "skills/principle-prove-it-works/SKILL.md", - "sourceDigest": "ae13d287984a5864312b6286899d4ee2b60f8272b5e5e8fcc586a7c3ea51020b", + "sourceDigest": "ec79a15025bac8d33d62011c54f3b612733fd2a024e623b531b3637aa75070e2", "targetDigest": "69fe19f428387ffbdf60d81fa6817272f1f88bc30ec7cd7edad408ce607ff39c" }, "skills/principle-redesign-from-first-principles/SKILL.md": { @@ -473,7 +509,7 @@ "skills/principle-sequence-verifiable-units/SKILL.md": { "upstream": "pstack", "source": "skills/principle-sequence-verifiable-units/SKILL.md", - "sourceDigest": "761390804ee36c32f5338d8db47ec54463d40ff96dbb296dfafabcd5f2593eec", + "sourceDigest": "2ccbbacc56ace5afdfb8670cef19d7bd009fb2a0033b9a741cbdf2b6baf72187", "targetDigest": "bc512996a3f226d1964444341e3fab1bda7f1b2928b136ab406ac4486150430f" }, "skills/principle-subtract-before-you-add/SKILL.md": { @@ -513,13 +549,13 @@ "skills/reflect/references/divergent-reviewer.md": { "upstream": "pstack", "source": "skills/reflect/references/divergent-reviewer.md", - "sourceDigest": "7da0334ce282e6d8d7349c0cff14ffbd10a91a756c0b5c3ccc97291f57b8bed6", + "sourceDigest": "221dfc0abf7cbcd25e1da3cd87323f5d1050fc3bf652e096d093584e183c98fb", "targetDigest": "6b21c64302826cea77c539f2be4bab2188be2821c1caaec536c16ef94f4ad99d" }, "skills/reflect/references/judgment-reviewer.md": { "upstream": "pstack", "source": "skills/reflect/references/judgment-reviewer.md", - "sourceDigest": "917bb2ad21240a42b440aeb2a17766092e09f70d0982417b2f4caa6d74f27164", + "sourceDigest": "a40ecb9b28bd2a3491e11a541157fe58efe158e0eda7b61a5006c14590aabe61", "targetDigest": "eafa6b19333572c21daeebe1506bda066d7dd44f0b0e0f9185ba8b54b2d10a93" }, "skills/reflect/references/synthesizer.md": { @@ -531,19 +567,19 @@ "skills/reflect/references/tooling-reviewer.md": { "upstream": "pstack", "source": "skills/reflect/references/tooling-reviewer.md", - "sourceDigest": "8c74ebf7811801d634db7ab609b097d77ea00ab77bb4b258d69bd96e671cfa39", + "sourceDigest": "bc49ced90fa81eaba3083b88aeb430d900a6d8f14ff40c1d6b52263bacfc77b6", "targetDigest": "c154b4f948cf470d099acd1770925aa1506edf17ba54de833af16c8d8528bc34" }, "skills/reflect/SKILL.md": { "upstream": "pstack", "source": "skills/reflect/SKILL.md", - "sourceDigest": "6a4d4ccaace9ce88c3e268fcbedf3cfd40e527162a5e5aad6de8edbaf5e2b83f", + "sourceDigest": "36efa48cc4ec2ba6f8131651aae24c6321682b098ed47a1069a7509462bf4a84", "targetDigest": "5478382b85614482fdf8799c9b0113d0c12c6595ee1003aa62c91f6288b91089" }, "skills/setup-mstack/SKILL.md": { "upstream": "pstack", "source": "skills/setup-pstack/SKILL.md", - "sourceDigest": "5acdc3db4f15f3e9b81fb56eab7f17cdccde1a11a40053ed7743f7467729c8a9", + "sourceDigest": "125dd0c8f588782cfb271efae8f97a0719e43e79f56b3495c095f460bcee6389", "targetDigest": "ede1efcab2c6503521faed92ab691df87dd92b48e33c66cc57d72d4ea4c5ff82" }, "skills/show-me-your-work/references/decision-log-template.tsv": { @@ -555,26 +591,26 @@ "skills/show-me-your-work/scripts/log.mjs": { "upstream": "pstack", "source": "skills/show-me-your-work/scripts/log.sh", - "sourceDigest": "1601bc18f9aba0af3f5d6375e4f2d5dc6102334d1bca935026c0e3547cdadbbf", + "sourceDigest": "a65a4bc5fb7cdeadbdb7b7ff1ca4682f4d9c42420942b2977cd17b46c4ac338e", "targetDigest": "1fa4184750bee4a37aedd1a9e7461f4d2bc121830b7724857fa5fbe2fb3c43f7", "reason": "The Node implementation replaces the Bash logger for Windows portability." }, "skills/show-me-your-work/SKILL.md": { "upstream": "pstack", "source": "skills/show-me-your-work/SKILL.md", - "sourceDigest": "831e85ba3f84f38bf338cd03e6af050fea357752e25a825e334c99f59d7f2077", + "sourceDigest": "bcff5f7f9fd23f92c12b251f9cd6b947e9485e1055cfacb6fdd9cae0789d7550", "targetDigest": "1464cc0dbe44a03df3250456260de8fdfa8535b80e10abaaf9e5b121637919cd" }, "skills/swarm/SKILL.md": { "upstream": "pstack", "source": "skills/swarm/SKILL.md", - "sourceDigest": "d578d877c3b8b9de7163f52579c4683337a940acc0fbe4496a498f5d3b27df30", - "targetDigest": "c24493812f03e0165cdbb3dd19e16d376742afe3b07f92cc48575f27883ae729" + "sourceDigest": "bdcee4168e22428036e93d7cdeec3f391dbc4132f927f6db2540328c22db0273", + "targetDigest": "93f49f135adb52278200670929eef76f03edb6995f5f3c074a690441a38d4e95" }, "skills/tdd/SKILL.md": { "upstream": "pstack", "source": "skills/tdd/SKILL.md", - "sourceDigest": "011cab0ecc04a3632121efb493ae4d60aa282a9b72c66de74dd8ad7e4313e05a", + "sourceDigest": "eeb868e2dfebee528d730a67d7b17498fac4bb85dec2e38bc5c5176aca4d5d2f", "targetDigest": "4930d09f2ca2dd47487c66d21d82bd376e35cd70bb8e42bfad5e19506c2ca2df" }, "skills/teach/SKILL.md": { @@ -586,14 +622,14 @@ "skills/technical-writing/SKILL.md": { "upstream": "pstack", "source": "skills/technical-writing/SKILL.md", - "sourceDigest": "6d6d9e625ae412ee8f36df8deb6fd9203d7c6acca776d5ee3cabbb9126f8b84c", - "targetDigest": "a450d685f477833640054828477fff97e1fd4ffb396a845b512d131b633c1919" + "sourceDigest": "f5c512ffeec70bc4e0dee50f7bb4c26742e1be77967a6e8b15d1921e1c209ceb", + "targetDigest": "b83d616480d74381acdc5accb65a409c01095b71abc7dc02b6cadc496138dc81" }, "skills/typescript-best-practices/references/patterns.md": { "upstream": "pstack", "source": "skills/typescript-best-practices/references/patterns.md", - "sourceDigest": "62e9cd32d2fa066a35d0d1349aac22dce31a48ad7d5eaf142570770cfe707384", - "targetDigest": "4f5ef6f9ab4d158910249aa375d14f939d46ec4441a9750060cef54e26691682" + "sourceDigest": "faa1362055374452efccac1b629677c61acfb0bcc6c4e3311836b5715638ee18", + "targetDigest": "d1b52ded45e285c9a0b7d720dbe896cecab845731e280906dc05128c57e9c1f9" }, "skills/typescript-best-practices/SKILL.md": { "upstream": "pstack", @@ -604,7 +640,7 @@ "skills/unslop/SKILL.md": { "upstream": "pstack", "source": "skills/unslop/SKILL.md", - "sourceDigest": "c6d2572294d933a428211921069e9a248490e9b466ca59437cb4d9de248600ca", + "sourceDigest": "195411d320b5b328f9f642baf59757ed19aaf0931c0838740e0aca273d538dc1", "targetDigest": "290a10a90e52f080fdf0f225f043088990b5cd8d8b8307c800a91cfeb1568aa4" }, "skills/why/references/epistemics.md": { @@ -682,7 +718,7 @@ "skills/why/SKILL.md": { "upstream": "pstack", "source": "skills/why/SKILL.md", - "sourceDigest": "222b93789754ba6ee901835137184acdca667f7e47c523bcc85aca86675fb249", + "sourceDigest": "2a852ec8680920109d2b56538b027c52867896a597250ac5d18a13e0b42e5b06", "targetDigest": "873aedc86d1321093e9a195ac8bff1783241b309a1d33808ab74f181c4b8f22d" }, "skills/writing-for-agents/SKILL-MECHANICS.md": { @@ -714,14 +750,14 @@ "tools/meta-mode/check-plan.mjs": { "upstream": "pstack", "source": "skills/poteto-mode/scripts/check-plan.mjs", - "sourceDigest": "4f5118edf719b481983dc87dfadd5b4b5473d05aad04a7ba65191ff9c73faf1b", - "targetDigest": "ae99ad15b22971829cf2f2517c862d695546411813a307bba55674b6b94a1445", + "sourceDigest": "4f9432d9989880b6afc2bdda503d5b12a9d07d357ecf31936b7ab5e83bc80523", + "targetDigest": "b37aa3a8d9a7466c2eda37d7ff8e8461f065bea873baa90e51e92746c89378ba", "reason": "Runtime tools are packaged separately from portable skill instructions." }, "tools/meta-mode/check-plan.test.mjs": { "upstream": null, "reason": "Local portability guidance or implementation; review alongside its owning skill.", - "targetDigest": "773d1e6582d8245d38c8d2deeff585ce0a9e9e9b293ba8d69f1c7b0e176a315b" + "targetDigest": "43b630cd003b18171ce62e6cf506cabbd8f6bb4bcd5192170ce5bf5340867709" }, "tools/meta-mode/check-playbooks.mjs": { "upstream": null, diff --git a/profiles/skills.json b/profiles/skills.json index 21ffdf8..aa355f6 100644 --- a/profiles/skills.json +++ b/profiles/skills.json @@ -3,9 +3,11 @@ "architect", "arena", "automate-me", + "benchmark-checklist", "blast-radius", "bro", "codebase-design", + "correct", "create-verification-skill", "diagnosing-bugs", "figure-it-out", @@ -13,6 +15,7 @@ "interrogate", "maintain-verification-skill", "make-bot-ui", + "meta-help", "meta-mode", "no-comments", "principle-attack-the-premise", @@ -21,6 +24,7 @@ "principle-encode-lessons-in-structure", "principle-exhaust-the-design-space", "principle-experience-first", + "principle-explain-the-number", "principle-fix-root-causes", "principle-foundational-thinking", "principle-guard-the-context-window", diff --git a/profiles/upstream-manifest.json b/profiles/upstream-manifest.json index bad87d5..90bd4f4 100644 --- a/profiles/upstream-manifest.json +++ b/profiles/upstream-manifest.json @@ -1,102 +1,49 @@ { "source": "https://github.com/cursor/plugins/tree/main/pstack", - "commit": "f5bdd6826fd0a0d9cbc4347134c3a74a200b9d9d", - "artifacts": { - "agents": { - "agents/comment-reviewer.md": "c0fd0383008da45fc78cfac17b9007d62c42f87ad1c8d5c2fb658b1fd01f7c82", - "agents/meta-agent.md": "98bfec1538a77982d5e5e2534c69de6b64077c172d0a4108fd9da7b36c95b5cb" - }, - "automations": { - "automations/benny/FOR_AGENTS.md": "9e86916edf7fdddf3325dac869d947d5cab767ee40f1b5eaf5d16e31f2a5322a", - "automations/benny/README.md": "339fa6a5e1b07dbd708e87bc423e31e25ab3ac7e4292b80d3330abe992ee3245", - "automations/benny/skills/reproduce-and-fix-issues/references/control-adapter.md": "58b0615d2fca895f9a20df83266e280042b0d585b5f2fd324e2094a682fd846b", - "automations/benny/skills/reproduce-and-fix-issues/references/feature-map.example.md": "1e5c7c8522daec3e43fcc2e73ceb97289ded65b552949ce65a11cc8eb3d2b6ee", - "automations/benny/skills/reproduce-and-fix-issues/references/verify-existing-fix.md": "c90eae00abcdec71a58fa8d60f2c495b082a526ad50b8e8e494837609129bf29", - "automations/benny/skills/reproduce-and-fix-issues/SKILL.md": "2cb174442390be10cb7e7767e89bb1e94fda4d014426c40888397ad8286060ff", - "automations/benny/skills/setup-benny/SKILL.md": "c5bbca8d97cc6975d34e84c42ac4fd59e04c7f77892e0af534b3e58ca0fd43df", - "automations/benny/skills/triage-issue-reports/references/routing.example.md": "e5e53013692568cf69da8e8b302fff929fe2fbc9aec1a4651fd7997e2c7a4025", - "automations/benny/skills/triage-issue-reports/SKILL.md": "92a17e4d2927457541b7e903f6def93e79e22f886c4b821c56bb5c9797db4193", - "automations/benny/templates/configuration.example.yaml": "13e24b4ce9b9a0913916e85fe3b080b88d45f8e55dccfe8ae38e0751a997b6f5", - "automations/benny/templates/reproduce-automation-prompt.md": "71ec574f1844e379394ae4ef14c48d7df10afbaa319d395c788d7f856f0e6899", - "automations/benny/templates/triage-automation-prompt.md": "e0bba594547834f013ec805915610eb597e7929efe3ffbe85ae00339ee16d474" - }, - "guide": { - "docs/guide/01-setup.md": "6786c9090de6092d87836214b690e2b5640ddc7f34b19c0b9e2af794fcc17e7e", - "docs/guide/02-meta-mode.md": "c169bbee5eae6ea6b16ea4d3df1442b05031778b20eb9af8cc19c1a7bac5282a", - "docs/guide/03-understand.md": "5db58a1fc2cc7bf1843945fcc7d93eba4f73e26fde5cd097d006be641fe5883e", - "docs/guide/04-design.md": "216bc41d25e3481333acfffef4ea486ce8dabcc5dfa736d16eb0afd979aa03a1", - "docs/guide/05-build-and-clean.md": "40a1d2b189e8a889022934d23dd79c661edbd13ee27b2f496543f8d8d03bac17", - "docs/guide/06-verify-and-ship.md": "53a6bc8b3e850e34c4d8b1785a488eb7fbcbfe94ed588aeeaca252a5eb6e442c", - "docs/guide/07-overnight.md": "060294d4dbda952e3211e285f75e471c8d454d7705767b42377c4e1963841ad2", - "docs/guide/08-principles.md": "4dba3340352310e432905a27dd70552b4e034bb7d37a55dcab59a4b378e59ef1", - "docs/guide/09-make-it-yours.md": "04b21905a0a152ea9e57dcbecf25112112a1e7584037feabf501132f2d8cc64c", - "docs/guide/10-recipes-and-pitfalls.md": "56b6e1360c070029ac26ec39f00f7c6c587f1203255682808ae93b3176f90746", - "docs/guide/images/design.jpg": "b8ed07427f6a0c37dd8ba97961fc0eb5071efeee6c4a230648bdb7547f6f2a8f", - "docs/guide/images/overnight.jpg": "4b4405e4df8925c5b3abbe702f681af0f3b1f5f32271b599f95717f578f1a0c8", - "docs/guide/images/recipes.jpg": "9fa2d51b476635712737795ddef81806efaa0086bb3bfa9f9f45695d9ab0f8e8", - "docs/guide/images/router.jpg": "525843055a4efd2b10acc50a8652fd02b0834ea733a8a2f895c1eb89036017da", - "docs/guide/images/understanding.jpg": "b60587e9a9bbe2550e93be9819cf0cd4acf77d90fac769a0c43d82bd8e34e279", - "docs/guide/images/verification.jpg": "2a76b52007a1cd2866ba67fd47d7d9ef3e1118bb5a09c4665eee8c3f161bd09a", - "docs/guide/README.md": "e76f2e20364a4021707394b0557751e3aa81be2c819b19aaa705de08086515a5" - }, - "meta-mode-tools": { - "tools/meta-mode/bootstrap.ts": "d9d39f235da5512de6122f1ff28584b3a0120b170f5447a7a5868f7cf187d12a", - "tools/meta-mode/bun.lock": "6413513594536785c3fd52b14934dd52d1ce179ad3ffe99d77535f5b637435a2", - "tools/meta-mode/check-plan.mjs": "ddcdb05af01b37d7513b2017d44e29c30bdaa79ca360c5913d701c16dde70907", - "tools/meta-mode/orch/orch.test.ts": "174b86d21ff51ccd28d1a8c938cb2e0c6fa287b209d4ca6c03932fcb1b53372e", - "tools/meta-mode/orch/orch.ts": "f091687df627a0b75fabd54af58945a9cd6c7039ef0622012ac9ed60cd8ec434", - "tools/meta-mode/orch/store.ts": "0eae7cf69282e827b1227166f2e32cee3560f2f3e65b3f1f2faf6fb83d3b4c5b", - "tools/meta-mode/package.json": "c7ac7fd69bb925415cdc15cd636567304ee40f8d665986e45ed8c0ee658f6caf", - "tools/meta-mode/watch-pr/cli.test.ts": "a35592b4c6da96caf8d47987e9cd503fab6c7774ab87d11a43f24b4b5df2a9d1", - "tools/meta-mode/watch-pr/cli.ts": "89c08863089181a232be782c4b2ed90a1552f44aeecb0dcb7aac2c623620e680", - "tools/meta-mode/watch-pr/fakes.test-helper.ts": "e53e31b7f03068063f53a99a3591b052aaed66e4e2b196b3a364980f60324ab1", - "tools/meta-mode/watch-pr/github.test.ts": "0cbce011050522938523e36bb42a260e92b812dcd2076930fa681672ad316b24", - "tools/meta-mode/watch-pr/github.ts": "d1bbbafbe8e2c703c84da2029de7f2c4011412512f8cf65a42100f46bcb92c8a", - "tools/meta-mode/watch-pr/policy.test.ts": "a9fedb25feefd1f57ef6a662f80c99018690170a3a8070773a08eaf694d1d3d9", - "tools/meta-mode/watch-pr/policy.ts": "68d240505852cf23c9b2dea463342e9e61243f486b3cc86c735d140f9ee7be49", - "tools/meta-mode/watch-pr/render.ts": "2b709e86628d5b8fdb61f860e60ababc342b0626c67576305442cf548283a604", - "tools/meta-mode/watch-pr/tsconfig.json": "1ecccc72320b086c63ce3f73c959896fd747363e63553b3b1136296ea4069e45", - "tools/meta-mode/watch-pr/types.compile.ts": "621af4c9a664fbf699a9737efccdc248abb416df8819c9dc5f824beae2b9b1d6", - "tools/meta-mode/watch-pr/types.ts": "64ba6221e3bfe61bbb292337d199cdec6309455477280efb060203dba34e0e91", - "tools/meta-mode/watch-pr/watch-pr": "a17825c7862730dd7c897c1ac076971c0f11d2f9ff8fe37c4a74ebc6db92d549", - "tools/meta-mode/worktree-audit.sh": "9f14b5f4f70a6ada93778e49701f854796b11776edccb9f73816ee2a8b8b623c" - } - }, + "commit": "2cbf58508f40de470d7490b55c51d71241928fa2", "canonicalSkills": { "architect": { - "source": "897a59beaa3cab107d98c256206e062cc4a5e9421a45b9d462fbded19291fea5", - "target": "cc8a035aa7a2aa417676c4e364b86f4a3e2b85748bf2d0916402105b011a1083" + "source": "8c46078c04ee70fc4f35a9f82a364e49b78992c43625873c82f0635054dc89bd", + "target": "76c299297a79236fa519d401716a6ad1845ecc1a3f4fdff2aa052309261651aa" }, "arena": { - "source": "648697e237871e279e66166fd070dc272c73a310ababe7498c89713414ed4a14", + "source": "6cc5f63b9212d91d25a10670f8a5eba8665278013ae0e066d18a25f87b710447", "target": "f100383e190b806567015d2cbbaf90b9a1b0151ae60b08aa6185fc6eca3c9552" }, "automate-me": { "source": "c80a6024fa6bebfa6875975c74293415fa6f729087377998751dc1343c865e75", "target": "6ab6c4c4a4b50a7cb182149408bd1758229d4386fbb8b1a66cf6927847b02c27" }, + "benchmark-checklist": { + "source": "6a767e788a60428fa14e645ee10fe2e49896e514ff654f668b1d824deb9038e8", + "target": "3fc701eecd146557b75c0e7d26929ca5d5469632def12ef032109710ae23c1c0" + }, "blast-radius": { - "source": "20cb2945f5fe62055166f745107274af5f19428ca033e53a9b8bc69650d3ded1", + "source": "5f02db9101ccf26c20254718f0fcd5c2c7ac5d4292b0e0923d0944ac47237aff", "target": "72113714dc5e7ef634a8b220e3a8dacea7b0e82d1f24136c13e04013749ef41a" }, "bro": { "source": "aa329d0ceeeecb6822a7174ad76bb07a7826a3c52ceb6a588dec4138815084bb", "target": "8b822d47b9299627f5e4fe42684a031105792c8531443da1ae3423adfa2de96f" }, + "correct": { + "source": "bf482bacc972b3f124a4af8bf9364b4b3e280cb5845e44c326ea4f4565e5c904", + "target": "b7af9686e96f242ddd7d0c12731dd8c4347f4eff1c6d404dc87403d87076d492" + }, "create-verification-skill": { "source": "644f2551403c1bca01a2855b34611b6e7be0ce0dc5b204514c376c0f6a6e6ac4", "target": "eca219cac2808714d6aa3090fd3065d1da6a579d432f277aef334f1ca0dfe770" }, "figure-it-out": { - "source": "982f2c1024a3a24f6417426ad8e8a3e027fe6210a8a442308fb85073f8f3f6ef", + "source": "cd4c13cfc6553c5ff32458ab1f1a72a83548510f0bba77ca8d6c3846f0da09a4", "target": "37c25a3c0b354da74e33a2a291fc21e62140304eee2447ed73400bc2759402ec" }, "how": { - "source": "06b714dbd830bc829bfb89e33a1c39daf6d72ea412e488ea9d65f5f33b885a0c", + "source": "6492ea0d986c9763d649c665fb331a3b555444c486616136b748ca6c945045b5", "target": "a3e2acb068e126bad1ddadb4b16bb14154d5687fffc8ce2fe8209660b83c2e4b" }, "interrogate": { - "source": "8aef2c35f2282bbc2636e10b4b52fe41ed5d00c86e775e82fbf8771b2b07f9be", + "source": "08a284d1c40dcfc49df5e33dcd5edac4dbb94664976eda174f3fdc15aad92873", "target": "ab2508809da00eac47444b102cd7d11730f15b2476cd6cd947e330cc08814e78" }, "maintain-verification-skill": { @@ -107,9 +54,13 @@ "source": "3624c8ef16cf2e48deb2a4049e72c6962a9431c8d6c6af90e7bd7ea0375224ec", "target": "2f04984c34d64ad8119eac43f24298d480528b14a9876d672aee0c942aa0c2da" }, + "meta-help": { + "source": "a564a70bc1de5d8fe9e13f46621aa20f9180d0d34476ebee878c8fed19cae476", + "target": "ee598f1639882e7f1c10b821f41cc94224bb5d6aa940306d31ae06cc42bfde9a" + }, "meta-mode": { - "source": "d5817d996f6da294c86cacb2bd1b0c40c85968844a6afd194fe69efa8654878f", - "target": "32363f67837dfe03bc5fd1b58ba940f2cfde2dfe46bce808416ad7cd4f63fd90" + "source": "2e09a945cbe289dd85448f4a51eeac8c0c3893904decaab9413a33babf96ca08", + "target": "08d339fcc5315f9e24bf2f810d3b3505bd98efb6930e30a2a4d4769575197024" }, "no-comments": { "source": "5c5b0882297d704c3a9720c52b7a793c68b013eaf717989f0945624efdfe2b05", @@ -139,6 +90,10 @@ "source": "58903529d733b1c1a7c9ccf127d45ef3c7d0d9f0b81164a4dc6b80efe6f2912b", "target": "3013367ce42fabb55799ffbcc51ad20b2ae7ec1b898bad4ac4ceaa2f093edbe1" }, + "principle-explain-the-number": { + "source": "5aac99e7ce0bb1b37e2579acf4fe88c32a1456d9d46afd4a57cfe1df9092e89c", + "target": "0a5cb3579a30e4da9d1635f5ceb11f773e551ec8626ac9c38b5db3985d3ac26b" + }, "principle-fix-root-causes": { "source": "ba4cd38da1dcc8fe5432feb64457cba95594736a9b21b2ebf8f8c52aee068707", "target": "2f48a508674c8b9f3339aba95929079af54fb7fbd367b4eb45175388f1e170f9" @@ -148,7 +103,7 @@ "target": "e69eea824d81c4bb32cbcdb26513bf964882daeeb647bb99210978e86bec1a49" }, "principle-guard-the-context-window": { - "source": "9f60e2c79b35f865cb103462f9128c6760b70f603475d1e535e5930f61840f66", + "source": "d2cef147862576e3d709b7afc149d85196245e8338b9c7eef337c95fba412b3e", "target": "7a0a9540d4c0e8053ace79628d0a493444a82d1bbe1d8e94c8e561606c3d2912" }, "principle-laziness-protocol": { @@ -172,15 +127,15 @@ "target": "4464cc1a0a2366ff8249659c30f525dba6206947f037f07f5931238ed0e96f82" }, "principle-never-block-on-the-human": { - "source": "d82bce9ab9193249d1ec0d514202d89602f0fd3d312174d622c2dd222bae5a2e", + "source": "f2764bb9338cbfc788c903cf4b9cd0a5f4042d3a04dd6d59cbd525d9beaadd0a", "target": "90cd48f4082367fe70fc1659fec5a8d0e76a40cb7f9be4797b4b460cec28a4dd" }, "principle-outcome-oriented-execution": { - "source": "beedcaed75572a6a1662d47f16da203c2bd2c9dbffbbd678d4ba187d67b7e670", + "source": "10eb91633aa570355ba4bb37088fcade2b22e498df7a58edc749e65bc5a78e2d", "target": "922ade1be5f671575b3c93367c3d08c9dbb2f7444a42bacbfb834656724d61ac" }, "principle-prove-it-works": { - "source": "ae13d287984a5864312b6286899d4ee2b60f8272b5e5e8fcc586a7c3ea51020b", + "source": "ec79a15025bac8d33d62011c54f3b612733fd2a024e623b531b3637aa75070e2", "target": "69fe19f428387ffbdf60d81fa6817272f1f88bc30ec7cd7edad408ce607ff39c" }, "principle-redesign-from-first-principles": { @@ -192,7 +147,7 @@ "target": "30cc80284a90bb5d94cde5a3533a8a27755832c2c4e638f8e3b97bbf8ba94924" }, "principle-sequence-verifiable-units": { - "source": "761390804ee36c32f5338d8db47ec54463d40ff96dbb296dfafabcd5f2593eec", + "source": "2ccbbacc56ace5afdfb8670cef19d7bd009fb2a0033b9a741cbdf2b6baf72187", "target": "bc512996a3f226d1964444341e3fab1bda7f1b2928b136ab406ac4486150430f" }, "principle-subtract-before-you-add": { @@ -212,23 +167,23 @@ "target": "be67c9e064a2b6d2ec52e915c19f6507f9f389a112e9961eb93b3c793b565e70" }, "reflect": { - "source": "6a4d4ccaace9ce88c3e268fcbedf3cfd40e527162a5e5aad6de8edbaf5e2b83f", + "source": "902cd959ff2a894c44f462b58057afac676fb83fb0c56c2fc3c853db95e02205", "target": "5478382b85614482fdf8799c9b0113d0c12c6595ee1003aa62c91f6288b91089" }, "setup-mstack": { - "source": "a11137437e12831c73f228f449bdfefab487bf7e2c69a4b306189e8fb1e6ab3e", + "source": "388d2a0869504ef9943f34b217d0d7a3ca13fdaaeea2327078104d3efb807ce3", "target": "ede1efcab2c6503521faed92ab691df87dd92b48e33c66cc57d72d4ea4c5ff82" }, "show-me-your-work": { - "source": "831e85ba3f84f38bf338cd03e6af050fea357752e25a825e334c99f59d7f2077", + "source": "bcff5f7f9fd23f92c12b251f9cd6b947e9485e1055cfacb6fdd9cae0789d7550", "target": "1464cc0dbe44a03df3250456260de8fdfa8535b80e10abaaf9e5b121637919cd" }, "swarm": { - "source": "32440570076df5a124d679e0419e5b03c1d405365bb443552789338427a8ce7b", - "target": "c24493812f03e0165cdbb3dd19e16d376742afe3b07f92cc48575f27883ae729" + "source": "f1d3a129f80f2e54d134f0216e5d7f6dd5043b3da245e2af38a94946f9f38153", + "target": "93f49f135adb52278200670929eef76f03edb6995f5f3c074a690441a38d4e95" }, "tdd": { - "source": "011cab0ecc04a3632121efb493ae4d60aa282a9b72c66de74dd8ad7e4313e05a", + "source": "eeb868e2dfebee528d730a67d7b17498fac4bb85dec2e38bc5c5176aca4d5d2f", "target": "4930d09f2ca2dd47487c66d21d82bd376e35cd70bb8e42bfad5e19506c2ca2df" }, "teach": { @@ -236,19 +191,19 @@ "target": "5a85664f8cce57429af0d8c060a20d8740579867f0976f4981032e8855cab2b5" }, "technical-writing": { - "source": "6d6d9e625ae412ee8f36df8deb6fd9203d7c6acca776d5ee3cabbb9126f8b84c", - "target": "a450d685f477833640054828477fff97e1fd4ffb396a845b512d131b633c1919" + "source": "f5c512ffeec70bc4e0dee50f7bb4c26742e1be77967a6e8b15d1921e1c209ceb", + "target": "b83d616480d74381acdc5accb65a409c01095b71abc7dc02b6cadc496138dc81" }, "typescript-best-practices": { "source": "28f9e61710e205f6f3c5476f333483cff0e988f6a5b639e2faad536344b40c5e", "target": "02b41b2cbb0ac43940b8f4df8b54c55f1aac0a68890a9379f9b006b2a8f1f4a0" }, "unslop": { - "source": "c6d2572294d933a428211921069e9a248490e9b466ca59437cb4d9de248600ca", + "source": "195411d320b5b328f9f642baf59757ed19aaf0931c0838740e0aca273d538dc1", "target": "290a10a90e52f080fdf0f225f043088990b5cd8d8b8307c800a91cfeb1568aa4" }, "why": { - "source": "222b93789754ba6ee901835137184acdca667f7e47c523bcc85aca86675fb249", + "source": "073fb39adb2de6d07a6cfbaf98a35b6397be974ff9fe3bb26dc46f7065a04114", "target": "873aedc86d1321093e9a195ac8bff1783241b309a1d33808ab74f181c4b8f22d" } }, @@ -299,24 +254,85 @@ "reason": "Route native Benny verification and maintenance through the shared canonical contract and feature map." }, "docs/guide/01-setup.md": { - "source": "6786c9090de6092d87836214b690e2b5640ddc7f34b19c0b9e2af794fcc17e7e", - "target": "b67fd0a7950464e1094225a2f85add0714849c1daab6c5289ad7bbc653baa536", + "source": "058974e262eed41d2c24428109127898d3a6c403538570e7add515c4089d0d84", + "target": "780ae4284b48e26032e0e70844d918ade5cd6ffebd6c301784c4432d4b7ac980", "reason": "Document one canonical verification contract and the mixed pstack/mstack project workflow." }, "docs/guide/03-understand.md": { - "source": "5db58a1fc2cc7bf1843945fcc7d93eba4f73e26fde5cd097d006be641fe5883e", - "target": "1fd73edc1cdde214e82b4b116ba3b1d3ec1dcae18e1ef019de99ee12439c3cf1", + "source": "c7dce3a9b1f1c0de8c00084453a3a18b69f0ad0c6616592b584e2d19add69ebd", + "target": "72e10ba5cac7e7510de58bf4669121f820343304f5050c4bc219dd00668c05f9", "reason": "Point session pickup at the portable project-local resume checkpoint." }, "docs/guide/06-verify-and-ship.md": { - "source": "53a6bc8b3e850e34c4d8b1785a488eb7fbcbfe94ed588aeeaca252a5eb6e442c", - "target": "e99e7108a757eee96397ebb79c6bbbc6f30084a35eb32d98f8de2e2b9c1aad18", + "source": "e3a8259f2b2450692e43d607848f5a85a7cee894490452968391079e52a8ac50", + "target": "5fd91e770e7805455668b44d4f39f767498dc5ff6d4f10a9cfbe9de9d0631ac5", "reason": "Document one canonical verification contract and the mixed pstack/mstack project workflow." }, "docs/guide/README.md": { - "source": "e76f2e20364a4021707394b0557751e3aa81be2c819b19aaa705de08086515a5", - "target": "e9c7b7d96995ed268034310e38b36721f3379cabe69d1e135cb9eab54d9ee2ad", + "source": "50c28fff5f88d6350856dec1412a85d1e5e7f4a978fd4c1022552b8e0d475ba3", + "target": "b6d86e7c913cb0e9549fb355ba9c5bc4bd4259c1986c80ac8dfdc23478aadd47", "reason": "Document one canonical verification contract and the mixed pstack/mstack project workflow." } + }, + "artifacts": { + "agents": { + "agents/comment-reviewer.md": "c0fd0383008da45fc78cfac17b9007d62c42f87ad1c8d5c2fb658b1fd01f7c82", + "agents/meta-agent.md": "51f3791434b848cf8881d5d3e1cfcde502cf92f694c1d8748a65ca9603b33b3e" + }, + "automations": { + "automations/benny/FOR_AGENTS.md": "9e86916edf7fdddf3325dac869d947d5cab767ee40f1b5eaf5d16e31f2a5322a", + "automations/benny/README.md": "339fa6a5e1b07dbd708e87bc423e31e25ab3ac7e4292b80d3330abe992ee3245", + "automations/benny/skills/reproduce-and-fix-issues/references/control-adapter.md": "58b0615d2fca895f9a20df83266e280042b0d585b5f2fd324e2094a682fd846b", + "automations/benny/skills/reproduce-and-fix-issues/references/feature-map.example.md": "1e5c7c8522daec3e43fcc2e73ceb97289ded65b552949ce65a11cc8eb3d2b6ee", + "automations/benny/skills/reproduce-and-fix-issues/references/verify-existing-fix.md": "c90eae00abcdec71a58fa8d60f2c495b082a526ad50b8e8e494837609129bf29", + "automations/benny/skills/reproduce-and-fix-issues/SKILL.md": "2cb174442390be10cb7e7767e89bb1e94fda4d014426c40888397ad8286060ff", + "automations/benny/skills/setup-benny/SKILL.md": "c5bbca8d97cc6975d34e84c42ac4fd59e04c7f77892e0af534b3e58ca0fd43df", + "automations/benny/skills/triage-issue-reports/references/routing.example.md": "e5e53013692568cf69da8e8b302fff929fe2fbc9aec1a4651fd7997e2c7a4025", + "automations/benny/skills/triage-issue-reports/SKILL.md": "92a17e4d2927457541b7e903f6def93e79e22f886c4b821c56bb5c9797db4193", + "automations/benny/templates/configuration.example.yaml": "13e24b4ce9b9a0913916e85fe3b080b88d45f8e55dccfe8ae38e0751a997b6f5", + "automations/benny/templates/reproduce-automation-prompt.md": "71ec574f1844e379394ae4ef14c48d7df10afbaa319d395c788d7f856f0e6899", + "automations/benny/templates/triage-automation-prompt.md": "e0bba594547834f013ec805915610eb597e7929efe3ffbe85ae00339ee16d474" + }, + "guide": { + "docs/guide/01-setup.md": "058974e262eed41d2c24428109127898d3a6c403538570e7add515c4089d0d84", + "docs/guide/02-meta-mode.md": "681343e7135540ecd0125c83209e602c5e646534b89c2a6029cc29d4dc2455fd", + "docs/guide/03-understand.md": "c7dce3a9b1f1c0de8c00084453a3a18b69f0ad0c6616592b584e2d19add69ebd", + "docs/guide/04-design.md": "83f10b418a0f4d6ec0d7b536918d395fbcdf853f640d5dcbc1f7394a8f3d68ca", + "docs/guide/05-build-and-clean.md": "af91971988478ed0e53775d7f14f59e40ef7093b524d21df4f0b7917121b4f23", + "docs/guide/06-verify-and-ship.md": "e3a8259f2b2450692e43d607848f5a85a7cee894490452968391079e52a8ac50", + "docs/guide/07-overnight.md": "b66d8726a888fa8ed2f1b488fc1ca14ac67eab892ff655878bd09bacdcdefabc", + "docs/guide/08-principles.md": "cd8f9466703489b9eab7f5b54e8dce6101c212f045dfe7f519f0e7e2fbf60857", + "docs/guide/09-make-it-yours.md": "bd1031fe054c60f34f4b7450ababf827d48a2bd216ae874587c9f7511f193639", + "docs/guide/10-recipes-and-pitfalls.md": "3e0eb2c1f5c7681180e6eea4813ce016143110e519ac5b23e42f6a55237f6e8d", + "docs/guide/images/design.jpg": "b8ed07427f6a0c37dd8ba97961fc0eb5071efeee6c4a230648bdb7547f6f2a8f", + "docs/guide/images/overnight.jpg": "4b4405e4df8925c5b3abbe702f681af0f3b1f5f32271b599f95717f578f1a0c8", + "docs/guide/images/recipes.jpg": "9fa2d51b476635712737795ddef81806efaa0086bb3bfa9f9f45695d9ab0f8e8", + "docs/guide/images/router.jpg": "525843055a4efd2b10acc50a8652fd02b0834ea733a8a2f895c1eb89036017da", + "docs/guide/images/understanding.jpg": "b60587e9a9bbe2550e93be9819cf0cd4acf77d90fac769a0c43d82bd8e34e279", + "docs/guide/images/verification.jpg": "2a76b52007a1cd2866ba67fd47d7d9ef3e1118bb5a09c4665eee8c3f161bd09a", + "docs/guide/README.md": "50c28fff5f88d6350856dec1412a85d1e5e7f4a978fd4c1022552b8e0d475ba3" + }, + "meta-mode-tools": { + "tools/meta-mode/bootstrap.ts": "d9d39f235da5512de6122f1ff28584b3a0120b170f5447a7a5868f7cf187d12a", + "tools/meta-mode/bun.lock": "6413513594536785c3fd52b14934dd52d1ce179ad3ffe99d77535f5b637435a2", + "tools/meta-mode/check-plan.mjs": "4f9432d9989880b6afc2bdda503d5b12a9d07d357ecf31936b7ab5e83bc80523", + "tools/meta-mode/orch/orch.test.ts": "174b86d21ff51ccd28d1a8c938cb2e0c6fa287b209d4ca6c03932fcb1b53372e", + "tools/meta-mode/orch/orch.ts": "f091687df627a0b75fabd54af58945a9cd6c7039ef0622012ac9ed60cd8ec434", + "tools/meta-mode/orch/store.ts": "0eae7cf69282e827b1227166f2e32cee3560f2f3e65b3f1f2faf6fb83d3b4c5b", + "tools/meta-mode/package.json": "c7ac7fd69bb925415cdc15cd636567304ee40f8d665986e45ed8c0ee658f6caf", + "tools/meta-mode/watch-pr/cli.test.ts": "a35592b4c6da96caf8d47987e9cd503fab6c7774ab87d11a43f24b4b5df2a9d1", + "tools/meta-mode/watch-pr/cli.ts": "89c08863089181a232be782c4b2ed90a1552f44aeecb0dcb7aac2c623620e680", + "tools/meta-mode/watch-pr/fakes.test-helper.ts": "e53e31b7f03068063f53a99a3591b052aaed66e4e2b196b3a364980f60324ab1", + "tools/meta-mode/watch-pr/github.test.ts": "0cbce011050522938523e36bb42a260e92b812dcd2076930fa681672ad316b24", + "tools/meta-mode/watch-pr/github.ts": "d1bbbafbe8e2c703c84da2029de7f2c4011412512f8cf65a42100f46bcb92c8a", + "tools/meta-mode/watch-pr/policy.test.ts": "a9fedb25feefd1f57ef6a662f80c99018690170a3a8070773a08eaf694d1d3d9", + "tools/meta-mode/watch-pr/policy.ts": "68d240505852cf23c9b2dea463342e9e61243f486b3cc86c735d140f9ee7be49", + "tools/meta-mode/watch-pr/render.ts": "2b709e86628d5b8fdb61f860e60ababc342b0626c67576305442cf548283a604", + "tools/meta-mode/watch-pr/tsconfig.json": "1ecccc72320b086c63ce3f73c959896fd747363e63553b3b1136296ea4069e45", + "tools/meta-mode/watch-pr/types.compile.ts": "621af4c9a664fbf699a9737efccdc248abb416df8819c9dc5f824beae2b9b1d6", + "tools/meta-mode/watch-pr/types.ts": "64ba6221e3bfe61bbb292337d199cdec6309455477280efb060203dba34e0e91", + "tools/meta-mode/watch-pr/watch-pr": "d955603be6cc0e8b8ffcec722f635192b2261410b1f2929abea94480e47eb5d4", + "tools/meta-mode/worktree-audit.sh": "9f14b5f4f70a6ada93778e49701f854796b11776edccb9f73816ee2a8b8b623c" + } } } diff --git a/profiles/upstreams.json b/profiles/upstreams.json index da55191..963b72d 100644 --- a/profiles/upstreams.json +++ b/profiles/upstreams.json @@ -1,11 +1,12 @@ { "pstack": { "repository": "https://github.com/cursor/plugins/tree/main/pstack", - "commit": "f5bdd6826fd0a0d9cbc4347134c3a74a200b9d9d", + "commit": "2cbf58508f40de470d7490b55c51d71241928fa2", "renames": { "poteto-mode": "meta-mode", "setup-pstack": "setup-mstack", - "poteto-agent": "meta-agent" + "poteto-agent": "meta-agent", + "poteto-help": "meta-help" }, "artifacts": { "agents": { @@ -101,6 +102,50 @@ { "from": "Writing a skill matches the [Authoring or modifying a skill playbook](../../skills/meta-mode/playbooks/authoring-a-skill.md), which routes through Cursor's built-in `create-skill`, validates the frontmatter and links, and ships the result through the Opening a PR playbook.", "to": "Writing a skill matches the [Authoring or modifying a skill playbook](../../skills/meta-mode/playbooks/authoring-a-skill.md), which routes through the active Harness's skill-authoring flow, validates the frontmatter and links, and ships the result through the Opening a PR playbook." + }, + { + "from": "Short works because the playbook holds the structure, and a Custom Mode keeps `/meta-mode` in context on every turn. [Set up mstack](./01-setup.md#run-your-first-task) shows how to start one.", + "to": "Short works because the playbook holds the structure, and `/meta-mode` stays active for the current task. [Set up mstack](./01-setup.md#run-your-first-task) says what to do when it fades." + }, + { + "from": "The cleanest isolation is a [cloud subagent](https://cursor.com/docs/subagents#cloud-subagents). Each one gets its own VM and branch, so it can install dependencies, run your app, and record video of the result without touching your machine. Type `/in-cloud` before the task, or ask the parent chat to hand work to cloud subagents.", + "to": "The cleanest isolation is a worker on its own machine or remote environment, when the active Harness offers one. Each gets its own branch, so it can install dependencies, run your app, and record the result without touching your machine. Ask the parent chat to hand the work to remote workers." + }, + { + "from": "an isolated worktree or cloud agent, and a decision log", + "to": "an isolated worktree or remote worker, and a decision log" + }, + { + "from": "or that you're about to go offline or restart Cursor.", + "to": "or that you're about to go offline or restart the Harness." + }, + { + "from": "A [Cursor Project](https://cursor.com/blog/projects) gives one coordinator agent a persistent thread. The coordinator doesn't write code. It directs subagents, which run in the cloud by default, so the work continues when your laptop is closed. That's the shape the Orchestrate playbook expects.", + "to": "A coordinator agent with a persistent thread, such as a Harness project or a long-lived session, directs subagents and doesn't write code itself. When the Harness runs subagents remotely, the work continues when your laptop is closed. That's the shape the Orchestrate playbook expects." + }, + { + "from": "- Give each body of work its own Project, such as a feature, a migration, a perf push, or a tech-debt cleanup. Several can run side by side.\n- Drag related chats into the Project, finished ones included. They become context for every agent in it.", + "to": "- Give each body of work its own coordinator thread, such as a feature, a migration, a perf push, or a tech-debt cleanup. Several can run side by side.\n- Point the coordinator at related finished chats and notes. They become context for every agent under it." + }, + { + "from": "One prompt can carry a whole Project, from research through execution:", + "to": "One prompt can carry a whole program, from research through execution:" + }, + { + "from": "Run them as cloud agents, or say \"own worktree per attempt\".", + "to": "Run them on separate machines, or say \"own worktree per attempt\"." + }, + { + "from": "## Load the TypeScript rules by name\n\n[`typescript-best-practices`](../../skills/typescript-best-practices/SKILL.md) turns the type-system principles into concrete rules: discriminated unions, `unknown` at boundaries, exhaustive variants, schema-derived types. It doesn't load on its own, so type `/typescript-best-practices` when a task touches `.ts` or `.tsx` files.", + "to": "## Let the TypeScript rules load themselves\n\n[`typescript-best-practices`](../../skills/typescript-best-practices/SKILL.md) has no slash command in your workflow. It loads whenever the agent touches a `.ts` or `.tsx` file and turns the type-system principles into concrete rules: discriminated unions, `unknown` at boundaries, exhaustive variants, schema-derived types." + }, + { + "from": "/poteto-help how do i get meta-mode to stay on every turn?", + "to": "/meta-help how do i pick a model for each role?" + }, + { + "from": "poteto-help", + "to": "meta-help" } ] }, diff --git a/scripts/agent-format.test.mjs b/scripts/agent-format.test.mjs index b2d75c1..7809283 100644 --- a/scripts/agent-format.test.mjs +++ b/scripts/agent-format.test.mjs @@ -103,3 +103,16 @@ test("round-trips actual agent files and escaped strings through Python's standa }); assert.equal(result.status, 0, result.stderr); }); + +test("the routing agent description matches meta-mode's fresh-subagent rule", () => { + const agent = readFileSync(new URL("../agents/meta-agent.md", import.meta.url), "utf8"); + const description = agent.match(/^description: (.*)$/m)?.[1] ?? ""; + const skill = readFileSync(new URL("../skills/meta-mode/SKILL.md", import.meta.url), "utf8"); + assert.match(skill, /\*\*Fresh subagents by default\.\*\*/); + assert.match(description, /Spawn a fresh `meta-agent` for each new task/); + assert.doesNotMatch(description, /Resume an existing/); + // The reuse cases come from meta-mode's own list, so the two files cannot drift apart. + const cases = skill.match(/costly to move: (its [^,]+), (its [^,]+), or (a process it still runs)/); + assert.ok(cases, "meta-mode no longer lists the reuse cases"); + for (const reuse of cases.slice(1)) assert.ok(description.includes(reuse), `description omits "${reuse}"`); +}); diff --git a/skills/architect/SKILL.md b/skills/architect/SKILL.md index 8935d57..adca3a5 100644 --- a/skills/architect/SKILL.md +++ b/skills/architect/SKILL.md @@ -33,7 +33,7 @@ Use the active mstack model configuration's `candidate` role for architect runne Design it twice. Require at least two structurally distinct candidates before synthesis, even when the first looks sufficient. This is the **exhaust-the-design-space** principle skill made concrete. Whole-shape alternatives, not point fixes inside one shape. -Screen every candidate against [`references/design-red-flags.md`](references/design-red-flags.md) before synthesis. Reject or revise shallow modules, information leakage, temporal decomposition, and pass-through methods. +Screen every candidate against [`references/design-red-flags.md`](references/design-red-flags.md) before synthesis. Assume the next contributor is an agent that sees only the files it opened, copies the nearest example, and takes the shortest path that compiles. Prefer the design where a change that looks right from one file is right for the whole repo. Compare viable candidates on interface depth. Prefer the design that hides more complexity behind a smaller, simpler public surface. A rich interface can keep call chains short by concentrating capability instead of scattering it across layers. diff --git a/skills/architect/references/design-red-flags.md b/skills/architect/references/design-red-flags.md index 32cb240..f8503c9 100644 --- a/skills/architect/references/design-red-flags.md +++ b/skills/architect/references/design-red-flags.md @@ -31,3 +31,27 @@ Group code around domain knowledge and ownership. Methods that run at different A pass-through method forwards the same arguments to another method with the same shape. It adds a layer without hiding complexity. Remove it or move responsibility to the module that can complete the operation. Keep a forwarding boundary only when it adds policy, adaptation, or a distinct abstraction. + +## Split ownership + +More than one module writes the same state or keeps its own copy of it. An agent that edits one writer can't see the others, so their rules diverge. + +Give each piece of state one owner. Other modules read it or ask the owner to change it. + +## Two ways to do one task + +The design supports more than one way to do the same task. An agent copies whichever way it finds first, so every way keeps gaining callers. + +Keep one way. Move callers off the others and delete them in the same change. + +## Importable internals + +A caller can import a module's internals. An agent takes the shortest path that compiles, so it imports them directly and they become part of the interface. + +Make internals unreachable from outside the module, so an import from outside fails the build. + +## Hand-synced list + +Two or more places list the same items, and adding an item means editing every list. An agent that sees one list updates only that one. + +Keep one list and derive the others from it. If a list can't be derived, make the build fail when the lists disagree. diff --git a/skills/benchmark-checklist/SKILL.md b/skills/benchmark-checklist/SKILL.md new file mode 100644 index 0000000..04cc322 --- /dev/null +++ b/skills/benchmark-checklist/SKILL.md @@ -0,0 +1,39 @@ +--- +name: benchmark-checklist +description: "Vet a perf measurement (limiter, tuning, limits, errors, repeatability, relevance, and whether the work happened) before you report or act on it. Use when you run a benchmark or report a speedup or regression you measured." +--- + +# Benchmark checklist + +Use this when you produce a performance number: a PR's before and after, a regression claim, a hillclimb harness, or a library or config choice. [Explain the Number](../principle-explain-the-number/SKILL.md) says why. Answer each question below with evidence from a run, not from a guess about the code. + +For a quick ballpark the user asked for, one run is enough. Still check questions 4 and 7, and say that it is one run. Skip the rest unless that run looks wrong. A choice between options is never a ballpark. + +## Before you run anything + +- Write down the claim you expect to make, in the words you would ship ("export is 30% faster at p50 on the 60k-row dataset"). The questions test that sentence. +- Read the measurement script. Note what it times, what it counts, and what it ignores. +- Check the system load and the core count, for example with `uptime` and `nproc` or the platform equivalent. If the machine is busy, find out what is running. If you cannot stop it, interleave the sides so both see the same noise, and say so in the report. +- The tools named below are Linux and macOS examples. On Windows, `$env:NUMBER_OF_PROCESSORS`, `Get-CimInstance Win32_Processor`, `Get-Counter`, Process Explorer, and WPR or ETW give the same evidence. On any platform, the evidence names the tool and the run it came from. + +## The questions + +1. **Why not double?** Name the limiter. Profile in a run you do not report, because profilers and tracers slow the work down. Use CPU per process (`top`, `pidstat`), a profiler for the runtime (`node --cpu-prof`, `py-spy`, `perf`), I/O wait, and syscall counts (`strace -c` on Linux). Then map the hot spot to source. Watch the load generator too. If it saturates first, you measured the load generator. If a change did not move the number, the limiter explains why, so find it before you call the change useless. +2. **Was it tuned?** Run every side the way production runs it: release builds, production flags and env, batching and transaction settings, connection pools, caches as warm or cold as production sees them, and the same versions and data. If one side runs on defaults, you compared configurations, not implementations. A limiter that is a setting, such as a commit per row, a debug build, or a missing index, means that side is untuned. Tune it and measure again before you pick a winner. If you cannot tune it, do not pick a winner from that run. Narrowing the claim to the code as it ships today does not fix this when the user is choosing what to adopt, because they adopt the option, not today's settings. +3. **Did it break limits?** Do the arithmetic. Compare bytes per second with disk and network bandwidth, and operations per second times the cost per operation with the cores you have. Compare the time saved with the time the changed piece took. Removing a piece that takes 10% of the run can make the run at most about 11% faster. A result past a limit means the run measured something other than the work, such as a cache, a no-op, or a bug. +4. **Did it error?** Count failures and non-success responses, and check that the outputs are correct, not just present. Errors behave differently from successes. Rejections are often fast, and timeouts and retries are slow. If the script does not count errors, add the count. +5. **Does it reproduce?** Run each side at least 5 times, and alternate the sides (A, B, A, B, and so on) so that warmup, lazy initialization, caches, and drift do not favor one side. Report the median and the range. Treat a gap smaller than the run-to-run variation as no measurable difference. When the call is close, use a rank-sum test or the harness's own statistics. +6. **Does it matter?** Next to any micro result, measure the end-to-end path a user waits on, with realistic data sizes and concurrency. Report the micro result as a share of the whole. A helper that takes 1% of a request can make the request at most 1% faster, however fast the helper gets. +7. **Did it even happen?** Confirm the work ran inside the timed region. The request reached the server, the rows were written, the bytes were read, and the code used the result. Lazy code (generators nobody iterates, promises nobody awaits, results the JIT can discard) and timeouts all produce numbers for work that never happened. + +## Report + +- Lead with the verdict: faster, slower, no measurable difference, or inconclusive. +- Give the number with its unit, the run count, the range, and the limiter. For example, "p50 41 ms → 33 ms, median of 7 runs per side, range 32 to 35 ms after, bound by JSON parsing on one core." +- Call the verdict inconclusive when you claim a difference but cannot name the limiter, when a side ran untuned, or when you could not check questions 4 and 7. Name the gap. +- Keep a PR body to one primary number, per the **Opening a PR** playbook. Put the runs, the range, and the limiter evidence in a linked artifact or a notes file. + +## How this fits the other perf material + +- The **Perf issue** playbook finds and fixes slowness, and the performance mantras in its step 2 generate the fixes. This skill vets its baseline before the playbook plans from it, and every number after that. +- The **Hillclimb** playbook loops on one metric. This skill vets its harness before the harness is frozen. The frozen harness then prints error and work counts, so each keep-or-revert checks questions 4 and 7 for free. diff --git a/skills/correct/SKILL.md b/skills/correct/SKILL.md new file mode 100644 index 0000000..a7ccc5e --- /dev/null +++ b/skills/correct/SKILL.md @@ -0,0 +1,31 @@ +--- +name: correct +description: "Find the mistakes agents keep repeating in this repo and make each one impossible. Try architecture first, then types, then a lint whose error names the fix, then a test, and write docs last. Prove each check fails on a real past mistake. Repeat this each time the operator corrects you. Use for /correct." +--- + +# Correct + +The operator keeps correcting agents in this repo for the same mistakes. Change the repo so the next agent can't make them. + +Assume every contributor is an agent that sees only the files it opened, copies the nearest example, and takes the shortest path that compiles. Design the repo so a change that looks right from one file is right for the whole repo. + +## Find the mistake classes + +First, read recent commits, reverts, review comments, agent instruction files, and comments that explain workarounds. Group the mistakes into classes. A class counts once it has happened twice. + +## Fix each class at the highest level that works + +1. **Eliminate it with architecture.** Give each piece of state one owner and each task one supported way. Hide internals so the wrong import fails. Replace hand-synced lists with one source of truth. Delete old ways and dead code an agent would copy. +2. **Enforce it with types so the bad state can't be written.** If bad code still compiles, add a lint or CI check whose error names the file, type, or function to use instead. If the pattern is already common, fail only when a change adds more. +3. **Test the behavior.** Fix or delete any test that would still pass if every function it calls returned nothing. +4. **Write docs or agent rules last, only for judgment calls.** Nothing fails when an agent skips them. + +## Fix and prove + +Then fix the most frequent classes now, one commit each. Prove each new check fails on a real past mistake. Run the same command locally and in CI. Exceptions go on the offending line with a reason, an expiry date, and a human's approval. + +## Keep the rule table + +Last, keep a table in the agent instruction file that pairs each rule with what enforces it. When the operator corrects you, fix the mistake and add the rule. If the rule was already there and nothing enforces it, that's a repeat, so fix it at the highest level in the same change. Drop a rule once its mistake can't happen. + +**Reply:** each class with its evidence, the level you picked, and why a higher level didn't work. diff --git a/skills/how/references/explorer-prompt.md b/skills/how/references/explorer-prompt.md index 8b898d9..9b4b059 100644 --- a/skills/how/references/explorer-prompt.md +++ b/skills/how/references/explorer-prompt.md @@ -4,7 +4,7 @@ Build each explorer subagent's prompt from this template. Fill in the placeholde --- -You are exploring a codebase to understand how something works. Gather facts: trace code paths, read implementations, map components. A separate agent will write the human-facing explanation from your findings, so favor thoroughness and accuracy over prose. +You are exploring a codebase to understand how something works. Gather facts. Trace code paths, read implementations, map components. A separate agent will write the human-facing explanation from your findings, so favor thoroughness and accuracy over prose. Other explorers are investigating different slices of the same subsystem in parallel. Don't try to cover everything. Focus on your assigned angle and go deep. diff --git a/skills/meta-help/SKILL.md b/skills/meta-help/SKILL.md new file mode 100644 index 0000000..ccfab9f --- /dev/null +++ b/skills/meta-help/SKILL.md @@ -0,0 +1,144 @@ +--- +name: meta-help +description: "Explains how to set up and use mstack and which skill, playbook, or principle fits a task, and hands back a prompt without starting the work. Use for /meta-help or a question about using or configuring mstack." +--- + +# Meta help + +Answer the user's question about mstack, hand them a prompt they can send, and link the file the answer came from. For a help question, don't start the work. The user asked how, and an mstack run spends real tokens, so let them send the prompt. + +A message that asks for work, such as "use mstack to fix this bug", is not a help question. Read [`meta-mode`](../meta-mode/SKILL.md), do the work under it, and mention once that `/meta-mode` fades as the chat moves on, per Start a task below. + +This file maps questions to the skills and guide pages that hold the answers. Those files own the details. Read the file you route to before you quote it, and trust it when it disagrees with this map. The links here point into the installed skills, which the user may not be able to open, so give the user the file's public copy: `https://github.com/3metaJun/mstack/blob/main/` followed by its path in the repository. The guide pages are the optional `guide` artifact, so link their public copies too. + +## Find out what they need + +Infer the need from the message and the conversation. A named situation, such as "which skill reviews a PR?", goes straight to its section. If the need is still unclear, ask one multiple-choice question with these options, then answer only the section they pick: + +- Get set up +- Start a task with `/meta-mode` +- Pick a skill for a situation +- Fix a run that went wrong +- Make mstack my own + +Check the state that changes the answer, and mention it only when it does: + +- No `~/.config/mstack/models.json` means `/setup-mstack` hasn't run for this user, so every role runs on the parent chat model. +- No `verify-*` skill, `.harness/verify/` contract, or other app harness in the project means agents have no scripted way to drive the app. Mention `/create-verification-skill` when the question is about proving a change works. + +## Get set up + +1. Install the skills for the Harness in use, from a terminal: `npx @3metajun/mstack --harness `. Claude Code can instead install the plugin with `claude plugin marketplace add 3metaJun/mstack` and `claude plugin install mstack@mstack`, where skills are namespaced, as in `/mstack:meta-mode`. +2. Run [`/setup-mstack`](../setup-mstack/SKILL.md). It asks for a reasoning budget, maps a model to each role, and writes `~/.config/mstack/models.json`. The file applies to new sessions. +3. Start a real task with `/meta-mode`, a goal, and a check that can pass or fail. + +Installing changes nothing until the user invokes a skill. The [README](../../README.md) and [guide page 1](../../docs/guide/01-setup.md) have the details. Offer to word their first prompt with them, per [`references/prompting.md`](references/prompting.md). + +If cost is the worry, say where the tokens go and how to spend fewer. mstack spends extra tokens on subagents and review panels. Rerun `/setup-mstack` and pick a smaller budget or cheaper models. A role set to `inherit-parent` runs on the chat's model, which saves tokens when the chat runs on a cheaper model. A shorter `reviewer` list runs fewer subagents, one for each entry. Save `/meta-mode` for work that needs rigor. + +The skills are portable across Codex, Claude Code, OpenCode, and pi, and they describe capabilities, not one vendor's commands. A skill that delegates, loops, or drives a UI uses what the active Harness provides. Where the Harness lacks a capability, the skill's fallback applies, so say which Harness the user runs when a delegation or loop question depends on it. + +## Start a task with `/meta-mode` + +`/meta-mode` matches the task to a playbook, copies the playbook's steps into the todo list, and runs the other skills as the steps need them. A step it skips stays in the list as `skip: `. A good prompt states the goal and how to tell it's done. It doesn't list skills, because a hand-written sequence tends to drop or reorder steps the playbook would keep. Read [`references/prompting.md`](references/prompting.md) before you help word one. [Guide page 2](../../docs/guide/02-meta-mode.md) has examples. + +Whether `/meta-mode` stays on across turns depends on the Harness. It is active for the task it was invoked for and fades as the chat moves on. If it fades, start the next task with `/meta-mode`. If the Harness can pin a skill or mode for a whole chat, the user can pin it there, and then it stays in context on every turn and stays out of casual turns. Mid-chat, "new task" makes the mode match a fresh playbook. + +## Pick a skill + +The default answer is `/meta-mode`, which runs most of the others when its steps need them. Name a skill directly when the user wants more or less of something than the playbook gives. Read the skill before you recommend it, and give one example prompt. + +| The user wants to | Skill | +|---|---| +| Do any non-trivial task with rigor | [`/meta-mode`](../meta-mode/SKILL.md) | +| Know how code works now, or where new code should live | [`/how`](../how/SKILL.md) | +| Know why code is shaped this way, or where a number came from | [`/why`](../why/SKILL.md) | +| Understand a change or subsystem, explained plainly | [`/teach`](../teach/SKILL.md) | +| Catch up on their own recent work on a topic | [`/recall`](../recall/SKILL.md) | +| Know what a small diff could break outside itself | [`/blast-radius`](../blast-radius/SKILL.md) | +| Settle types and module shape before code that crosses a function boundary | [`/architect`](../architect/SKILL.md) | +| Review or design a module's interface, seams, and depth | [`/codebase-design`](../codebase-design/SKILL.md) | +| Get several attempts at one brief, merged into the best one | [`/arena`](../arena/SKILL.md) | +| Run parallel checks over slices, or race workers | [`/swarm`](../swarm/SKILL.md) | +| Have several models review a diff and try to break it | [`/interrogate`](../interrogate/SKILL.md) | +| Diagnose a hard, flaky, or regressed bug, especially after a failed fix | [`/diagnosing-bugs`](../diagnosing-bugs/SKILL.md) | +| Fix a bug test-first when a cheap local test exists | [`/tdd`](../tdd/SKILL.md) | +| Apply TypeScript rules to `.ts` or `.tsx` work | [`/typescript-best-practices`](../typescript-best-practices/SKILL.md) | +| Strip comments before review, using a reviewer that didn't write them | [`/no-comments`](../no-comments/SKILL.md) | +| Clean AI tells out of prose | [`/unslop`](../unslop/SKILL.md) | +| Write docs, an RFC, a README, a PR description, or a commit message to a standard | [`/technical-writing`](../technical-writing/SKILL.md) | +| Write or revise instructions that agents read, such as a skill or AGENTS.md | [`/writing-for-agents`](../writing-for-agents/SKILL.md) | +| Hear the last reply again in plain words | [`/bro`](../bro/SKILL.md) | +| Give agents a scripted way to drive the app and prove behavior | [`/create-verification-skill`](../create-verification-skill/SKILL.md) | +| Bring a verification skill and its feature map back in line with the app | [`/maintain-verification-skill`](../maintain-verification-skill/SKILL.md) | +| Vet a performance number before reporting or acting on it | [`/benchmark-checklist`](../benchmark-checklist/SKILL.md) | +| Run a large or cross-cutting change, or one to review after stepping away | [`/figure-it-out`](../figure-it-out/SKILL.md) | +| Keep a decision log during a run, and review it afterward | [`/show-me-your-work`](../show-me-your-work/SKILL.md) | +| Pick a model for each role and a reasoning budget | [`/setup-mstack`](../setup-mstack/SKILL.md) | +| Turn their own working habits into a personal mode skill | [`/automate-me`](../automate-me/SKILL.md) | +| Turn what a finished task taught into skill edits | [`/reflect`](../reflect/SKILL.md) | +| Stop agents from repeating the same mistakes in this repo | [`/correct`](../correct/SKILL.md) | +| Build a page whose buttons wake a Grok Bot over a webhook | [`/make-bot-ui`](../make-bot-ui/SKILL.md) | +| Find their way around mstack | `/meta-help` | + +If a skill directory next to this one is missing from the table, read its frontmatter and route by its description. The `principle-*` directories are covered under principles below. + +Close calls: + +- `/how` explains what the code does. `/why` explains the reasons. `/teach` runs one or both and explains the result plainly. +- `/arena` gives every worker the same brief and merges the best parts. `/swarm` splits work into slices or a race and returns one report. +- `/architect` implements right after it settles the design. Add "with checkpoint" to review the design before it writes code. `/codebase-design` reviews or designs one module's interface and doesn't implement. +- `/interrogate` reviews the diff. `/blast-radius` looks for breakage outside the diff and proves the one fact that makes the change safe. +- `/recall` rebuilds context across recent sessions. Resuming one specific session or branch is the Session pickup playbook. +- `/figure-it-out` designs one rigorous run. The Orchestrate playbook runs a program that spans days and many PRs. The Autonomous run playbook drives one task to a finish condition. + +Not in mstack: + +- A code-cleanup command such as `/deslop`, and UI or CLI control skills such as `control-ui` and `control-cli`, come from the Harness or from other plugins. +- Loop, scheduled wake, background-job, and skill-authoring commands come from the Harness. mstack's playbooks use them when they exist and name a fallback when they don't. +- mstack has no `/orchestrate` skill. Orchestrate is a `/meta-mode` playbook. If a slash menu shows `/orchestrate`, another plugin provides it. + +## Playbooks and principles + +Playbooks are step lists inside `/meta-mode`, not skills, so they have no slash command. Inside `/meta-mode`, describing the task picks one, and these phrases name one directly: + +- "babysit this pr" or "check on pr 123" runs Babysit. It drives the PR to merge-ready and stops there. It doesn't merge unless the user asks to merge, land, or ship. +- "land the stack" runs Shipping. +- "take over this branch" runs Session pickup. +- "pause safely" runs Pause safely. +- "full autopilot on this queue" runs Autopilot-full. "stack them, don't ship" runs Autopilot-stack. +- "run the eval playbook" runs Eval. + +Without `/meta-mode`, a phrase such as "babysit this pr" can start another skill or command for the same job instead. The Playbooks section of [`meta-mode`](../meta-mode/SKILL.md) lists every playbook and when it applies. [Guide page 6](../../docs/guide/06-verify-and-ship.md) covers opening, babysitting, and landing a PR. + +mstack has no planning skill. A Harness's plan mode works alongside it. For work that spans phases or stacked PRs, asking `/meta-mode` for a plan runs the [Multi-phase plan playbook](../meta-mode/playbooks/multi-phase-plan.md), which writes the plan and doesn't implement it. For a design question, the Prototype playbook or `/architect` settles it in code first. + +Principles are one-rule skills that `/meta-mode` reads and cites in its replies. The user rarely invokes one. They steer with the names instead, as in "apply prove it works. show me the real output." Typing `/principle-` still loads one on demand. [Guide page 8](../../docs/guide/08-principles.md) lists them. + +## Fix a run that went wrong + +| Symptom | Fix | +|---|---| +| The mode stopped applying after a few turns | It was invoked for one task. Start the next task with `/meta-mode`, or pin it if the Harness can. | +| A question got treated as the next step of the last task | Say "new task", or say the turn doesn't need the mode. | +| A new model choice had no effect | The configuration from `/setup-mstack` applies to new sessions. Start one. | +| Runs cost more than expected | See the cost paragraph under Get set up. | +| A skill didn't load on its own | Whether a skill loads from the user's words depends on the Harness. Type `/`, or have `/meta-mode` run it, and note that it doesn't run every skill. | +| Parallel agents overwrote each other | Give each agent its own worktree, or run them on separate machines or remote workers when the Harness offers them. | +| An overnight run moved but finished nothing | A loop needs a check that can pass or fail, not a duration. See [guide page 7](../../docs/guide/07-overnight.md). | +| The reply claims success from a green build | Ask for the real command, flow, stored value, or profile. That's the prove-it-works principle. | + +For a run that drifts, [`references/prompting.md`](references/prompting.md) has one-line steers. [Guide page 10](../../docs/guide/10-recipes-and-pitfalls.md) has more pitfalls and the recipes worth copying. + +## Make mstack my own + +- [`/automate-me`](../automate-me/SKILL.md) drafts a personal mode skill from the user's own history, to use alongside `/meta-mode`. +- [`/reflect`](../reflect/SKILL.md) after a session turns its lessons into skill edits the user approves. +- `/meta-mode write a skill for ` runs the authoring playbook. The eval playbook tests a skill change blind. +- Fix a misbehaving skill in its own PR, not inside the feature work where it went wrong. + +[Guide page 9](../../docs/guide/09-make-it-yours.md) covers each of these. + +## Reply + +Lead with the answer. Give at most one example prompt in a code block, adapted from [`references/recipes.md`](references/recipes.md) when one fits, then the link to that file. Keep it short unless the user asked for the whole map. diff --git a/skills/meta-help/references/prompting.md b/skills/meta-help/references/prompting.md new file mode 100644 index 0000000..3a101b0 --- /dev/null +++ b/skills/meta-help/references/prompting.md @@ -0,0 +1,51 @@ +# Word the prompt + +A prompt states the intent and the check for done. The playbook supplies the steps, so a few plain sentences beat a spec. + +## Put in + +- The goal. Say what is wrong or what the user wants. +- The done check. It can pass or fail. "Make it better" and a duration are not checks. +- The proof to show. Ask for the real command output, a video of the flow, the stored value, or a before and after number. +- What the user already knows. A symptom, a repro step, a log, or a link saves the agent a search. +- The real constraints. "repro first", "don't change any code yet", "zero behavior change", and "let me review before proceeding" each change what the agent does. + +## Leave out + +- The how. Say what to achieve, and leave the agent room to find a better way. +- A list of skills or steps. A hand-written order drops or reorders steps the playbook keeps. Name a skill only to override one choice. +- The user's theory of the cause, until the agent restates the problem. A stated guess narrows the search. + +## Load the context first + +- For a noisy report, ask the agent to restate the underlying issue in its own words and in plain English before it does anything else. A misreading shows up before any code exists. +- In a fresh chat, `/recall` earlier work on the topic. Old chats hold context that the new agent lacks. +- Before a change to unfamiliar code, ask `/how` for the mechanics and `/why` for the reasons. An agent with no traced model fixes the symptom at the first plausible spot. +- Ask `/teach` to make the case for a choice, as in "convince me it fixes the cause and not the symptom". A case is easier to check than a summary. + +## Design before the plan + +- Never take the first design. Ask for prototypes of a few options, with screenshots or videos for UI, and pick from the evidence. +- Let prototypes answer the open questions. Don't review an abstract plan adversarially, because reviewers invent risks that never happen. +- For a shared package or API, ask for the README or a tutorial first, then work back to the code. The doc becomes the target the agent checks itself against. +- Ask for the plan only after the design is settled. Each step of the plan ends in a check. + +## Follow up short + +- "do it", "continue", and "keep going until done" are whole prompts once the chat holds the task. +- Start with "new task" when the subject changes. Otherwise the mode treats the message as the next step. + +## Before stepping away + +- Say "im going to bed" or "im stepping away" so the agent stops asking. +- Write done as checks every iteration can run, and give the Harness's loop or background command that predicate. +- Ask for a fresh worktree off a named base. +- Pre-answer what the agent would stop for, such as "don't ask me before committing". +- Ask for a decision log to audit later. +- Give an exit: "if you're truly stuck after a few hours, stop and write up why". + +## Steer in one line + +- Restate the goal: "i said the goal is to repro. i did not ask for a fix yet." +- Name the principle: "apply prove it works. show me the real output, not the build log." +- A principle name works because the agent already read the rule. Its reply names the decision the rule changed. diff --git a/skills/meta-help/references/recipes.md b/skills/meta-help/references/recipes.md new file mode 100644 index 0000000..6a46759 --- /dev/null +++ b/skills/meta-help/references/recipes.md @@ -0,0 +1,47 @@ +# Prompts worth copying + +Swap in the real paths, skills, and done checks. Informal wording works. + +## Understand + +- `/meta-mode read . restate the underlying issue in your own words, in plain english.` +- `/meta-mode investigate why . give me what we know, what data you used, and your best hypotheses. don't change any code yet.` +- `use /how to understand . then use /why to find out why it broke recently.` +- `/recall my work on from last week, then read .` +- `/teach me why you implemented it this way and not . what did you trade off?` +- `/meta-mode take over this branch. read the decision log, find what's done, and continue. don't redo finished work.` + +## Build + +- Bug: `/meta-mode . repro first, then fix and verify.` +- Bug in an app: `/meta-mode repro this with /verify-. if it repros on main, fix it and show me a video as proof.` +- Bug with a cheap test: `/meta-mode repro first. if there's a cheap test path, /tdd it. then fix and rerun.` +- Feature: `/meta-mode add . stays byte-identical. verify both.` +- Refactor: `/meta-mode move into one module, zero behavior change. record the current output first and prove it's unchanged after.` +- Perf: `/meta-mode takes