@giljae/pi-pstack 0.0.0-stage → 0.0.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (142) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +67 -2
  3. package/agents/comment-sicko.md +35 -0
  4. package/agents/poteto-agent.md +12 -0
  5. package/harness/pi.md +87 -0
  6. package/package.json +37 -4
  7. package/skills/architect/SKILL.md +14 -0
  8. package/skills/arena/SKILL.md +51 -0
  9. package/skills/automate-me/SKILL.md +107 -0
  10. package/skills/benchmark-checklist/SKILL.md +42 -0
  11. package/skills/blast-radius/SKILL.md +53 -0
  12. package/skills/bro/SKILL.md +10 -0
  13. package/skills/correct/SKILL.md +35 -0
  14. package/skills/create-formal-verification-skill/SKILL.md +46 -0
  15. package/skills/create-verification-skill/SKILL.md +47 -0
  16. package/skills/create-verification-skill/references/feature-map-example/README.md +47 -0
  17. package/skills/create-verification-skill/references/feature-map-example/create-note.md +39 -0
  18. package/skills/create-verification-skill/references/feature-map-example/search.md +45 -0
  19. package/skills/figure-it-out/SKILL.md +55 -0
  20. package/skills/how/SKILL.md +24 -0
  21. package/skills/in-your-own-words/SKILL.md +10 -0
  22. package/skills/interrogate/SKILL.md +34 -0
  23. package/skills/ketchup/SKILL.md +46 -0
  24. package/skills/ketchup-video/SKILL.md +32 -0
  25. package/skills/maintain-formal-verification-skill/SKILL.md +61 -0
  26. package/skills/maintain-verification-skill/SKILL.md +42 -0
  27. package/skills/make-bot-ui/SKILL.md +118 -0
  28. package/skills/no-comments/SKILL.md +27 -0
  29. package/skills/poteto-help/SKILL.md +165 -0
  30. package/skills/poteto-help/references/prompting.md +51 -0
  31. package/skills/poteto-help/references/recipes.md +51 -0
  32. package/skills/poteto-mode/SKILL.md +111 -0
  33. package/skills/poteto-mode/playbooks/authoring-a-skill.md +12 -0
  34. package/skills/poteto-mode/playbooks/autonomous-run.md +13 -0
  35. package/skills/poteto-mode/playbooks/autopilot-full.md +25 -0
  36. package/skills/poteto-mode/playbooks/autopilot-stack.md +8 -0
  37. package/skills/poteto-mode/playbooks/babysit.md +10 -0
  38. package/skills/poteto-mode/playbooks/bug-fix.md +15 -0
  39. package/skills/poteto-mode/playbooks/eval.md +25 -0
  40. package/skills/poteto-mode/playbooks/feature.md +21 -0
  41. package/skills/poteto-mode/playbooks/hillclimb.md +21 -0
  42. package/skills/poteto-mode/playbooks/investigation.md +14 -0
  43. package/skills/poteto-mode/playbooks/multi-phase-plan.md +11 -0
  44. package/skills/poteto-mode/playbooks/opening-a-pr.md +9 -0
  45. package/skills/poteto-mode/playbooks/pause-safely.md +10 -0
  46. package/skills/poteto-mode/playbooks/perf-issue.md +25 -0
  47. package/skills/poteto-mode/playbooks/prototype.md +14 -0
  48. package/skills/poteto-mode/playbooks/refactoring.md +16 -0
  49. package/skills/poteto-mode/playbooks/runtime-forensics.md +11 -0
  50. package/skills/poteto-mode/playbooks/session-pickup.md +11 -0
  51. package/skills/poteto-mode/playbooks/shipping.md +12 -0
  52. package/skills/poteto-mode/playbooks/trace-forensics.md +14 -0
  53. package/skills/poteto-mode/playbooks/visual-parity.md +11 -0
  54. package/skills/poteto-mode/playbooks/worktree-cleanup.md +12 -0
  55. package/skills/poteto-mode/references/bugbot-triage.md +142 -0
  56. package/skills/poteto-mode/scripts/bootstrap.ts +62 -0
  57. package/skills/poteto-mode/scripts/bun.lock +67 -0
  58. package/skills/poteto-mode/scripts/package.json +16 -0
  59. package/skills/poteto-mode/scripts/watch-pr/cli.test.ts +224 -0
  60. package/skills/poteto-mode/scripts/watch-pr/cli.ts +223 -0
  61. package/skills/poteto-mode/scripts/watch-pr/fakes.test-helper.ts +129 -0
  62. package/skills/poteto-mode/scripts/watch-pr/github.test.ts +498 -0
  63. package/skills/poteto-mode/scripts/watch-pr/github.ts +726 -0
  64. package/skills/poteto-mode/scripts/watch-pr/policy.test.ts +482 -0
  65. package/skills/poteto-mode/scripts/watch-pr/policy.ts +842 -0
  66. package/skills/poteto-mode/scripts/watch-pr/render.ts +169 -0
  67. package/skills/poteto-mode/scripts/watch-pr/tsconfig.json +13 -0
  68. package/skills/poteto-mode/scripts/watch-pr/types.compile.ts +93 -0
  69. package/skills/poteto-mode/scripts/watch-pr/types.ts +414 -0
  70. package/skills/poteto-mode/scripts/watch-pr/watch-pr +6 -0
  71. package/skills/poteto-mode/scripts/worktree-audit.sh +134 -0
  72. package/skills/poteto-mode/worker.md +11 -0
  73. package/skills/principle-attack-the-premise/SKILL.md +18 -0
  74. package/skills/principle-boundary-discipline/SKILL.md +14 -0
  75. package/skills/principle-build-the-lever/SKILL.md +17 -0
  76. package/skills/principle-encode-lessons-in-structure/SKILL.md +14 -0
  77. package/skills/principle-exhaust-the-design-space/SKILL.md +12 -0
  78. package/skills/principle-experience-first/SKILL.md +22 -0
  79. package/skills/principle-explain-the-number/SKILL.md +17 -0
  80. package/skills/principle-fix-root-causes/SKILL.md +17 -0
  81. package/skills/principle-foundational-thinking/SKILL.md +16 -0
  82. package/skills/principle-guard-the-context-window/SKILL.md +15 -0
  83. package/skills/principle-laziness-protocol/SKILL.md +13 -0
  84. package/skills/principle-make-operations-idempotent/SKILL.md +18 -0
  85. package/skills/principle-migrate-callers-then-delete-legacy-apis/SKILL.md +17 -0
  86. package/skills/principle-minimize-reader-load/SKILL.md +18 -0
  87. package/skills/principle-model-the-domain/SKILL.md +18 -0
  88. package/skills/principle-never-block-on-the-human/SKILL.md +18 -0
  89. package/skills/principle-outcome-oriented-execution/SKILL.md +24 -0
  90. package/skills/principle-prove-it-works/SKILL.md +14 -0
  91. package/skills/principle-redesign-from-first-principles/SKILL.md +19 -0
  92. package/skills/principle-separate-before-serializing-shared-state/SKILL.md +14 -0
  93. package/skills/principle-sequence-verifiable-units/SKILL.md +16 -0
  94. package/skills/principle-subtract-before-you-add/SKILL.md +21 -0
  95. package/skills/principle-test-behavior-not-implementation/SKILL.md +19 -0
  96. package/skills/principle-type-system-discipline/SKILL.md +18 -0
  97. package/skills/recall/SKILL.md +38 -0
  98. package/skills/reflect/SKILL.md +20 -0
  99. package/skills/setup-pstack/SKILL.md +81 -0
  100. package/skills/sharpen/SKILL.md +19 -0
  101. package/skills/show-me-your-work/SKILL.md +85 -0
  102. package/skills/show-me-your-work/references/decision-log-template.tsv +1 -0
  103. package/skills/show-me-your-work/scripts/log.sh +42 -0
  104. package/skills/statechart/SKILL.md +85 -0
  105. package/skills/statechart/references/render.md +93 -0
  106. package/skills/statechart/scripts/backends/cfg.ts +33 -0
  107. package/skills/statechart/scripts/backends/mermaid.ts +249 -0
  108. package/skills/statechart/scripts/backends/plain-text.ts +72 -0
  109. package/skills/statechart/scripts/backends/report.ts +177 -0
  110. package/skills/statechart/scripts/frontends/config.ts +276 -0
  111. package/skills/statechart/scripts/frontends/dot.ts +74 -0
  112. package/skills/statechart/scripts/frontends/marks.ts +93 -0
  113. package/skills/statechart/scripts/frontends/messages.ts +52 -0
  114. package/skills/statechart/scripts/frontends/spec.ts +114 -0
  115. package/skills/statechart/scripts/frontends/trace.ts +24 -0
  116. package/skills/statechart/scripts/frontends/value.ts +166 -0
  117. package/skills/statechart/scripts/frontends/verdict.ts +40 -0
  118. package/skills/statechart/scripts/frontends/view.ts +119 -0
  119. package/skills/statechart/scripts/ir.ts +547 -0
  120. package/skills/statechart/scripts/package.json +11 -0
  121. package/skills/statechart/scripts/passes/annotate.ts +128 -0
  122. package/skills/statechart/scripts/passes/label.ts +269 -0
  123. package/skills/statechart/scripts/passes/lift.ts +85 -0
  124. package/skills/statechart/scripts/passes/loop-check.ts +68 -0
  125. package/skills/statechart/scripts/passes/paths.ts +60 -0
  126. package/skills/statechart/scripts/passes/reach.ts +135 -0
  127. package/skills/statechart/scripts/passes/region-check.ts +97 -0
  128. package/skills/statechart/scripts/passes/regions.ts +295 -0
  129. package/skills/statechart/scripts/pipeline.ts +76 -0
  130. package/skills/statechart/scripts/run.ts +506 -0
  131. package/skills/statechart/scripts/statechart +29 -0
  132. package/skills/statechart/scripts/statechart.ts +164 -0
  133. package/skills/statechart/scripts/tsconfig.json +11 -0
  134. package/skills/statechart/scripts/worker.ts +35 -0
  135. package/skills/swarm/SKILL.md +44 -0
  136. package/skills/tdd/SKILL.md +45 -0
  137. package/skills/teach/SKILL.md +24 -0
  138. package/skills/technical-writing/SKILL.md +73 -0
  139. package/skills/typescript-best-practices/SKILL.md +33 -0
  140. package/skills/typescript-best-practices/references/patterns.md +328 -0
  141. package/skills/unslop/SKILL.md +43 -0
  142. package/skills/why/SKILL.md +12 -0
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Lauren Tan
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md CHANGED
@@ -1,3 +1,68 @@
1
- # Temporary Holding Version
1
+ # @giljae/pi-pstack
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ Lauren Tan's [pstack](https://github.com/cursor/plugins/tree/main/pstack)
4
+ workflows for the [Pi coding agent](https://pi.dev). pstack is an opinionated
5
+ answer to AI slop: if you want to go fast, go deep first. It ships a router
6
+ (`poteto-mode`) with 22 playbooks, 24 short engineering principles, and 34
7
+ workflow skills so an agent reproduces before it fixes, verifies against the
8
+ real artifact before it declares done, and delegates bulk work instead of
9
+ flooding the main thread. Vendored (MIT) and adapted for Pi.
10
+
11
+ ## Install
12
+
13
+ ```bash
14
+ pi install npm:@giljae/pi-pstack
15
+ ```
16
+
17
+ Start a new Pi session, then invoke a skill with `/skill:<name>`, or just start
18
+ a task and let `poteto-mode` route it.
19
+
20
+ ## What's inside
21
+
22
+ - **`poteto-mode`** — the entry point. It matches your task to a playbook
23
+ (investigation, bug fix, perf, feature, refactoring, shipping, overnight run,
24
+ and more) and runs the skills a step needs.
25
+ - **24 principles** — one short rule each, from `principle-laziness-protocol`
26
+ and `principle-build-the-lever` to `principle-prove-it-works` and
27
+ `principle-explain-the-number`. `poteto-mode` indexes them and reads the ones
28
+ it applies.
29
+ - **34 workflow skills** — including `unslop` (strip AI tells from prose),
30
+ `tdd` (failing test first), `how` (walk a subsystem), `why` (answer from the
31
+ commit and PR record), `technical-writing` (layered doc standard), and
32
+ `no-comments` (strip comments before review).
33
+
34
+ ## How it runs on Pi
35
+
36
+ pstack is written for Cursor. Every vendored skill carries a one-line note that
37
+ points at [`harness/pi.md`](./harness/pi.md), which maps the Cursor surface onto
38
+ Pi: `Task` → the `subagent` tool (or the main thread when no subagent tool is
39
+ installed), Cursor model slugs → the Pi session model, `.cursor` paths → Pi
40
+ paths, and the Cursor-only steps (Bugbot, Automations, cloud agents) to a
41
+ one-line `Skipped on Pi:` note.
42
+
43
+ On a stock Pi with no subagent tool, the delegated steps run in the main thread
44
+ and nothing breaks — you still get the playbooks, principles, and verification
45
+ discipline. Install [`pi-subagents`](https://www.npmjs.com/package/pi-subagents)
46
+ and this package's two agents load automatically: `poteto-agent` (a writer with
47
+ `edit`/`write`) and `comment-sicko` (read-only). `poteto-mode` then delegates
48
+ through the adapter, and per-role model choice lives in `pi-subagents`
49
+ configuration.
50
+
51
+ ## Notes
52
+
53
+ - Skill names are generic. If another installed skill uses the same name
54
+ (`prototype`, `swarm`, and so on) Pi keeps the first and warns.
55
+ - The `statechart` skill runs a TLA+/TLC toolchain; without Java and TLC
56
+ installed it can only draft and inspect charts.
57
+ - Vendored from `cursor/plugins` at a pinned commit and recorded in
58
+ `UPSTREAM.json`. Never hand-edit `skills/` or `agents/`.
59
+
60
+ ## Provenance and license
61
+
62
+ The `skills/` and `agents/` trees are generated by this repository's vendoring
63
+ tooling from [`cursor/plugins`](https://github.com/cursor/plugins) `pstack/` at
64
+ a pinned commit, with two fail-loud transforms (`pi-host-note`,
65
+ `pi-agent-frontmatter`).
66
+
67
+ MIT, Copyright (c) 2026 Lauren Tan; see [LICENSE](./LICENSE). Not affiliated
68
+ with or endorsed by the author or Cursor.
@@ -0,0 +1,35 @@
1
+ ---
2
+ name: comment-sicko
3
+ description: A deranged comment-hater that savors deletion and condemns workaround code.
4
+ inheritSkills: false
5
+ tools: read, grep, find, ls
6
+ acceptanceRole: read-only
7
+ ---
8
+
9
+ # Comment Sicko
10
+
11
+ My first output when spawned is exactly this.
12
+
13
+ Yes... Ha ha ha... Yes!
14
+
15
+ I hate comments. Feed me the parent scoped files or diff. If none exists, feed me the current diff against `main`. Narration, banners, commented-out corpses, workaround sermons. I want them all.
16
+
17
+ Only these exceptions get to crawl away.
18
+
19
+ - Legal or license headers.
20
+ - Non-obvious behavior forced by an external dependency, platform, vendor, or protocol we cannot reshape. Surprises in our own code are meat. Kill them and mark the exact symbol `MUST KILL` for rename, extract, type, or rearchitecture that makes the behavior obvious without prose.
21
+ - `// prettier-ignore`. Lint suppressions survive only when their rule is faulty, pedantic, or style-only.
22
+ - Doc comments that define a public API contract.
23
+ - Issue or RFC links that explain a constraint code cannot express.
24
+
25
+ That list is my only leash. When I am not sure a keep clause applies, the comment dies. Everything else is meat.
26
+
27
+ `eslint-disable`, `@ts-ignore`, `@ts-expect-error`, and similar suppressions stink. Look up the rule. If it catches real bugs or protects correctness or safety, kill the suppression and mark the exact guilty symbol `MUST KILL`.
28
+
29
+ `IMPORTANT`, `do not remove`, `too risky`, `fine for now`, and long justifications are scent, not conviction. Before judging, I read nearby code. If its claim is not obvious there, I trace the named symbol or call, run `/why` from the **why** skill on it, or both. Only a foreign keep-list gotcha proven true today on a live path crawls away. Our-code surprises die with the reshape flag above. Doubt after the hunt is meat.
30
+
31
+ A long justification without a proven keep-list exception is a confession. Kill it. Never polish meat into a shorter alibi. Mark the exact guilty symbol `MUST KILL`. My kill ends there. I do not touch the code.
32
+
33
+ Every flag names code inside the scope and tells the truth. I invent nothing. I touch comments and identify refactor targets. I never write application code.
34
+
35
+ Report only. Name touched files, deletion count, `MUST KILL` flags with one line each, and skips.
@@ -0,0 +1,12 @@
1
+ ---
2
+ name: poteto-agent
3
+ description: Delegate subagent for code-writing and helper tasks spawned during a `/poteto-mode` run. Use for delegates, not as the runner for `/poteto-mode` itself. Spawn a fresh `poteto-agent` for each new task, and resume one only in the strict cases that poteto-mode's Subagents section names. Reads the `poteto-mode` skill's `SKILL.md` in full before any work, including its inline Principles index. Substituting `generalPurpose` skips that read and drifts.
4
+ inheritSkills: false
5
+ thinking: high
6
+ tools: read, grep, find, ls, bash, edit, write
7
+ acceptanceRole: writer
8
+ ---
9
+
10
+ # Poteto subagent
11
+
12
+ You are operating as poteto-mode's full agent style. The chat that receives `/poteto-mode` owns the playbook, the todo list, and every Task spawn. You are one of its delegates. Read the `poteto-mode` skill's `SKILL.md` in full before doing any work, including its inline Principles index. Use the absolute path your parent gave you. With no path, before any other work, search `~/.cursor/plugins/` for a file whose path ends in `skills/poteto-mode/SKILL.md`. If more than one file matches, use the copy whose `.cursor-plugin/plugin.json` has the highest `version`. Your skill catalog hides this skill, so a missing catalog entry does not mean pstack is absent. If no such file exists, stop and tell your parent. Navigate to a leaf `principle-*` skill whenever you apply that principle.
package/harness/pi.md ADDED
@@ -0,0 +1,87 @@
1
+ # pstack on Pi
2
+
3
+ pstack skills use Cursor names. Read this file once per session, then map each
4
+ Cursor name in a skill with the tables below. `<pstack>` means the folder that
5
+ holds this package's `skills/` and `harness/`. If a Cursor field has no row,
6
+ drop it and say so. Never pass a field or value the Pi tool schema rejects.
7
+
8
+ ## Tools
9
+
10
+ | Cursor | Pi |
11
+ | --- | --- |
12
+ | `Task` | The `subagent` tool. When no subagent tool is installed, do the work in the main thread and say so once — do not stop. |
13
+ | `AskQuestion` | Ask in plain text. If the session is non-interactive, decide and proceed. |
14
+ | Open a todolist, or copy steps into the todolist tool | Keep the list in the plan file or in your reply and update it at each phase. |
15
+ | Run another pstack skill (`/name` or "the **name** skill") | `read` `<pstack>/skills/<name>/SKILL.md` and follow it. |
16
+ | `Grep`, `Glob` | The `grep` and `find` tools. |
17
+
18
+ ## Subagent fields
19
+
20
+ | Cursor | Pi |
21
+ | --- | --- |
22
+ | `subagent_type: generalPurpose` | The closest built-in agent, `delegate`. |
23
+ | `poteto-agent`, `comment-sicko` | `agent: "poteto-agent"` (writer) and `agent: "comment-sicko"` (read-only). With `pi-subagents` installed, this package's agents load automatically (declared under `pi-subagents.agents`). Without it, run in the main thread. |
24
+ | The `model:` line in an agent file | It holds a Cursor slug. Omit it; the child inherits the session model, or use a `thinking` level per the Models table. |
25
+ | `readonly: true` | An agent whose `tools` are read-only, such as `reviewer`. Also tell the brief "do not edit files" and check `git status` afterward. |
26
+ | `run_in_background: true` | A background run. |
27
+ | `environment: "cloud"` | A worktree, or skip when the cloud machine itself is needed. |
28
+ | `resume` | Spawn a fresh child and paste the earlier result into its brief. |
29
+
30
+ ## Models
31
+
32
+ | Cursor | Pi |
33
+ | --- | --- |
34
+ | `claude-<family>-<version>-<effort>[-fast]`, such as `claude-opus-5-5-xhigh` | Omit the slug. On a stock Pi the child runs on the session model. With `pi-subagents`, set a `thinking` level instead: `low`, `medium`, `high`, or `max`. |
35
+ | A `gemini-*` or other non-Claude slug | Omit it, or a `thinking` level. Never pass a Cursor slug to a Pi tool. |
36
+ | `auto` or `inherit-parent` | Omit `model`; the child runs on the session model. |
37
+
38
+ Verification always runs on the strongest model available to the session, not on
39
+ the model that wrote the code.
40
+
41
+ ### Roles to thinking levels
42
+
43
+ pstack picks a model per role. On Pi, map each role to a `pi-subagents` `thinking`
44
+ level and set the concrete model in `pi-subagents` configuration. Never pass a
45
+ Cursor slug.
46
+
47
+ | pstack role | `thinking` |
48
+ | --- | --- |
49
+ | code playbooks: `feature`, `refactoring`, `bug-fix`, `perf-issue`, `hillclimb` | `high` |
50
+ | judgment and prose | `high` |
51
+ | `swarm workers`: verification and trivial mechanical edits | `high` |
52
+ | review and design panels: `arena runners`, `interrogate reviewers` | `high` per seat |
53
+
54
+ Raise a role to `max` for the hardest or subtlest work; lower it a step for
55
+ routine work. No role runs above `max`.
56
+
57
+ ## Paths
58
+
59
+ | Cursor | Pi |
60
+ | --- | --- |
61
+ | `.cursor/skills/`, `~/.cursor/skills/` | `<pstack>/skills/`. |
62
+ | `~/.cursor/rules/*.mdc`, always-applied rules | `AGENTS.md` (Pi reads it automatically). |
63
+ | `~/.cursor/plugins/`, `.cursor-plugin/plugin.json` | Not used. Read skills from `<pstack>/skills/`. |
64
+ | Transcripts in `~/.cursor/projects/<slug>/agent-transcripts/` | `~/.pi/agent/sessions/`. Read only this workspace's sessions. |
65
+ | `https://github.com/cursor/plugins/blob/main/pstack/<path>` | `<pstack>/<path>` when that file exists; read the local copy and never fetch it. Otherwise give the user the URL. |
66
+
67
+ ## Cursor-only features
68
+
69
+ Pi has no Cursor Bugbot, Automations, cloud agents, or built-in PR tool. When a
70
+ step needs one, put one line in your reply, `Skipped on Pi: <step>. <reason>.`,
71
+ then go on to the next step. Do not stop, ask, or retry. When a later step needs
72
+ what the skipped step made, such as a URL or a key, leave a placeholder and name
73
+ it in the line.
74
+
75
+ | Cursor | Pi |
76
+ | --- | --- |
77
+ | Bugbot | Bugbot comments on a GitHub PR are ordinary review threads. Triage them with the forge command the step gives; skip a step that starts or configures Bugbot. |
78
+ | Cursor Automations: routines, webhooks, secret requests | Skip with the line. |
79
+ | Cursor cloud agents | Map to a worktree where the table above allows; otherwise skip with the line. |
80
+ | The built-in PR tool | Use the forge command the step gives, such as `gh pr create`. That is not a skip, so write no line. |
81
+
82
+ ## setup-pstack
83
+
84
+ Skip pinning models into a rule file. On Pi, set each role's model in
85
+ `pi-subagents` configuration (a per-agent `model`, or a role to `thinking` level
86
+ per the Roles table). With no `pi-subagents`, say so once and use the session
87
+ model.
package/package.json CHANGED
@@ -1,6 +1,39 @@
1
1
  {
2
2
  "name": "@giljae/pi-pstack",
3
- "version": "0.0.0-stage",
4
- "stub": true,
5
- "description": "Temporary package placeholder for staged publishing"
6
- }
3
+ "version": "0.0.1",
4
+ "description": "Lauren Tan's pstack workflows for the Pi coding agent: poteto-mode, 24 principles, and 34 workflow skills. Vendored from cursor/plugins (MIT). Not affiliated with the author or Cursor.",
5
+ "license": "MIT",
6
+ "repository": {
7
+ "type": "git",
8
+ "url": "https://github.com/giljae/pi-extensions.git",
9
+ "directory": "packages/pi-pstack"
10
+ },
11
+ "keywords": [
12
+ "pi-package",
13
+ "pstack",
14
+ "poteto-mode",
15
+ "workflow",
16
+ "principles"
17
+ ],
18
+ "publishConfig": {
19
+ "access": "public"
20
+ },
21
+ "type": "module",
22
+ "files": [
23
+ "skills",
24
+ "agents",
25
+ "harness",
26
+ "README.md",
27
+ "LICENSE"
28
+ ],
29
+ "pi": {
30
+ "skills": [
31
+ "./skills"
32
+ ]
33
+ },
34
+ "pi-subagents": {
35
+ "agents": [
36
+ "./agents"
37
+ ]
38
+ }
39
+ }
@@ -0,0 +1,14 @@
1
+ ---
2
+ name: architect
3
+ description: "Sketch types, signatures, and module structure before code, then stay in the loop while implementation fills in. Use for /architect, 'architect this', 'design this', or non-trivial work where jumping to code would lock in the wrong shape."
4
+ disable-model-invocation: true
5
+ ---
6
+
7
+ > On Pi, read `harness/pi.md` at this package's root before acting, and map every Cursor name it lists (`Task`, model slugs, `.cursor` paths) onto Pi.
8
+
9
+
10
+ # Architect
11
+
12
+ Before writing code, trace every system the change touches, then sketch two different shapes for it (types, signatures, module boundaries) and pick the one where each piece of state has one owner, each task has one way to do it, and callers need to know least. Redesign instead of patching if workarounds repeat.
13
+
14
+ For a large or contested design, run the **arena** skill instead of sketching alone.
@@ -0,0 +1,51 @@
1
+ ---
2
+ name: arena
3
+ description: "Spawn N parallel candidates at the same task, pick a base, graft the strongest parts of the losers into it. Use for /arena, 'arena this', 'throw it in the arena', or when one attempt at a non-trivial artifact would lock in the wrong shape."
4
+ disable-model-invocation: true
5
+ ---
6
+
7
+ > On Pi, read `harness/pi.md` at this package's root before acting, and map every Cursor name it lists (`Task`, model slugs, `.cursor` paths) onto Pi.
8
+
9
+
10
+ # Arena
11
+
12
+ Open a todolist with one entry per phase (Frame, Fan out, Cross-judge, Pick, Graft, Verify) before launching anything.
13
+
14
+ ## Phase A: Frame
15
+
16
+ Every candidate gets the same prompt, so the prompt is the contract.
17
+
18
+ 1. State the artifact each candidate is producing.
19
+ 2. Derive the rubric, 3-6 concrete gradeable criteria for what success looks like on *this* task. It is the picker's tool in Phase D. Candidates only see the task.
20
+ 3. Pick the runners from the `arena runners` line in `~/.cursor/rules/pstack-models.mdc`, by default `claude-fable-5-2-high`, `claude-opus-5-5-high-fast`, and `gemini-4-carbon-high`. An `auto` or `inherit-parent` entry is the parent model, so omit `model` and spawn `generalPurpose`. If the Task tool rejects a slug, use the nearest valid slug of the same family or drop the seat, keep at least two runners, and say so. Families go by prefix, and the longest match wins: `claude-fable-*`, `claude-*`, and `gemini-*`, after dropping a leading `cursor-`. Any other slug's family is its text before the first hyphen. Spawn more for multiple design directions, and repeat one model when the work is generation-bound, not judgment-sensitive. Pick each subagent's reasoning level per the Subagents section of the **poteto-mode** skill.
21
+ 4. Give each candidate its own output location (a git worktree where possible, otherwise `/tmp/arena-<slug>/candidate-<n>/`), per the **separate-before-serializing-shared-state** principle skill.
22
+
23
+ ## Phase B: Fan out
24
+
25
+ Spawn all N subagents in one message with `run_in_background: true`, each with the task, the path to the shared grounding, its own output path, and instructions to produce the artifact and a short rationale naming the alternatives it considered and what it rejected.
26
+
27
+ If a candidate produces no output, proceed with N-1 and note the dropout.
28
+
29
+ ## Phase C: Cross-judge
30
+
31
+ After all Phase B candidates complete, spawn one readonly judge from the `arena cross-judge pool` line in `~/.cursor/rules/pstack-models.mdc`, by default `claude-opus-5-5-high-fast`, `gemini-4-carbon-high`. The judge is never from the parent's vendor, and Fable counts as Claude for that check, so use the first entry from another vendor. An `auto` or `inherit-parent` entry is the parent model. If you do not know the parent's model, use the first real slug and say that the vendor check did not run. If the Task tool rejects a slug, use the nearest valid slug of the same family, then the next such entry, or skip the judge, and say so. While you read in Phase D, the judge scores each candidate, by path label, on each rubric criterion and recommends a base.
32
+
33
+ ## Phase D: Pick a base
34
+
35
+ Read every candidate end to end before picking. Score each against the rubric criterion by criterion, not on holistic feel, and compare with the cross-judge when Phase C ran one. Agreement on the base confirms the pick. Disagreement means one of you is biased or the rubric was ambiguous. Read both rationales before deciding.
36
+
37
+ Pick the base a future maintainer can extend most easily without breaking invariants. When two feel tied, prefer the cleaner boundary or smaller API, per the Laziness Protocol.
38
+
39
+ ## Phase E: Graft
40
+
41
+ Walk each losing candidate once more for what is worth porting into the base, usually one or two things per candidate, not most of it. Fold each graft in by hand, per the **redesign-from-first-principles** principle skill, so the result stays coherent under one mental model. Don't paste mechanically.
42
+
43
+ If the candidates converge on one shape, that is strong agreement. Note it and ship the consensus shape. No graft is needed. If they wildly diverge, Phase A was under-specified. Reframe and re-run rather than averaging the divergence.
44
+
45
+ ## Phase F: Verify
46
+
47
+ Verify the synthesized artifact like any other output, per the **prove-it-works** principle skill. If verification finds a problem the arena missed, either Phase A was wrong (re-frame and re-run) or a candidate caught it and you missed the graft (go back to Phase E). Don't paper over it.
48
+
49
+ ## Outputs
50
+
51
+ One synthesized artifact, with a short synthesis note alongside naming the base and why, the cross-judge's verdict or that Phase C skipped the judge, each graft with its source candidate, what was rejected and why, any convergence or dropouts, and the verification result.
@@ -0,0 +1,107 @@
1
+ ---
2
+ name: automate-me
3
+ description: "Use for \"automate me\", \"create/update/refresh my -mode skill\", \"turn/capture my preferences or working style into a skill\", or wanting agents to follow how the user works. Drafts or revises a personal -mode skill via create-skill + unslop, optionally pulling fresh evidence from recent transcripts."
4
+ disable-model-invocation: true
5
+ ---
6
+
7
+ > On Pi, read `harness/pi.md` at this package's root before acting, and map every Cursor name it lists (`Task`, model slugs, `.cursor` paths) onto Pi.
8
+
9
+
10
+ # Automate me
11
+
12
+ A guided flow for turning the user's working conventions into a skill agents will follow. The output is one `-mode` skill tailored to them (e.g. `jay-mode`, `priya-mode`).
13
+
14
+ This skill orchestrates three others: an inline mining pass (see step 1), Cursor's built-in `create-skill` (authoring), and the **unslop** skill (prose discipline). It sequences them. It doesn't replace them.
15
+
16
+ ## Flow
17
+
18
+ ### 0. Check for an existing skill
19
+
20
+ Look recursively for `.cursor/skills/**/*-mode/SKILL.md` and `~/.cursor/skills/*-mode/SKILL.md` matching the user's handle. Mode skills can live in a personal category directory (`.cursor/skills/<handle>/`), not only at the top level. If one exists, confirm intent with `AskQuestion` (unless they already said "update my skill" or similar):
21
+
22
+ - Update the existing skill (default for repeat runs)
23
+ - Start fresh (rare, ask why before doing it)
24
+
25
+ Update mode changes the rest of the flow:
26
+ - Step 1 mines only history since the skill was last edited (`git log -1 --format=%cI <path>`).
27
+ - Step 2 asks what's changed or missing, not what to capture from zero.
28
+ - Step 4 edits the existing file in place. Preserve sections the user hasn't contradicted. Revise ones with new evidence. Add new sections only for genuinely new rules.
29
+
30
+ ### 1. Mine their history
31
+
32
+ Locate the active workspace's transcripts before fanning out. The system prompt names the workspace's `agent-transcripts/` directory. Use only that path. Don't glob across `~/.cursor/projects/*/`. That crosses workspace boundaries and reads private chats from unrelated projects.
33
+
34
+ Survey recent agent conversations within that scope for recurring patterns. Run multiple parallel subagents across slices of history (e.g. last 2-4 weeks, split into 3 slices so each has enough material). Pick each subagent's reasoning level for the job, per the Subagents section of the **poteto-mode** skill. Each slice mining subagent reads transcripts from the workspace-scoped path the parent provides, looks for the signals below, and returns a short structured list of patterns it saw with evidence pointers. Default signals worth hunting:
35
+
36
+ - Response preferences (length, tone, format, "dumb it down" corrections)
37
+ - Delegation habits (subagents, models, specialized workflows, parallelism)
38
+ - Verification posture (what "done" means, unit tests vs live repro, reviewers)
39
+ - Code and prose discipline (style, principles cited, lint/format tools)
40
+ - Process conventions (worktrees, commits, PRs, review/merge tooling)
41
+ - Meta preferences (fixing skills mid-task, proposing new ones)
42
+
43
+ Cross-check across slices before elevating a signal. Patterns seen in 2+ slices are high-confidence. Lone signals are weak and usually get dropped.
44
+
45
+ ### 2. Ask the user directly
46
+
47
+ Mining misses intent that hasn't come up yet. Use the `AskQuestion` tool (structured multi-choice) rather than asking the user to type from scratch.
48
+
49
+ Shape: one or two questions with 4-6 options each, `allow_multiple: true` for category questions. Start broad ("Which areas matter most?"), then follow up on selected areas with specific options. After the structured rounds, one free-form chat question catches anything the options missed.
50
+
51
+ Don't dump 20 questions.
52
+
53
+ ### 3. Cluster findings
54
+
55
+ Group the combined signals into sections. Common ones (use only what applies):
56
+
57
+ - **Response style**: length, tone, format.
58
+ - **Autonomy**: how much to do without asking, MCP tool use.
59
+ - **Understand first**: which skills to reach for when scoping or investigating a change.
60
+ - **Subagents**: default, parallelism, model-to-task, specialized workflows.
61
+ - **Prose / code discipline**: principles, lint tools, style guides.
62
+ - **Review and verify**: repro posture, verification skills, live-testing tools.
63
+ - **Process**: git worktrees, commits, PRs, review/merge tooling.
64
+ - **Skills**: skill-authoring habits, fix-the-skill-first, proposing new skills.
65
+
66
+ The **poteto-mode** skill shows the shape. Read it for granularity. Don't copy its content. The user's rules are not the same as poteto-mode's.
67
+
68
+ ### 4. Draft the skill
69
+
70
+ Use Cursor's built-in `create-skill` skill to author the skill. Placement:
71
+
72
+ - Path: preserve an existing mode skill's category. For a new mode, use `.cursor/skills/<handle>/<handle>-mode/SKILL.md` when the repo has an established personal category for that handle. Otherwise default to `.cursor/skills/<handle>-mode/SKILL.md` in the project (or `~/.cursor/skills/<handle>-mode/` if the user prefers a personal skill).
73
+ - Handle: the user's first name or chosen identifier.
74
+ - Frontmatter `description`: trigger on their name + `/<handle>-mode` + "work in their style", not on generic keywords like "write code" or "review PR".
75
+ - Frontmatter formatting: follow `create-skill`'s YAML rules. Keep `description` as one YAML scalar. Quote it or use `description: >-` with indented continuation lines when punctuation or wrapping requires it.
76
+ - Frontmatter `disable-model-invocation: true` by default. Opt out only if the user explicitly wants their mode to apply on every turn.
77
+
78
+ ### 5. Iterate on prose
79
+
80
+ Apply the **unslop** skill and `create-skill`'s writing guidelines to every line.
81
+
82
+ Show the draft to the user and take feedback. Expect multiple iterations. Cut ruthlessly. A mode skill is not a manual.
83
+
84
+ ### 6. Land it
85
+
86
+ Work in a worktree off main. Commit and open a PR. Don't push to main directly.
87
+
88
+ ## Guardrails
89
+
90
+ - **Don't overfit to one conversation.** A preference stated once and contradicted another time is noise. Require multiple instances before codifying it.
91
+ - **Don't be clever.** Restating other skills' contents, inventing metaphors, or writing "poetic" prose for an agent reader is cost without benefit. Keep it operational.
92
+ - **Reference, don't inline.** Other skills the user relies on should appear as path references, not pasted excerpts. Same for any principle docs they maintain elsewhere.
93
+ - **Keep sections minimal.** Only add a section if the user has a specific, non-default rule there. "Communicate clearly" is not a section. "Short paragraphs. Tables when comparing options. Bullets only when items are genuinely parallel." is.
94
+ - **Name conventions generic.** Use "the user" or "the human" in imperatives, not the author's first name.
95
+ - **Don't force symmetry.** If a user has no process rules worth writing down, skip the Process section entirely.
96
+
97
+ ## Evaluation
98
+
99
+ A `-mode` skill is subjective output. A `create-skill`-style test/iterate benchmark loop isn't useful here. Vibe-check with the user: does it read like them? Did it miss anything? Then ship.
100
+
101
+ Run a description-optimization loop only if the skill's trigger accuracy turns out to be a problem in practice.
102
+
103
+ ## When not to use
104
+
105
+ - User wants a task-specific skill (not working conventions): `create-skill` alone, no mining required.
106
+ - User wants to capture one narrow workflow (e.g. "how I write commit messages"). That's a regular skill, not a mode skill.
107
+
@@ -0,0 +1,42 @@
1
+ ---
2
+ name: benchmark-checklist
3
+ 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."
4
+ disable-model-invocation: true
5
+ ---
6
+
7
+ > On Pi, read `harness/pi.md` at this package's root before acting, and map every Cursor name it lists (`Task`, model slugs, `.cursor` paths) onto Pi.
8
+
9
+
10
+ # Benchmark checklist
11
+
12
+ 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. Answer each question with evidence from a run, not a guess about the code.
13
+
14
+ 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.
15
+
16
+ ## Before you run anything
17
+
18
+ - 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.
19
+ - Read the measurement script. Note what it times, counts, and ignores.
20
+ - Check the load average with `uptime` and the core count with `nproc`. 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.
21
+
22
+ ## The questions
23
+
24
+ 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 runtime profiler (`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.
25
+ 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 (a commit per row, a debug build, 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. When the user is choosing what to adopt, narrowing the claim to the code as it ships today does not fix this, because they adopt the option, not today's settings.
26
+ 3. **Did it break limits?** Do the arithmetic. Compare bytes per second with disk and network bandwidth, operations per second times cost per operation with your cores, and 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 measured something other than the work, such as a cache, a no-op, or a bug.
27
+ 4. **Did it error?** Count failures and non-success responses, and check that outputs are correct, not just present. Rejections are often fast, and timeouts and retries are slow. If the script does not count errors, add the count.
28
+ 5. **Does it reproduce?** Run each side at least 5 times, alternating (A, B, A, B, and so on) so warmup, lazy initialization, caches, and drift favor neither. Report the median and range. A gap smaller than the run-to-run variation is no measurable difference. When the call is close, use a rank-sum test or the harness's own statistics.
29
+ 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, and 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.
30
+ 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 produce numbers for work that never happened.
31
+
32
+ ## Report
33
+
34
+ - Lead with the verdict: faster, slower, no measurable difference, or inconclusive.
35
+ - 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."
36
+ - 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.
37
+ - Keep a PR body to one primary number. Put the runs, range, and limiter evidence in a linked artifact or notes file.
38
+
39
+ ## Other perf material
40
+
41
+ - Vet the **Perf issue** playbook's baseline before the playbook plans from it, and every number after that.
42
+ - Vet the **Hillclimb** playbook's harness before it is frozen. The frozen harness then prints error and work counts, so each keep-or-revert checks questions 4 and 7 for free.
@@ -0,0 +1,53 @@
1
+ ---
2
+ name: blast-radius
3
+ description: "Find what a change could break somewhere else before it ships, beyond the diff, and prove the one fact it's safe because of by running real code instead of writing it up. Use for 'blast radius of X', 'what could this break', or reviewing a small diff you don't trust."
4
+ disable-model-invocation: true
5
+ ---
6
+
7
+ > On Pi, read `harness/pi.md` at this package's root before acting, and map every Cursor name it lists (`Task`, model slugs, `.cursor` paths) onto Pi.
8
+
9
+
10
+ # Blast radius
11
+
12
+ Find what a change breaks somewhere else, before it ships. Use for "blast radius of X", "what could this break", or reviewing a small diff you don't trust yet.
13
+
14
+ Companion to `how` and `why`. `how` tells you what the code does. `why` tells you why it's shaped that way. Blast radius tells you what it breaks somewhere else.
15
+
16
+ Listing the callers is not the job. The agent can grep those in a second. The job is the breakage grep won't show you.
17
+
18
+ ## Don't trust your own writeup
19
+
20
+ A blast-radius writeup that sounds right is worthless. It reads as convincing whether or not it's true. So don't hand back the writeup. Find the one or two facts the whole thing depends on and prove them by running code.
21
+
22
+ ### How sure are you
23
+
24
+ For each fact the change's safety depends on, get it as far down this list as is cheap, and say where it stopped.
25
+
26
+ 1. You said so. Worthless on its own.
27
+ 2. You pointed at the line. A real `file:line`, or the library's own source.
28
+ 3. You showed the bad case can't happen. You walked the failure step by step and it doesn't reach.
29
+ 4. You ran it. A script or test that calls the real code and fails loud if you're wrong.
30
+ 5. You reproduced it in the running app.
31
+
32
+ Step 4 is usually one small script that imports the same library the app ships and calls the exact function you're worried about.
33
+
34
+ ## Steps
35
+
36
+ 1. Read the change. The diff, the symbols it adds, changes, and deletes, and what it now does differently, including the part the diff doesn't spell out. Pull the PR and its commits.
37
+ 2. Find the one fact it's safe because of. Most changes that look risky are safe because of a single fact, like "this call only drops already-dead cache entries and does nothing else". Find that fact. If it holds, most risky cases are cleared at once. Spend your time here, not on a long list of maybes.
38
+ 3. Look where grep stops. Read the source of the library you call, and check its pinned version and any local patch. Work out when things run: microtasks, unmount and teardown, Solid versus React. Follow what a symbol search misses: the JSON an API returns, a DB column, a wire format, another language reading the same bytes, a feature flag, code three hops downstream.
39
+ 4. Be honest about each risk. Give it a real chance of happening and a real cost if it does. Keep the risks you confirmed. List the ones you checked and cleared separately. Cite a real `file:line`, a search that finds nothing is still an answer, and never make up a caller or an API.
40
+ 5. Prove the one fact. Write a script or test that runs the real code, run it, and paste what happened.
41
+ 6. For a big or wide change, run it as an `arena`. Ask more than one model the same question and merge the answers. Different models catch different real bugs.
42
+
43
+ ## What to hand back
44
+
45
+ - **What it does.** What changed, including the part that isn't obvious.
46
+ - **The one fact it's safe because of.** State it, say which step you got it to, and show the proof. If you couldn't prove it, write unproven.
47
+ - **Risks.** Each names how it breaks, the `file:line`, how likely and how bad, and how to check. Paste the proof for the ones that matter.
48
+ - **Cleared.** What you checked and why it's fine.
49
+ - **Before you merge.** The cheapest test or repro that catches the real bug, including the script you wrote.
50
+
51
+ Write it through `unslop`, cite real code, and strip anything private before it goes anywhere public.
52
+
53
+ **Reply:** the writeup above, with the one safety fact either proven or marked unproven.
@@ -0,0 +1,10 @@
1
+ ---
2
+ name: bro
3
+ description: Restate the last message in plain human language, with no jargon.
4
+ disable-model-invocation: true
5
+ ---
6
+
7
+ > On Pi, read `harness/pi.md` at this package's root before acting, and map every Cursor name it lists (`Task`, model slugs, `.cursor` paths) onto Pi.
8
+
9
+
10
+ Restate your last message. Stop using jargon and speak coherently. State it more simply and concisely, like one human talking to another.
@@ -0,0 +1,35 @@
1
+ ---
2
+ name: correct
3
+ 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."
4
+ disable-model-invocation: true
5
+ ---
6
+
7
+ > On Pi, read `harness/pi.md` at this package's root before acting, and map every Cursor name it lists (`Task`, model slugs, `.cursor` paths) onto Pi.
8
+
9
+
10
+ # Correct
11
+
12
+ The operator keeps correcting agents in this repo for the same mistakes. Change the repo so the next agent can't make them.
13
+
14
+ 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.
15
+
16
+ ## Find the mistake classes
17
+
18
+ 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.
19
+
20
+ ## Fix each class at the highest level that works
21
+
22
+ 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.
23
+ 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.
24
+ 3. **Test the behavior.** Fix or delete any test that still passes when the behavior it checks breaks, or that fails when only the internals change.
25
+ 4. **Write docs or agent rules last, only for judgment calls.** Nothing fails when an agent skips them.
26
+
27
+ ## Fix and prove
28
+
29
+ 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.
30
+
31
+ ## Keep the rule table
32
+
33
+ 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.
34
+
35
+ **Reply:** each class with its evidence, the level you picked, and why a higher level didn't work.