dsh-pstack 0.1.0 → 0.2.0-beta.3
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.
- package/LICENSE +2 -3
- package/README.md +174 -148
- package/README.zh.md +185 -0
- package/assets/logo.png +0 -0
- package/cordis.patch.yml +103 -14
- package/dist/host-contract-CUPSpeNk.d.mts +22 -0
- package/dist/index.d.mts +87 -14
- package/dist/index.mjs +370 -143
- package/dist/models.d.mts +44 -0
- package/dist/models.mjs +201 -0
- package/dist/paths-BT77khwm.mjs +48 -0
- package/dist/{LICENSE → pstack/LICENSE} +1 -2
- package/dist/pstack/README.md +291 -0
- package/{assets → dist/pstack}/agents/comment-sicko.md +1 -1
- package/dist/pstack/agents/poteto-agent.md +9 -0
- package/{assets → dist/pstack}/docs/guide/01-setup.md +11 -9
- package/dist/{assets → pstack}/docs/guide/02-poteto-mode.md +2 -2
- package/{assets → dist/pstack}/docs/guide/04-design.md +4 -4
- package/dist/{assets → pstack}/docs/guide/05-build-and-clean.md +3 -3
- package/dist/{assets → pstack}/docs/guide/06-verify-and-ship.md +11 -1
- package/{assets → dist/pstack}/docs/guide/07-overnight.md +10 -10
- package/dist/{assets → pstack}/docs/guide/09-make-it-yours.md +4 -4
- package/{assets → dist/pstack}/docs/guide/10-recipes-and-pitfalls.md +6 -4
- package/dist/pstack/docs/guide/images/design.jpg +0 -0
- package/dist/pstack/docs/guide/images/overnight.jpg +0 -0
- package/dist/pstack/docs/guide/images/recipes.jpg +0 -0
- package/dist/pstack/docs/guide/images/router.jpg +0 -0
- package/dist/pstack/docs/guide/images/understanding.jpg +0 -0
- package/dist/pstack/docs/guide/images/verification.jpg +0 -0
- package/dist/pstack/docs/harness/dsh.md +98 -0
- package/{assets → dist/pstack}/skills/architect/SKILL.md +5 -5
- package/dist/pstack/skills/arena/SKILL.md +50 -0
- package/{assets → dist/pstack}/skills/automate-me/SKILL.md +14 -13
- package/dist/{assets → pstack}/skills/benchmark-checklist/SKILL.md +1 -3
- package/dist/{assets → pstack}/skills/blast-radius/SKILL.md +1 -3
- package/{assets → dist/pstack}/skills/bro/SKILL.md +0 -2
- package/dist/{assets → pstack}/skills/correct/SKILL.md +1 -3
- package/{assets → dist/pstack}/skills/create-formal-verification-skill/SKILL.md +5 -3
- package/{assets → dist/pstack}/skills/create-verification-skill/SKILL.md +6 -6
- package/{assets → dist/pstack}/skills/figure-it-out/SKILL.md +4 -4
- package/dist/{assets → pstack}/skills/how/SKILL.md +4 -4
- package/{assets → dist/pstack}/skills/how/references/explainer-prompt.md +1 -1
- package/dist/pstack/skills/in-your-own-words/SKILL.md +7 -0
- package/dist/pstack/skills/interrogate/SKILL.md +33 -0
- package/{assets → dist/pstack}/skills/ketchup/SKILL.md +1 -3
- package/dist/pstack/skills/ketchup-video/SKILL.md +29 -0
- package/{assets → dist/pstack}/skills/maintain-formal-verification-skill/SKILL.md +2 -2
- package/dist/{assets → pstack}/skills/maintain-verification-skill/SKILL.md +3 -3
- package/dist/pstack/skills/make-bot-ui/SKILL.md +117 -0
- package/{assets → dist/pstack}/skills/no-comments/SKILL.md +4 -4
- package/{assets → dist/pstack}/skills/poteto-help/SKILL.md +21 -17
- package/dist/{assets → pstack}/skills/poteto-help/references/prompting.md +1 -1
- package/dist/{assets → pstack}/skills/poteto-help/references/recipes.md +3 -3
- package/{assets → dist/pstack}/skills/poteto-mode/SKILL.md +20 -21
- package/dist/{assets → pstack}/skills/poteto-mode/playbooks/authoring-a-skill.md +1 -1
- package/dist/{assets → pstack}/skills/poteto-mode/playbooks/autonomous-run.md +2 -2
- package/{assets → dist/pstack}/skills/poteto-mode/playbooks/autopilot-full.md +7 -7
- package/dist/pstack/skills/poteto-mode/playbooks/autopilot-stack.md +8 -0
- package/{assets → dist/pstack}/skills/poteto-mode/playbooks/babysit.md +3 -3
- package/{assets → dist/pstack}/skills/poteto-mode/playbooks/bug-fix.md +3 -3
- package/dist/{assets → pstack}/skills/poteto-mode/playbooks/eval.md +1 -1
- package/{assets → dist/pstack}/skills/poteto-mode/playbooks/feature.md +1 -1
- package/{assets → dist/pstack}/skills/poteto-mode/playbooks/hillclimb.md +1 -1
- package/{assets → dist/pstack}/skills/poteto-mode/playbooks/multi-phase-plan.md +13 -13
- package/dist/{assets → pstack}/skills/poteto-mode/playbooks/opening-a-pr.md +3 -3
- package/dist/pstack/skills/poteto-mode/playbooks/orchestrate.md +25 -0
- package/dist/{assets → pstack}/skills/poteto-mode/playbooks/perf-issue.md +2 -2
- package/{assets → dist/pstack}/skills/poteto-mode/playbooks/prototype.md +1 -1
- package/dist/{assets → pstack}/skills/poteto-mode/playbooks/refactoring.md +2 -2
- package/{assets → dist/pstack}/skills/poteto-mode/playbooks/runtime-forensics.md +1 -1
- package/{assets → dist/pstack}/skills/poteto-mode/playbooks/session-pickup.md +1 -1
- package/dist/{assets → pstack}/skills/poteto-mode/playbooks/shipping.md +2 -2
- package/{assets → dist/pstack}/skills/poteto-mode/playbooks/visual-parity.md +1 -1
- package/dist/{assets → pstack}/skills/poteto-mode/playbooks/worktree-cleanup.md +2 -2
- package/{assets → dist/pstack}/skills/poteto-mode/scripts/check-plan.mjs +83 -70
- package/dist/{assets/skills/poteto-mode/scripts/check-plan.test.ts → pstack/skills/poteto-mode/scripts/check-plan.test.mjs} +53 -21
- package/dist/pstack/skills/poteto-mode/scripts/expect.mjs +254 -0
- package/dist/pstack/skills/poteto-mode/scripts/support.mjs +93 -0
- package/dist/pstack/skills/poteto-mode/scripts/watch-pr/cli.mjs +123 -0
- package/dist/pstack/skills/poteto-mode/scripts/watch-pr/cli.test.mjs +217 -0
- package/dist/pstack/skills/poteto-mode/scripts/watch-pr/fakes.test-helper.mjs +119 -0
- package/dist/pstack/skills/poteto-mode/scripts/watch-pr/github.mjs +626 -0
- package/dist/pstack/skills/poteto-mode/scripts/watch-pr/github.test.mjs +521 -0
- package/dist/pstack/skills/poteto-mode/scripts/watch-pr/policy.mjs +657 -0
- package/dist/pstack/skills/poteto-mode/scripts/watch-pr/policy.test.mjs +523 -0
- package/dist/pstack/skills/poteto-mode/scripts/watch-pr/render.mjs +106 -0
- package/dist/pstack/skills/poteto-mode/scripts/watch-pr/types.mjs +9 -0
- package/dist/pstack/skills/poteto-mode/scripts/watch-pr/watch-pr.mjs +5 -0
- package/dist/pstack/skills/poteto-mode/scripts/worktree-audit.mjs +668 -0
- package/dist/pstack/skills/poteto-mode/scripts/worktree-audit.test.mjs +134 -0
- package/{assets → dist/pstack}/skills/principle-attack-the-premise/SKILL.md +1 -3
- package/{assets → dist/pstack}/skills/principle-boundary-discipline/SKILL.md +1 -3
- package/{assets → dist/pstack}/skills/principle-build-the-lever/SKILL.md +0 -3
- package/dist/pstack/skills/principle-encode-lessons-in-structure/SKILL.md +11 -0
- package/dist/pstack/skills/principle-exhaust-the-design-space/SKILL.md +9 -0
- package/{assets → dist/pstack}/skills/principle-experience-first/SKILL.md +1 -3
- package/dist/{assets → pstack}/skills/principle-explain-the-number/SKILL.md +3 -4
- package/dist/{assets → pstack}/skills/principle-fix-root-causes/SKILL.md +1 -3
- package/{assets → dist/pstack}/skills/principle-foundational-thinking/SKILL.md +0 -2
- package/dist/{assets → pstack}/skills/principle-guard-the-context-window/SKILL.md +0 -2
- package/dist/{assets → pstack}/skills/principle-laziness-protocol/SKILL.md +1 -3
- package/dist/{assets → pstack}/skills/principle-make-operations-idempotent/SKILL.md +1 -3
- package/dist/{assets → pstack}/skills/principle-migrate-callers-then-delete-legacy-apis/SKILL.md +1 -3
- package/{assets → dist/pstack}/skills/principle-minimize-reader-load/SKILL.md +1 -3
- package/{assets → dist/pstack}/skills/principle-model-the-domain/SKILL.md +1 -3
- package/{assets → dist/pstack}/skills/principle-never-block-on-the-human/SKILL.md +1 -3
- package/dist/{assets → pstack}/skills/principle-outcome-oriented-execution/SKILL.md +1 -3
- package/{assets → dist/pstack}/skills/principle-prove-it-works/SKILL.md +3 -3
- package/dist/{assets → pstack}/skills/principle-redesign-from-first-principles/SKILL.md +1 -3
- package/{assets → dist/pstack}/skills/principle-separate-before-serializing-shared-state/SKILL.md +1 -3
- package/dist/{assets → pstack}/skills/principle-sequence-verifiable-units/SKILL.md +1 -3
- package/dist/{assets → pstack}/skills/principle-subtract-before-you-add/SKILL.md +1 -3
- package/{assets → dist/pstack}/skills/principle-test-behavior-not-implementation/SKILL.md +1 -3
- package/{assets → dist/pstack}/skills/principle-type-system-discipline/SKILL.md +1 -3
- package/dist/{assets → pstack}/skills/recall/SKILL.md +4 -4
- package/dist/pstack/skills/reflect/SKILL.md +71 -0
- package/{assets → dist/pstack}/skills/reflect/references/divergent-reviewer.md +1 -1
- package/{assets → dist/pstack}/skills/reflect/references/judgment-reviewer.md +1 -1
- package/{assets → dist/pstack}/skills/reflect/references/synthesizer.md +3 -3
- package/dist/{assets → pstack}/skills/reflect/references/tooling-reviewer.md +1 -1
- package/dist/pstack/skills/setup-pstack/SKILL.md +80 -0
- package/{assets → dist/pstack}/skills/sharpen/SKILL.md +1 -3
- package/{assets → dist/pstack}/skills/show-me-your-work/SKILL.md +3 -3
- package/dist/pstack/skills/show-me-your-work/scripts/log.mjs +106 -0
- package/dist/pstack/skills/show-me-your-work/scripts/log.test.mjs +56 -0
- package/dist/pstack/skills/statechart/SKILL.md +82 -0
- package/dist/pstack/skills/statechart/references/render.md +93 -0
- package/dist/pstack/skills/statechart/scripts/backends/cfg.mjs +31 -0
- package/dist/pstack/skills/statechart/scripts/backends/mermaid.mjs +186 -0
- package/dist/pstack/skills/statechart/scripts/backends/plain-text.mjs +62 -0
- package/dist/pstack/skills/statechart/scripts/backends/report.mjs +84 -0
- package/dist/pstack/skills/statechart/scripts/frontends/config.mjs +268 -0
- package/dist/pstack/skills/statechart/scripts/frontends/dot.mjs +67 -0
- package/dist/pstack/skills/statechart/scripts/frontends/marks.mjs +94 -0
- package/dist/pstack/skills/statechart/scripts/frontends/messages.mjs +48 -0
- package/dist/pstack/skills/statechart/scripts/frontends/spec.mjs +101 -0
- package/dist/pstack/skills/statechart/scripts/frontends/trace.mjs +39 -0
- package/dist/pstack/skills/statechart/scripts/frontends/value.mjs +180 -0
- package/dist/pstack/skills/statechart/scripts/frontends/verdict.mjs +40 -0
- package/dist/pstack/skills/statechart/scripts/frontends/view.mjs +99 -0
- package/dist/pstack/skills/statechart/scripts/ir.mjs +277 -0
- package/dist/pstack/skills/statechart/scripts/passes/annotate.mjs +92 -0
- package/dist/pstack/skills/statechart/scripts/passes/label.mjs +210 -0
- package/dist/pstack/skills/statechart/scripts/passes/lift.mjs +84 -0
- package/dist/pstack/skills/statechart/scripts/passes/loop-check.mjs +47 -0
- package/dist/pstack/skills/statechart/scripts/passes/paths.mjs +72 -0
- package/dist/pstack/skills/statechart/scripts/passes/reach.mjs +135 -0
- package/dist/pstack/skills/statechart/scripts/passes/region-check.mjs +82 -0
- package/dist/pstack/skills/statechart/scripts/passes/regions.mjs +268 -0
- package/dist/pstack/skills/statechart/scripts/pipeline.mjs +72 -0
- package/dist/pstack/skills/statechart/scripts/run.mjs +440 -0
- package/dist/pstack/skills/statechart/scripts/statechart.mjs +155 -0
- package/dist/pstack/skills/statechart/scripts/statechart.test.mjs +198 -0
- package/dist/pstack/skills/statechart/scripts/worker.mjs +31 -0
- package/dist/pstack/skills/swarm/SKILL.md +43 -0
- package/{assets → dist/pstack}/skills/tdd/SKILL.md +1 -3
- package/{assets → dist/pstack}/skills/teach/SKILL.md +3 -3
- package/{assets → dist/pstack}/skills/technical-writing/SKILL.md +2 -2
- package/{assets → dist/pstack}/skills/typescript-best-practices/SKILL.md +1 -2
- package/{assets → dist/pstack}/skills/unslop/SKILL.md +0 -2
- package/dist/{assets → pstack}/skills/why/SKILL.md +9 -9
- package/dist/script.d.mts +91 -0
- package/dist/script.mjs +485 -0
- package/dist/skill.d.mts +38 -0
- package/dist/skill.mjs +183 -0
- package/dist/skills/authored/decision-audit/SKILL.md +99 -0
- package/dist/skills/authored/decision-audit/SKILL.zh.md +99 -0
- package/dist/skills/authored/decision-audit/references/recover-commit.md +17 -0
- package/dist/skills/authored/decision-audit/references/recover-commit.zh.md +17 -0
- package/dist/skills/authored/decision-write/SKILL.md +131 -0
- package/dist/skills/authored/decision-write/SKILL.zh.md +131 -0
- package/dist/skills/authored/decision-write/references/land.md +48 -0
- package/dist/skills/authored/decision-write/references/land.zh.md +48 -0
- package/dist/skills/authored/setup-project-docs/SKILL.md +58 -0
- package/dist/skills/authored/setup-project-docs/SKILL.zh.md +58 -0
- package/dist/skills/authored/setup-project-docs/references/decision-conventions.md +11 -0
- package/dist/skills/authored/setup-project-docs/references/decision-conventions.zh.md +11 -0
- package/dist/skills/vendored/retro/SKILL.md +44 -0
- package/dist/skills/vendored/retro/agents/openai.yaml +5 -0
- package/dist/skills/vendored/writing-for-agents/SKILL-MECHANICS.md +22 -0
- package/dist/skills/vendored/writing-for-agents/SKILL.md +81 -0
- package/dist/skills/vendored/writing-for-agents/agents/openai.yaml +3 -0
- package/dist/subagent.d.mts +175 -106
- package/dist/subagent.mjs +1012 -344
- package/locale/en.json +7 -0
- package/locale/zh.json +7 -0
- package/package.json +61 -50
- package/assets/agents/poteto-agent.md +0 -8
- package/assets/docs/guide/02-poteto-mode.md +0 -139
- package/assets/docs/guide/05-build-and-clean.md +0 -83
- package/assets/docs/guide/06-verify-and-ship.md +0 -152
- package/assets/docs/guide/09-make-it-yours.md +0 -100
- package/assets/docs/harness/dsh.md +0 -65
- package/assets/docs/pstack-models.example.md +0 -23
- package/assets/skills/arena/SKILL.md +0 -50
- package/assets/skills/benchmark-checklist/SKILL.md +0 -41
- package/assets/skills/blast-radius/SKILL.md +0 -52
- package/assets/skills/correct/SKILL.md +0 -34
- package/assets/skills/how/SKILL.md +0 -38
- package/assets/skills/in-your-own-words/SKILL.md +0 -9
- package/assets/skills/interrogate/SKILL.md +0 -69
- package/assets/skills/interrogate/references/code-quality-review.md +0 -47
- package/assets/skills/interrogate/references/lead-judgment.md +0 -39
- package/assets/skills/interrogate/references/reviewer-prompt.md +0 -62
- package/assets/skills/interrogate/references/rubric.md +0 -77
- package/assets/skills/maintain-verification-skill/SKILL.md +0 -41
- package/assets/skills/poteto-help/references/prompting.md +0 -51
- package/assets/skills/poteto-help/references/recipes.md +0 -51
- package/assets/skills/poteto-mode/playbooks/authoring-a-skill.md +0 -12
- package/assets/skills/poteto-mode/playbooks/autonomous-run.md +0 -13
- package/assets/skills/poteto-mode/playbooks/autopilot-stack.md +0 -12
- package/assets/skills/poteto-mode/playbooks/eval.md +0 -25
- package/assets/skills/poteto-mode/playbooks/opening-a-pr.md +0 -34
- package/assets/skills/poteto-mode/playbooks/orchestrate.md +0 -112
- package/assets/skills/poteto-mode/playbooks/perf-issue.md +0 -25
- package/assets/skills/poteto-mode/playbooks/refactoring.md +0 -16
- package/assets/skills/poteto-mode/playbooks/shipping.md +0 -12
- package/assets/skills/poteto-mode/playbooks/worktree-cleanup.md +0 -12
- package/assets/skills/poteto-mode/scripts/bootstrap.ts +0 -62
- package/assets/skills/poteto-mode/scripts/bun.lock +0 -67
- package/assets/skills/poteto-mode/scripts/check-plan.test.ts +0 -96
- package/assets/skills/poteto-mode/scripts/orch/orch.test.ts +0 -761
- package/assets/skills/poteto-mode/scripts/orch/orch.ts +0 -590
- package/assets/skills/poteto-mode/scripts/orch/store.ts +0 -1677
- package/assets/skills/poteto-mode/scripts/package.json +0 -16
- package/assets/skills/poteto-mode/scripts/watch-pr/cli.test.ts +0 -224
- package/assets/skills/poteto-mode/scripts/watch-pr/cli.ts +0 -223
- package/assets/skills/poteto-mode/scripts/watch-pr/fakes.test-helper.ts +0 -129
- package/assets/skills/poteto-mode/scripts/watch-pr/github.test.ts +0 -436
- package/assets/skills/poteto-mode/scripts/watch-pr/github.ts +0 -718
- package/assets/skills/poteto-mode/scripts/watch-pr/policy.test.ts +0 -420
- package/assets/skills/poteto-mode/scripts/watch-pr/policy.ts +0 -836
- package/assets/skills/poteto-mode/scripts/watch-pr/render.ts +0 -169
- package/assets/skills/poteto-mode/scripts/watch-pr/tsconfig.json +0 -13
- package/assets/skills/poteto-mode/scripts/watch-pr/types.compile.ts +0 -93
- package/assets/skills/poteto-mode/scripts/watch-pr/types.ts +0 -413
- package/assets/skills/poteto-mode/scripts/watch-pr/watch-pr +0 -6
- package/assets/skills/poteto-mode/scripts/worktree-audit.sh +0 -127
- package/assets/skills/principle-encode-lessons-in-structure/SKILL.md +0 -13
- package/assets/skills/principle-exhaust-the-design-space/SKILL.md +0 -11
- package/assets/skills/principle-explain-the-number/SKILL.md +0 -19
- package/assets/skills/principle-fix-root-causes/SKILL.md +0 -23
- package/assets/skills/principle-guard-the-context-window/SKILL.md +0 -14
- package/assets/skills/principle-laziness-protocol/SKILL.md +0 -12
- package/assets/skills/principle-make-operations-idempotent/SKILL.md +0 -24
- package/assets/skills/principle-migrate-callers-then-delete-legacy-apis/SKILL.md +0 -16
- package/assets/skills/principle-outcome-oriented-execution/SKILL.md +0 -23
- package/assets/skills/principle-redesign-from-first-principles/SKILL.md +0 -18
- package/assets/skills/principle-sequence-verifiable-units/SKILL.md +0 -19
- package/assets/skills/principle-subtract-before-you-add/SKILL.md +0 -20
- package/assets/skills/recall/SKILL.md +0 -37
- package/assets/skills/reflect/SKILL.md +0 -70
- package/assets/skills/reflect/references/tooling-reviewer.md +0 -48
- package/assets/skills/setup-pstack/SKILL.md +0 -76
- package/assets/skills/show-me-your-work/scripts/log.sh +0 -42
- package/assets/skills/swarm/SKILL.md +0 -41
- package/assets/skills/why/SKILL.md +0 -100
- package/dist/README.md +0 -159
- package/dist/assets/agents/comment-sicko.md +0 -32
- package/dist/assets/agents/poteto-agent.md +0 -8
- package/dist/assets/docs/guide/01-setup.md +0 -64
- package/dist/assets/docs/guide/03-understand.md +0 -79
- package/dist/assets/docs/guide/04-design.md +0 -133
- package/dist/assets/docs/guide/07-overnight.md +0 -122
- package/dist/assets/docs/guide/08-principles.md +0 -72
- package/dist/assets/docs/guide/10-recipes-and-pitfalls.md +0 -180
- package/dist/assets/docs/guide/README.md +0 -38
- package/dist/assets/docs/harness/dsh.md +0 -65
- package/dist/assets/docs/pstack-models.example.md +0 -23
- package/dist/assets/skills/architect/SKILL.md +0 -81
- package/dist/assets/skills/architect/references/design-red-flags.md +0 -57
- package/dist/assets/skills/architect/references/rationale-template.md +0 -35
- package/dist/assets/skills/architect/references/runner-prompt.md +0 -20
- package/dist/assets/skills/arena/SKILL.md +0 -50
- package/dist/assets/skills/automate-me/SKILL.md +0 -105
- package/dist/assets/skills/bro/SKILL.md +0 -9
- package/dist/assets/skills/create-formal-verification-skill/SKILL.md +0 -43
- package/dist/assets/skills/create-verification-skill/SKILL.md +0 -46
- package/dist/assets/skills/create-verification-skill/references/feature-map-example/README.md +0 -47
- package/dist/assets/skills/create-verification-skill/references/feature-map-example/create-note.md +0 -39
- package/dist/assets/skills/create-verification-skill/references/feature-map-example/search.md +0 -45
- package/dist/assets/skills/figure-it-out/SKILL.md +0 -54
- package/dist/assets/skills/how/references/explainer-prompt.md +0 -55
- package/dist/assets/skills/how/references/explorer-prompt.md +0 -35
- package/dist/assets/skills/in-your-own-words/SKILL.md +0 -9
- package/dist/assets/skills/interrogate/SKILL.md +0 -69
- package/dist/assets/skills/interrogate/references/code-quality-review.md +0 -47
- package/dist/assets/skills/interrogate/references/lead-judgment.md +0 -39
- package/dist/assets/skills/interrogate/references/reviewer-prompt.md +0 -62
- package/dist/assets/skills/interrogate/references/rubric.md +0 -77
- package/dist/assets/skills/ketchup/SKILL.md +0 -45
- package/dist/assets/skills/maintain-formal-verification-skill/SKILL.md +0 -60
- package/dist/assets/skills/no-comments/SKILL.md +0 -26
- package/dist/assets/skills/poteto-help/SKILL.md +0 -161
- package/dist/assets/skills/poteto-mode/SKILL.md +0 -153
- package/dist/assets/skills/poteto-mode/playbooks/autopilot-full.md +0 -25
- package/dist/assets/skills/poteto-mode/playbooks/autopilot-stack.md +0 -12
- package/dist/assets/skills/poteto-mode/playbooks/babysit.md +0 -23
- package/dist/assets/skills/poteto-mode/playbooks/bug-fix.md +0 -15
- package/dist/assets/skills/poteto-mode/playbooks/feature.md +0 -21
- package/dist/assets/skills/poteto-mode/playbooks/hillclimb.md +0 -21
- package/dist/assets/skills/poteto-mode/playbooks/investigation.md +0 -14
- package/dist/assets/skills/poteto-mode/playbooks/multi-phase-plan.md +0 -155
- package/dist/assets/skills/poteto-mode/playbooks/orchestrate.md +0 -112
- package/dist/assets/skills/poteto-mode/playbooks/pause-safely.md +0 -10
- package/dist/assets/skills/poteto-mode/playbooks/prototype.md +0 -14
- package/dist/assets/skills/poteto-mode/playbooks/runtime-forensics.md +0 -11
- package/dist/assets/skills/poteto-mode/playbooks/session-pickup.md +0 -11
- package/dist/assets/skills/poteto-mode/playbooks/trace-forensics.md +0 -14
- package/dist/assets/skills/poteto-mode/playbooks/visual-parity.md +0 -11
- package/dist/assets/skills/poteto-mode/references/bugbot-triage.md +0 -142
- package/dist/assets/skills/poteto-mode/scripts/bootstrap.ts +0 -62
- package/dist/assets/skills/poteto-mode/scripts/bun.lock +0 -67
- package/dist/assets/skills/poteto-mode/scripts/check-plan.mjs +0 -205
- package/dist/assets/skills/poteto-mode/scripts/orch/orch.test.ts +0 -761
- package/dist/assets/skills/poteto-mode/scripts/orch/orch.ts +0 -590
- package/dist/assets/skills/poteto-mode/scripts/orch/store.ts +0 -1677
- package/dist/assets/skills/poteto-mode/scripts/package.json +0 -16
- package/dist/assets/skills/poteto-mode/scripts/watch-pr/cli.test.ts +0 -224
- package/dist/assets/skills/poteto-mode/scripts/watch-pr/cli.ts +0 -223
- package/dist/assets/skills/poteto-mode/scripts/watch-pr/fakes.test-helper.ts +0 -129
- package/dist/assets/skills/poteto-mode/scripts/watch-pr/github.test.ts +0 -436
- package/dist/assets/skills/poteto-mode/scripts/watch-pr/github.ts +0 -718
- package/dist/assets/skills/poteto-mode/scripts/watch-pr/policy.test.ts +0 -420
- package/dist/assets/skills/poteto-mode/scripts/watch-pr/policy.ts +0 -836
- package/dist/assets/skills/poteto-mode/scripts/watch-pr/render.ts +0 -169
- package/dist/assets/skills/poteto-mode/scripts/watch-pr/tsconfig.json +0 -13
- package/dist/assets/skills/poteto-mode/scripts/watch-pr/types.compile.ts +0 -93
- package/dist/assets/skills/poteto-mode/scripts/watch-pr/types.ts +0 -413
- package/dist/assets/skills/poteto-mode/scripts/watch-pr/watch-pr +0 -6
- package/dist/assets/skills/poteto-mode/scripts/worktree-audit.sh +0 -127
- package/dist/assets/skills/principle-attack-the-premise/SKILL.md +0 -23
- package/dist/assets/skills/principle-boundary-discipline/SKILL.md +0 -36
- package/dist/assets/skills/principle-build-the-lever/SKILL.md +0 -26
- package/dist/assets/skills/principle-encode-lessons-in-structure/SKILL.md +0 -13
- package/dist/assets/skills/principle-exhaust-the-design-space/SKILL.md +0 -11
- package/dist/assets/skills/principle-experience-first/SKILL.md +0 -21
- package/dist/assets/skills/principle-foundational-thinking/SKILL.md +0 -23
- package/dist/assets/skills/principle-minimize-reader-load/SKILL.md +0 -20
- package/dist/assets/skills/principle-model-the-domain/SKILL.md +0 -26
- package/dist/assets/skills/principle-never-block-on-the-human/SKILL.md +0 -17
- package/dist/assets/skills/principle-prove-it-works/SKILL.md +0 -24
- package/dist/assets/skills/principle-separate-before-serializing-shared-state/SKILL.md +0 -18
- package/dist/assets/skills/principle-test-behavior-not-implementation/SKILL.md +0 -22
- package/dist/assets/skills/principle-type-system-discipline/SKILL.md +0 -15
- package/dist/assets/skills/reflect/SKILL.md +0 -70
- package/dist/assets/skills/reflect/references/divergent-reviewer.md +0 -38
- package/dist/assets/skills/reflect/references/judgment-reviewer.md +0 -37
- package/dist/assets/skills/reflect/references/synthesizer.md +0 -56
- package/dist/assets/skills/setup-pstack/SKILL.md +0 -76
- package/dist/assets/skills/sharpen/SKILL.md +0 -18
- package/dist/assets/skills/show-me-your-work/SKILL.md +0 -84
- package/dist/assets/skills/show-me-your-work/references/decision-log-template.tsv +0 -1
- package/dist/assets/skills/show-me-your-work/scripts/log.sh +0 -42
- package/dist/assets/skills/swarm/SKILL.md +0 -41
- package/dist/assets/skills/tdd/SKILL.md +0 -44
- package/dist/assets/skills/teach/SKILL.md +0 -23
- package/dist/assets/skills/technical-writing/SKILL.md +0 -108
- package/dist/assets/skills/typescript-best-practices/SKILL.md +0 -32
- package/dist/assets/skills/typescript-best-practices/references/patterns.md +0 -328
- package/dist/assets/skills/unslop/SKILL.md +0 -64
- package/dist/assets/skills/why/references/epistemics.md +0 -71
- package/dist/assets/skills/why/references/investigator-prompt.md +0 -84
- package/dist/assets/skills/why/references/source-playbook.md +0 -17
- package/dist/assets/skills/why/references/sources/code-archaeology.md +0 -51
- package/dist/assets/skills/why/references/sources/databricks.md +0 -70
- package/dist/assets/skills/why/references/sources/datadog.md +0 -97
- package/dist/assets/skills/why/references/sources/incident-postmortem.md +0 -5
- package/dist/assets/skills/why/references/sources/linear.md +0 -48
- package/dist/assets/skills/why/references/sources/notion.md +0 -55
- package/dist/assets/skills/why/references/sources/sentry.md +0 -66
- package/dist/assets/skills/why/references/sources/slack.md +0 -17
- package/dist/assets/skills/why/references/synthesizer-prompt.md +0 -129
- package/dist/cordis.patch.yml +0 -20
- package/dist/index.mjs.map +0 -1
- package/dist/paths-Bbai4CaT.mjs +0 -16
- package/dist/paths-Bbai4CaT.mjs.map +0 -1
- package/dist/subagent.mjs.map +0 -1
- /package/{assets → dist/pstack}/docs/guide/03-understand.md +0 -0
- /package/{assets → dist/pstack}/docs/guide/08-principles.md +0 -0
- /package/{assets → dist/pstack}/docs/guide/README.md +0 -0
- /package/{assets → dist/pstack}/skills/architect/references/design-red-flags.md +0 -0
- /package/{assets → dist/pstack}/skills/architect/references/rationale-template.md +0 -0
- /package/{assets → dist/pstack}/skills/architect/references/runner-prompt.md +0 -0
- /package/{assets → dist/pstack}/skills/create-verification-skill/references/feature-map-example/README.md +0 -0
- /package/{assets → dist/pstack}/skills/create-verification-skill/references/feature-map-example/create-note.md +0 -0
- /package/{assets → dist/pstack}/skills/create-verification-skill/references/feature-map-example/search.md +0 -0
- /package/{assets → dist/pstack}/skills/how/references/explorer-prompt.md +0 -0
- /package/{assets → dist/pstack}/skills/poteto-mode/playbooks/investigation.md +0 -0
- /package/{assets → dist/pstack}/skills/poteto-mode/playbooks/pause-safely.md +0 -0
- /package/{assets → dist/pstack}/skills/poteto-mode/playbooks/trace-forensics.md +0 -0
- /package/{assets → dist/pstack}/skills/poteto-mode/references/bugbot-triage.md +0 -0
- /package/{assets → dist/pstack}/skills/show-me-your-work/references/decision-log-template.tsv +0 -0
- /package/{assets → dist/pstack}/skills/typescript-best-practices/references/patterns.md +0 -0
- /package/{assets → dist/pstack}/skills/why/references/epistemics.md +0 -0
- /package/{assets → dist/pstack}/skills/why/references/investigator-prompt.md +0 -0
- /package/{assets → dist/pstack}/skills/why/references/source-playbook.md +0 -0
- /package/{assets → dist/pstack}/skills/why/references/sources/code-archaeology.md +0 -0
- /package/{assets → dist/pstack}/skills/why/references/sources/databricks.md +0 -0
- /package/{assets → dist/pstack}/skills/why/references/sources/datadog.md +0 -0
- /package/{assets → dist/pstack}/skills/why/references/sources/incident-postmortem.md +0 -0
- /package/{assets → dist/pstack}/skills/why/references/sources/linear.md +0 -0
- /package/{assets → dist/pstack}/skills/why/references/sources/notion.md +0 -0
- /package/{assets → dist/pstack}/skills/why/references/sources/sentry.md +0 -0
- /package/{assets → dist/pstack}/skills/why/references/sources/slack.md +0 -0
- /package/{assets → dist/pstack}/skills/why/references/synthesizer-prompt.md +0 -0
|
@@ -1,62 +0,0 @@
|
|
|
1
|
-
# Reviewer Prompt Template
|
|
2
|
-
|
|
3
|
-
Build each reviewer subagent's prompt from this template, filling in the placeholders.
|
|
4
|
-
|
|
5
|
-
---
|
|
6
|
-
|
|
7
|
-
You are an adversarial code reviewer. Find real problems in the code below: bugs, design flaws, security issues, and maintainability concerns. You are not here to be helpful or encouraging. You are here to stress-test.
|
|
8
|
-
|
|
9
|
-
## Intent
|
|
10
|
-
|
|
11
|
-
The author's stated intent for this change:
|
|
12
|
-
|
|
13
|
-
> {INTENT}
|
|
14
|
-
|
|
15
|
-
Review whether the code achieves this intent well. Do NOT question the intent itself. Assume the goal is correct and challenge the execution.
|
|
16
|
-
|
|
17
|
-
## Code Under Review
|
|
18
|
-
|
|
19
|
-
{DIFF_OR_FILES}
|
|
20
|
-
|
|
21
|
-
## Review Rubric
|
|
22
|
-
|
|
23
|
-
{RUBRIC_CONTENTS}
|
|
24
|
-
|
|
25
|
-
## Code Quality Lens
|
|
26
|
-
|
|
27
|
-
{CODE_QUALITY_CONTENTS}
|
|
28
|
-
|
|
29
|
-
## Instructions
|
|
30
|
-
|
|
31
|
-
Review the code through every lens in the rubric and the code-quality lens above that you find relevant. Do not force lenses that don't apply. A simple bug fix does not need paragraphs about architectural integrity.
|
|
32
|
-
|
|
33
|
-
For each finding, provide:
|
|
34
|
-
|
|
35
|
-
1. **Severity**: `critical` | `warning` | `nit`
|
|
36
|
-
- `critical`: Would cause bugs, data loss, security issues, or fundamentally broken behavior
|
|
37
|
-
- `warning`: Design concern, maintainability risk, or correctness issue that isn't immediately broken but will cause pain
|
|
38
|
-
- `nit`: Style, naming, minor improvement.
|
|
39
|
-
2. **Finding**: What the problem is, in concrete terms. Reference specific lines/functions.
|
|
40
|
-
3. **Evidence**: Why you believe this is a problem. Show your reasoning. Don't just assert.
|
|
41
|
-
4. **Suggestion** (optional): What you'd do instead, only if you have a concrete alternative.
|
|
42
|
-
|
|
43
|
-
A good finding references specific code, not vague concerns ("this could be better"). It distinguishes between "this is broken" and "I would have done this differently". It considers the stated intent. A finding that ignores the context of what's being built is a bad finding.
|
|
44
|
-
|
|
45
|
-
Do not restate what the code does without identifying a problem. Do not praise the code. If you find nothing wrong, say "no findings" and stop. An empty review is a valid outcome.
|
|
46
|
-
|
|
47
|
-
## Output
|
|
48
|
-
|
|
49
|
-
Return your findings as a structured list:
|
|
50
|
-
|
|
51
|
-
```
|
|
52
|
-
## Findings
|
|
53
|
-
|
|
54
|
-
### 1. [Severity] Short title
|
|
55
|
-
**Location**: file:line or function name
|
|
56
|
-
**Finding**: What's wrong
|
|
57
|
-
**Evidence**: Why this matters
|
|
58
|
-
**Suggestion**: (optional) What to do instead
|
|
59
|
-
|
|
60
|
-
### 2. [Severity] Short title
|
|
61
|
-
...
|
|
62
|
-
```
|
|
@@ -1,77 +0,0 @@
|
|
|
1
|
-
# Review Rubric
|
|
2
|
-
|
|
3
|
-
Review through whichever lenses are relevant. Not every lens applies to every change.
|
|
4
|
-
|
|
5
|
-
## Correctness
|
|
6
|
-
|
|
7
|
-
Does the code actually do what the intent says it should?
|
|
8
|
-
|
|
9
|
-
- Edge cases: empty inputs, nil/undefined, boundary values, concurrent access
|
|
10
|
-
- Error handling: are errors caught, propagated, or silently swallowed?
|
|
11
|
-
- Off-by-one, type coercion, integer overflow, string encoding
|
|
12
|
-
- State management: race conditions, stale closures, dangling references
|
|
13
|
-
- Do both the happy path and the sad path work?
|
|
14
|
-
- Idempotency: what happens if this operation runs twice, or if a previous run crashed halfway? If the answer is "it depends on what state was left behind," a reconciliation step is missing.
|
|
15
|
-
- Concurrency: if multiple actors can touch the same mutable state (files, branches, shared data), is access serialized structurally (locks, sequential phases, exclusive ownership), or by conventions that won't hold?
|
|
16
|
-
|
|
17
|
-
When you find a potential bug, trace the execution path. Don't just flag "this could be nil". Show the call chain that makes it nil.
|
|
18
|
-
|
|
19
|
-
## Root Causes vs. Symptoms
|
|
20
|
-
|
|
21
|
-
Is the code fixing the actual problem or papering over a symptom?
|
|
22
|
-
|
|
23
|
-
Answering this often requires looking beyond the changed files. Read the surrounding code (callers, callees, type definitions, sibling modules) and understand the architecture the change lives in. Use the tools available to you (Read, `grep`, `glob`) to follow the call chain, read the types, and understand why the code exists before judging whether the change addresses the right layer.
|
|
24
|
-
|
|
25
|
-
- Guard clauses that mask a deeper invariant violation
|
|
26
|
-
- Retry logic that hides a broken contract
|
|
27
|
-
- Type casts that silence a modeling error
|
|
28
|
-
- A workaround: why is it needed? What would a proper fix look like?
|
|
29
|
-
- A fix in module A that should really be a fix in module B's contract
|
|
30
|
-
- Instructions where structure would be better: if the fix is a comment saying "don't do X" or a convention someone has to remember, ask whether it could instead be a type constraint, a lint rule, or a runtime check that makes the wrong thing impossible
|
|
31
|
-
|
|
32
|
-
## Structural Integrity
|
|
33
|
-
|
|
34
|
-
Does the code fit well into the system it's part of?
|
|
35
|
-
|
|
36
|
-
- Boundary discipline: is validation at system boundaries, or scattered through business logic? Validate data once where it enters the system, then trust it internally.
|
|
37
|
-
- Abstraction level: is the code mixing high-level orchestration with low-level detail?
|
|
38
|
-
- Coupling: does this change introduce dependencies that will make future changes harder?
|
|
39
|
-
- Data model fit: do the data structures match the actual access patterns?
|
|
40
|
-
- Bolted-on vs. integrated: if the new requirement had been known from the start, would the code look like this, or does the change feel patched onto the existing design?
|
|
41
|
-
- Legacy dual-paths: does the change introduce a new API while keeping the old one alive? If there are no external consumers, migrate callers and delete the old path in the same wave. Don't leave compatibility layers that will become permanent.
|
|
42
|
-
|
|
43
|
-
Don't penalize simple code for lacking abstraction. Premature abstraction is worse than duplication.
|
|
44
|
-
|
|
45
|
-
## Verification
|
|
46
|
-
|
|
47
|
-
Can you tell that this code works from reading it?
|
|
48
|
-
|
|
49
|
-
- Are there tests? Do they test behavior or implementation details?
|
|
50
|
-
- Are there assertions/invariants that would catch regressions?
|
|
51
|
-
- If this is a bug fix: is there a test for the bug?
|
|
52
|
-
- If this touches an integration boundary: is the full path tested?
|
|
53
|
-
- Check the real thing, not a proxy. If the code checks liveness via file mtime or cached state instead of reading the actual value, that's a verification gap.
|
|
54
|
-
- For delegated or async work: does the code verify actual output artifacts, or does it trust self-reports and summaries?
|
|
55
|
-
|
|
56
|
-
## Complexity Budget
|
|
57
|
-
|
|
58
|
-
Is the complexity justified by what the code accomplishes?
|
|
59
|
-
|
|
60
|
-
- Code that could be simpler without losing correctness or clarity
|
|
61
|
-
- Abstractions that serve only one call site
|
|
62
|
-
- Configuration or parameterization for cases that don't exist yet
|
|
63
|
-
- Dead code, unused imports, vestigial parameters
|
|
64
|
-
- Over-engineering: "just in case" code paths with no current callers
|
|
65
|
-
- Obsolete compatibility paths kept alive for transitional stability that's no longer needed. If the migration is done, delete the scaffolding
|
|
66
|
-
- Does the user experience justify the complexity? Every feature, control, and option should earn its place. Half-finished features are worse than missing ones.
|
|
67
|
-
|
|
68
|
-
Simpler is better unless simpler is wrong.
|
|
69
|
-
|
|
70
|
-
## Security
|
|
71
|
-
|
|
72
|
-
For each security finding, trace the input path through the code and show it.
|
|
73
|
-
|
|
74
|
-
- User input flowing to dangerous sinks (SQL, shell, eval, innerHTML) without sanitization
|
|
75
|
-
- Authentication/authorization gaps in new endpoints
|
|
76
|
-
- Secrets in code, logs, or error messages
|
|
77
|
-
- TOCTOU (time-of-check-time-of-use) in security-critical paths
|
|
@@ -1,41 +0,0 @@
|
|
|
1
|
-
---
|
|
2
|
-
name: maintain-verification-skill
|
|
3
|
-
description: "Periodic pass that keeps a project's verification skill and feature map honest: parallel source readers per feature, one live session driving every feature, at most one PR of proven corrections. Use for /maintain-verification-skill or \"audit the verify skill\"."
|
|
4
|
-
disable-model-invocation: true
|
|
5
|
-
---
|
|
6
|
-
|
|
7
|
-
> DSH port of pstack. `pstack_subagent` replaces Cursor's `Task` tool, and `role` replaces Cursor model slugs. Full mapping: `../../docs/harness/dsh.md`.
|
|
8
|
-
|
|
9
|
-
# Maintain a verification skill
|
|
10
|
-
|
|
11
|
-
A feature map rots the moment the app changes. This skill is the upkeep loop for a skill generated by `/create-verification-skill` (or any project-local verification skill with a feature map). The unit of rigor is the feature, not every sentence: cover every feature file from source and exercise every feature live, without terminalising every bullet.
|
|
12
|
-
|
|
13
|
-
## Outcomes
|
|
14
|
-
|
|
15
|
-
Pick one, and say which:
|
|
16
|
-
|
|
17
|
-
- **clean** — every feature got source and live coverage; nothing worth shipping. No branch, no PR.
|
|
18
|
-
- **changed** — one PR ships proven doc, harness, or map corrections.
|
|
19
|
-
- **blocked** — coverage could not finish or a proven fix could not ship safely. Say exactly what blocked it.
|
|
20
|
-
|
|
21
|
-
## Edit scope
|
|
22
|
-
|
|
23
|
-
Only edit the verification skill's own directory (its SKILL.md, features/, and any harness scripts it owns). Never edit product code during a run: a behavior the map describes that the app no longer does is either doc drift (fix the map) or a product regression (report it, don't paper over it in docs).
|
|
24
|
-
|
|
25
|
-
## Pass
|
|
26
|
-
|
|
27
|
-
0. **Locate the target.** Find the verification skill to maintain: the project-local skill whose body has launch/drive sections and a feature map (usually `.dsh/skills/verify-*/`). Several candidates → ask which one; none → stop and point at `/create-verification-skill` instead of inventing a target.
|
|
28
|
-
|
|
29
|
-
1. **Index hygiene.** Read the feature map README and glob its sibling files. Fix missing, extra, duplicate, or dead entries. Lightweight; no generated inventory.
|
|
30
|
-
|
|
31
|
-
2. **Source wave.** One read-only subagent per feature file, launched concurrently. Each explains "how does this user-facing feature work?" from source, flags likely doc drift with citations, and returns one concise live-verification recipe. Children never drive the app and never edit files. Return shape: feature summary / source entry points / likely drift or none / one recipe.
|
|
32
|
-
|
|
33
|
-
3. **Reconcile.** Every feature file has a returned summary. Merge overlapping recipes into as few app states as practical. Spot-check cited drift; don't re-prove clean claims. Sweep recent churn for user-facing surfaces missing from the map — require a concrete source path before calling one missing.
|
|
34
|
-
|
|
35
|
-
4. **Live pass.** Required even when source looks clean. The coordinator owns all driving; follow the verification skill's own launch model — one long-lived instance driven serially for servers and UIs, or a fresh isolated session per drive for short-lived CLIs (the skill's Launch section decides, not this one). Exercise every feature at least once, and hold three invariants the whole pass, whatever the failure: (1) never drive an instance you haven't health-checked since it last did something surprising — doctor before first drive, doctor on each fresh session where sessions are the unit, doctor again after any failed drive, and where doctor can't see the failure (a wedged UI state on a healthy process), reset to a known state or relaunch rather than hoping; (2) evidence captured so far survives every cleanup, checked at its named location, not assumed; (3) nothing a drive started outlives that drive's usefulness — failed-iteration residue is cleaned whether the session is stuck, exited, or shared (for a shared instance, clean the residue, not the instance). A doctor failure caused by skill drift is drift: fix it under edit scope and retry once — restart whatever the fix invalidated, nothing more — before calling the pass `blocked`. A feature that can't be reached is `verified-unreachable` only with the concrete prerequisite (auth, entitlement, OS, external state) and the route attempted; if the map omits that prerequisite, that's drift. Any harness fix from triage gets re-driven live before it ships. Final teardown happens after the last drive of the run — including those re-proofs — so nothing outlives the run (evidence stays, per the skill).
|
|
36
|
-
|
|
37
|
-
5. **Triage.** Wrong or missing user-POV description → doc drift, fix it. Working behavior the harness can't drive → harness gap, fix it; a harness fix follows the same helpers rule as generation (scripts executable, invocation documented in the skill body). App behavior that's actually broken → product gap; record it for the user, keep it out of this PR.
|
|
38
|
-
|
|
39
|
-
6. **Ship or stop.** For changed: one PR of proven corrections, re-read every changed file first. For clean or blocked: no PR, report the outcome and the coverage honestly.
|
|
40
|
-
|
|
41
|
-
Keep concise run notes (features covered, unreachable prerequisites, confirmed drift, outcome) in a scratch location; don't commit them.
|
|
@@ -1,51 +0,0 @@
|
|
|
1
|
-
# Word the prompt
|
|
2
|
-
|
|
3
|
-
A prompt states the intent and the check for done. The playbook supplies the steps, so a few plain sentences beat a spec.
|
|
4
|
-
|
|
5
|
-
## Put in
|
|
6
|
-
|
|
7
|
-
- The goal. Say what is wrong or what the user wants.
|
|
8
|
-
- The done check. It can pass or fail. "Make it better" and a duration are not checks.
|
|
9
|
-
- The proof to show. Ask for the real command output, a video of the flow, the stored value, or a before and after number.
|
|
10
|
-
- What the user already knows. A symptom, a repro step, a log, or a link saves the agent a search.
|
|
11
|
-
- 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.
|
|
12
|
-
|
|
13
|
-
## Leave out
|
|
14
|
-
|
|
15
|
-
- The how. Say what to achieve, and leave the agent room to find a better way.
|
|
16
|
-
- 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.
|
|
17
|
-
- The user's theory of the cause, until the agent restates the problem. A stated guess narrows the search.
|
|
18
|
-
|
|
19
|
-
## Load the context first
|
|
20
|
-
|
|
21
|
-
- 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.
|
|
22
|
-
- In a fresh chat, `/recall` earlier work on the topic. Old chats hold context that the new agent lacks.
|
|
23
|
-
- 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.
|
|
24
|
-
- 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.
|
|
25
|
-
|
|
26
|
-
## Design before the plan
|
|
27
|
-
|
|
28
|
-
- Never take the first design. Ask for prototypes of a few options, with screenshots or videos for UI, and pick from the evidence.
|
|
29
|
-
- Let prototypes answer the open questions. Don't review an abstract plan adversarially, because reviewers invent risks that never happen.
|
|
30
|
-
- 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.
|
|
31
|
-
- Ask for the plan only after the design is settled. Each step of the plan ends in a check.
|
|
32
|
-
|
|
33
|
-
## Follow up short
|
|
34
|
-
|
|
35
|
-
- "do it", "continue", and "keep going until done" are whole prompts once the chat holds the task.
|
|
36
|
-
- Start with "new task" when the subject changes. Otherwise the mode treats the message as the next step.
|
|
37
|
-
|
|
38
|
-
## Before stepping away
|
|
39
|
-
|
|
40
|
-
- Say "im going to bed" or "im stepping away" so the agent stops asking.
|
|
41
|
-
- Write done as checks every iteration can run, and give the wake prompt that predicate.
|
|
42
|
-
- Ask for a fresh worktree off a named base.
|
|
43
|
-
- Pre-answer what the agent would stop for, such as "don't ask me before committing".
|
|
44
|
-
- Ask for a decision log to audit later.
|
|
45
|
-
- Give an exit: "if you're truly stuck after a few hours, stop and write up why".
|
|
46
|
-
|
|
47
|
-
## Steer in one line
|
|
48
|
-
|
|
49
|
-
- Restate the goal: "i said the goal is to repro. i did not ask for a fix yet."
|
|
50
|
-
- Name the principle: "apply prove it works. show me the real output, not the build log."
|
|
51
|
-
- A principle name works because the agent already read the rule. Its reply names the decision the rule changed.
|
|
@@ -1,51 +0,0 @@
|
|
|
1
|
-
# Prompts worth copying
|
|
2
|
-
|
|
3
|
-
Swap in the real paths, skills, and done checks. Informal wording works.
|
|
4
|
-
|
|
5
|
-
## Understand
|
|
6
|
-
|
|
7
|
-
- `/poteto-mode read <thread>. restate the underlying issue in your own words, in plain english.`
|
|
8
|
-
- `/in-your-own-words <long or messy ask>`
|
|
9
|
-
- `/sharpen <the prompt you're about to send>`
|
|
10
|
-
- `/poteto-mode investigate why <symptom>. give me what we know, what data you used, and your best hypotheses. don't change any code yet.`
|
|
11
|
-
- `use /how to understand <subsystem>. then use /why to find out why it broke recently.`
|
|
12
|
-
- `/recall my work on <topic> from last week, then read <issue>.`
|
|
13
|
-
- `/teach me why you implemented it this way and not <other way>. what did you trade off?`
|
|
14
|
-
- `/poteto-mode take over this branch. read the decision log, find what's done, and continue. don't redo finished work.`
|
|
15
|
-
|
|
16
|
-
## Build
|
|
17
|
-
|
|
18
|
-
- Bug: `/poteto-mode <symptom>. repro first, then fix and verify.`
|
|
19
|
-
- Bug in an app: `/poteto-mode repro this with /verify-<app>. if it repros on main, fix it and show me a video as proof.`
|
|
20
|
-
- Bug with a cheap test: `/poteto-mode repro <bug> first. if there's a cheap test path, /tdd it. then fix and rerun.`
|
|
21
|
-
- Feature: `/poteto-mode add <behavior>. <current output> stays byte-identical. verify both.`
|
|
22
|
-
- Refactor: `/poteto-mode move <code> into one module, zero behavior change. record the current output first and prove it's unchanged after.`
|
|
23
|
-
- Perf: `/poteto-mode <operation> takes <time> on <fixture>. trace it, fix the measured cause, show me before and after.`
|
|
24
|
-
|
|
25
|
-
## Design and plan
|
|
26
|
-
|
|
27
|
-
- `/poteto-mode prototype a few options for <feature>. take screenshots or videos for me to compare.`
|
|
28
|
-
- `/poteto-mode we need <feature>. /architect it first, and answer open questions with prototypes. let me review before proceeding.`
|
|
29
|
-
- `/poteto-mode write a tutorial for how i would use <new package> first. then /teach me why it beats the current one.`
|
|
30
|
-
- `ask /arena for a second opinion on this thread and our approach.`
|
|
31
|
-
- `/poteto-mode turn this design into a plan. small verifiable PRs, each with its own verification steps.`
|
|
32
|
-
- `/poteto-mode plan the migration of <library> to <target>. small verifiable PRs. the result must match the original exactly, bugs included.`
|
|
33
|
-
|
|
34
|
-
## Review and ship
|
|
35
|
-
|
|
36
|
-
- `/interrogate the whole branch, but skeptically. don't change anything yet. no nitpicks unless it's a real bug or regression.` Read the dismissals too.
|
|
37
|
-
- `/create-formal-verification-skill prove <property> holds in <module>, even when <steps> interleave or retry.` After merges or refactors in that code: `/maintain-formal-verification-skill`.
|
|
38
|
-
- `/swarm check every package under <dir> against its check script. one worker per package. one report.`
|
|
39
|
-
- `/poteto-mode open the pr. small ordered commits, evidence in the description.`
|
|
40
|
-
- `/poteto-mode babysit this pr. get it green.` For status only: `/poteto-mode check on pr <number>. anything outstanding?`
|
|
41
|
-
- `/poteto-mode land the stack.`
|
|
42
|
-
|
|
43
|
-
## Away and back
|
|
44
|
-
|
|
45
|
-
- `/poteto-mode im going to bed. <goal> in a fresh worktree off <base>. done means <checks>. keep a decision log. don't ask me before committing. Arm a `schedule_create` heartbeat for the finish condition. if you're truly stuck after a few hours, stop and write up why.`
|
|
46
|
-
- `/show-me-your-work catch me up on what you did last night.` Read its Attention section first.
|
|
47
|
-
- `/ketchup` catches you up on this chat since your last message and lists every call that waits on you.
|
|
48
|
-
- `/poteto-mode full autopilot on this queue. each item is independent.`
|
|
49
|
-
- `/poteto-mode autopilot these changes but stack them, don't ship. i'll land the stack.`
|
|
50
|
-
- `/reflect capture what we learned so the next run doesn't repeat it.` Approve only edits that change a future decision.
|
|
51
|
-
- `/bro` restates the last reply in plain words.
|
|
@@ -1,12 +0,0 @@
|
|
|
1
|
-
### Authoring or modifying a skill
|
|
2
|
-
|
|
3
|
-
**You own the skill's voice.**
|
|
4
|
-
|
|
5
|
-
1. Use the **authoring-a-skill** playbook (the pstack authoring-a-skill playbook).
|
|
6
|
-
2. Validate the skill: frontmatter has `name` and `description`, referenced files exist, cross-skill links resolve.
|
|
7
|
-
3. Test cases if structural. Skip if subjective.
|
|
8
|
-
4. Run **Opening a PR**.
|
|
9
|
-
|
|
10
|
-
When in doubt, delete. Keep only prose that changes a decision. Tell it to do the thing and skip the reason. Explain only when the rule is confusing without one. Match tone to scope. Point at structural sources (types, READMEs, config) per the **encode-lessons-in-structure** principle skill. Delegate to other skills by path. Don't restate. A workflow you keep hitting but isn't captured → propose a new skill.
|
|
11
|
-
|
|
12
|
-
**Reply:** summary of the skill, key design decisions, validation notes.
|
|
@@ -1,13 +0,0 @@
|
|
|
1
|
-
### Autonomous run
|
|
2
|
-
|
|
3
|
-
**You own the exit condition. Define done, then drive to it without stopping.**
|
|
4
|
-
|
|
5
|
-
1. State the exit condition as a checkable predicate before the first iteration (tests green, repro fixed, all N PRs merged, pixel-diff zero).
|
|
6
|
-
2. Pick the wake mechanism using the `schedule_create` tool. An event to watch (CI, a merge, a ref advancing) gets a watcher subagent that wakes you on the event, with a long time-based heartbeat as fallback. No event gets a fixed-interval heartbeat sized to when the result is worth re-checking. Prefer one goal with a checkable finish predicate over a bare interval.
|
|
7
|
-
3. Each iteration makes the smallest change the evidence justifies, verifies it against the predicate, commits if it advanced, discards changes that didn't help. Belt-and-suspenders that "might help" gets reverted, not left to ride.
|
|
8
|
-
Sequence the work via the **sequence-verifiable-units** principle skill, verifying each unit before the next instead of batching checks at the end.
|
|
9
|
-
4. Mid-run discoveries are yours. Address broken skills, related bugs, flaky verifiers, review noise, tooling failures, orphaned follow-ups, and fixable drift yourself via poteto-mode. Put out-of-band fixes in their own PR. Do not park reversible work for the human or use `ask_user_question`. Surface only irreversible actions, genuine product or preference calls no experiment can settle, or a real dead end. Keep the predicate as the main drive, and return to it after each side fix.
|
|
10
|
-
5. Checkpoint every iteration via the **show-me-your-work** skill, a row for what changed and whether the predicate moved.
|
|
11
|
-
6. Stop when the predicate is met. A plateau is not a stop, so keep going and pivot your approach to push past it. Surface a genuine dead end rather than spinning, and never relax the predicate to declare victory.
|
|
12
|
-
|
|
13
|
-
**Reply:** the exit condition, iterations run, what landed, what was discarded, final predicate state.
|
|
@@ -1,12 +0,0 @@
|
|
|
1
|
-
### Autopilot-stack
|
|
2
|
-
|
|
3
|
-
**You own the stack, never the landing. Hand the operator one linear stack of base-chained PRs to review and land.** **Autopilot-full** holds except for how verified work leaves. Each tick re-reads both playbooks from trunk, and this one wins where they differ.
|
|
4
|
-
|
|
5
|
-
1. **Run Autopilot-full's owners, minus the landing.** Owners report STACK-READY in place of merge-ready. They never rebase onto another branch, trunk included, and never retarget, merge, close a PR, or arm auto-merge, because the root owns the chain's topology and the operator owns the landing. When an item depends on another, its owner branches from that item's branch, not from trunk.
|
|
6
|
-
2. **Give the topology one writer.** Owners push only their own branches and report each tip and its intended parent. Only you rebase or retarget a link, because two writers on one chain undo each other. Append each clean PR in dependency order, with its base set to its parent's branch (`origin pr edit <pr> --base <parent-branch>` or `gh pr edit <pr> --base <parent-branch>`). Never require `gt`. An owner takes your push as its new base and lease, and on a conflict resolves its own slice for you to push.
|
|
7
|
-
3. **Absorb drift at the root.** Until landing starts, apply Autopilot-full step 5's test to each link and rebase the chain bottom-up where it calls for one. Then apply the patch-id rule link by link, since a link's base is its parent.
|
|
8
|
-
4. **Deliver the chain, then keep your hands off it.** Each link carries its verdict in its PR. Once landing starts, nobody writes to the chain except the post-merge retarget that `playbooks/shipping.md` sanctions, because a second writer breaks a landing in flight. A mid-landing problem goes through you to the operator, and any fix waits for the operator's go.
|
|
9
|
-
|
|
10
|
-
**Choosing between the autopilots.** Autopilot-full when the PRs are independent and landing authority is granted. Autopilot-stack when the operator wants review before landing, the work is sequenced or coupled, or merge authority is withheld.
|
|
11
|
-
|
|
12
|
-
**Reply:** catch the operator up per the **ketchup** skill, with links to the stack root and tip, a one-line verdict per link, and anything parked or excluded with the reason.
|
|
@@ -1,25 +0,0 @@
|
|
|
1
|
-
### Eval
|
|
2
|
-
|
|
3
|
-
**You own the experiment design. Plan, blind, run, synthesize.**
|
|
4
|
-
|
|
5
|
-
**Non-negotiables for blinding:**
|
|
6
|
-
|
|
7
|
-
- No `eval`, `test`, `judge`, `experiment`, `rubric`, `score`, `compare`, `benchmark`, `candidate`, or `arena` in any directory, file, or prompt the candidate sees.
|
|
8
|
-
- The candidate prompt looks like an organic user request. State the goal, not the meta.
|
|
9
|
-
- No chain-eliciting cues. Don't ask the candidate to list which skills, principles, or files they applied. Ask for design notes generally and grade chain-following from code shape, not self-report.
|
|
10
|
-
- Sanitize directory and slug names. Use project-shaped names a user might pick.
|
|
11
|
-
- Don't tell the candidate other candidates exist.
|
|
12
|
-
- The judge can know it's judging but sees outputs by sanitized label only, never by model name.
|
|
13
|
-
- Comparing two variants: one judge scores both sets in a single pass on one scale, blind to which set each came from.
|
|
14
|
-
|
|
15
|
-
**Steps:**
|
|
16
|
-
|
|
17
|
-
1. **Frame.** State what variant is under test and what behavior counts as success. Write the rubric (3-6 concrete criteria) for the judge only. Hold it back from candidates.
|
|
18
|
-
2. **Set up sanitized environments.** Per-candidate working dir with the variant in place. Plant any context an organic task would have: a project skeleton, the skills the candidate would naturally read.
|
|
19
|
-
3. **Author one organic prompt.** What a user would type. No leakage of what's being measured.
|
|
20
|
-
4. **Spawn N parallel candidates** on different models per the **arena** skill's Phase B. Each works in its own sanitized dir. Same prompt to each. Pick each subagent's reasoning level and fast or standard speed for the job, per the Subagents section.
|
|
21
|
-
5. **Spawn one blinded judge** on a different model family per the **arena** skill's Phase C. Judge sees outputs by sanitized label and the rubric, never a model name.
|
|
22
|
-
6. **Verify the chain from transcripts, not self-report.** Read each candidate's local session log under `$DSH_HOME/sessions/<workspace-slug>/<session-id>/`. Do not scan other workspace directories. Look at which files each candidate actually opened. Grade chain-following from the files it really read plus the shape of the code, never from the candidate's own claims.
|
|
23
|
-
7. **Read every candidate output yourself** end to end. Compare to the judge's verdict. Disagreement means a model is biased or the rubric is ambiguous. Synthesize.
|
|
24
|
-
|
|
25
|
-
**Reply:** variant under test, rubric, per-candidate notes, judge's verdict, your synthesis, and a recommendation for whether to promote the variant.
|
|
@@ -1,34 +0,0 @@
|
|
|
1
|
-
### Opening a PR
|
|
2
|
-
|
|
3
|
-
Invoked at the end of every other playbook.
|
|
4
|
-
|
|
5
|
-
**Worktree.** Work from a git worktree off main. Subagents inherit it. Multiple `pstack_subagent` calls on the same branch each get their own worktree, or `git fetch && git reset --hard origin/<branch>` between them. Dirty branch with unrelated work: patch out, fresh worktree, apply. Snarled worktree: reset from main, redo minimally.
|
|
6
|
-
|
|
7
|
-
**Commits.** Commit liberally. Rebase into small, ordered commits before opening PRs. Each commit is a future PR: landable, ordered to tell the story. Amend when the fix belongs in a just-made commit. New commit when separable. Commit bodies don't restate the subject.
|
|
8
|
-
|
|
9
|
-
**PRs.** Run the pre-commit cleanup over the diff before commit: `/no-comments`, then a read for narration, dead compatibility paths, and unrelated edits. Run `/no-comments` again before review. Write every PR title, description, and commit body with `/technical-writing` (every layer except Diátaxis, and apply the STE vocabulary rules: one word per action, keep articles, a plain verb over `-ing` where one works), then apply `/unslop`.
|
|
10
|
-
|
|
11
|
-
**Titles.** Conventional Commits `type(scope): subject`, no trailing period. Type such as `feat`, `fix`, `docs`, `refactor`, `test`, `chore`, or `perf`. Scope is the area, such as `pstack` or `poteto-mode`. Subject is short, imperative, and names a real symbol when one carries the change, for example `fix(pstack): retarget opening-a-pr babysit trigger`.
|
|
12
|
-
|
|
13
|
-
**Descriptions.** The PR body is a one-minute briefing, not a lab notebook, for a reviewer who has the diff. It says why the change exists, what it leaves out, what it could break, and how you proved it works. Write short, simple sentences with few identifiers, no walls of text. The body becomes the squash commit body, so keep that commit under about 40 lines. Use `##` headings, not bold lead-ins, in this order, and drop a section with nothing to say:
|
|
14
|
-
|
|
15
|
-
- `## Why`: the problem and approach, 1–3 short sentences. No SHAs, rebase genealogy, or "based on main" preamble.
|
|
16
|
-
- `## What changed`: 1–3 short bullets. Name a real symbol or path only when it carries the change. Name both sides of a rename or retarget.
|
|
17
|
-
- `## Scope`: always. 1–3 short items on what it covers and what it deliberately leaves out (a follow-up, a known gap). No symbols, paths, or file-by-file essay.
|
|
18
|
-
- `## Tradeoffs`: only rejected alternatives a reviewer would otherwise ask about. Skip when there was no real choice.
|
|
19
|
-
- `## Blast Radius`: 1–2 sentences on who or what it touches and why that is safe or risky. If main is red, state the cost of leaving it red.
|
|
20
|
-
- `## Verification`: 1–3 bullets, each a real run path and its outcome. Perf: one primary number with its unit, `before → after`, and a link to the arena or swarm directory for the rest. No sample-size methodology, swarm recitals, or metric tables.
|
|
21
|
-
|
|
22
|
-
After the sections, attach videos or screenshots when they prove a claim. Full SHAs, swarm or arena lane recitals, lever-correction essays, file-by-file checklists, and "CLEAN" verdicts go in a linked artifact, not the body.
|
|
23
|
-
|
|
24
|
-
**Forge.** Resolve the forge before the first PR operation and keep that choice for create, edit, view, watch, and merge. GitHub CLI (`gh`) is the default. If `command -v origin` succeeds and Origin can resolve the repository, prefer `origin pr ...`. If Origin is absent or cannot resolve the repository, stay on `gh` and record the fallback. Do not require Graphite (`gt`).
|
|
25
|
-
|
|
26
|
-
**Built-in PR tool.** When the run provides a built-in PR tool, create, edit, retarget, and mark ready through it, never through a forge CLI. A CLI-made PR misses what the tool tracks. Use the resolved forge for everything the tool does not cover, and for every PR operation when the run has no such tool.
|
|
27
|
-
|
|
28
|
-
**Size and stacks.** Prefer five narrow PRs to one large PR. A stack is a base-branch chain. The root PR targets trunk. Each child branch rebases onto its parent's exact tip and its PR targets the parent branch. As a parent merges, move its child onto trunk per `playbooks/shipping.md` step 4. Without a built-in PR tool, per the resolved forge, create a child with `origin pr create --status open --base <parent-branch>` or `gh pr create --base <parent-branch>`, and retarget one with `origin pr edit <pr> --base <parent-branch>` or `gh pr edit <pr> --base <parent-branch>`. Branch from trunk only for independent work. Rebase on trunk before substantial stack work.
|
|
29
|
-
|
|
30
|
-
**Readiness.** Open every PR ready, never as a draft. A built-in PR tool can default to draft, so set `draft: false` on every creation call through it. With Origin, pass `--status open`. With `gh`, omit `--draft`. If a PR still opens as a draft, mark it ready through the PR tool, or run `origin pr ready <number>` or `gh pr ready <number>` according to the resolved forge. Run `origin pr view <number>` or `gh pr view <number>` before you refer to PR status.
|
|
31
|
-
|
|
32
|
-
**Babysit.** Opening a PR does not start a babysit. Post the URL and keep building. Finish the phase or stack first. Run a separate babysit pass only when the user asks for one after the whole stack exists. A babysit for each new PR stalls the build and spends checks on commits later waves restart. Push back when feedback drifts from intent.
|
|
33
|
-
|
|
34
|
-
A subagent that opens a PR runs `interrogate`, the pre-commit cleanup, and `/no-comments`, and posts the URL. It returns to the parent without babysitting, unless it is an Autopilot-full or Autopilot-stack owner. That owner's brief assigns the babysit loop and is the ask `playbooks/babysit.md` waits for. The owner starts the loop after its code-ready report, reports merge-ready or STACK-READY per its playbook, and is exempt from the rules here and in `playbooks/babysit.md` that hold babysitting until a whole stack is built.
|
|
@@ -1,112 +0,0 @@
|
|
|
1
|
-
### Orchestrate
|
|
2
|
-
|
|
3
|
-
**You own the program, never the code. Author briefs, drain the queue, keep the frontier green, decide.** For a whole project handed to one standing coordinator chat: multi-day, many stacked PRs, dozens to hundreds of subagents, the human checking in twice a day instead of every five minutes. One task driven to a predicate is Autonomous run. One ambitious run needing a bespoke workflow is figure-it-out. Route here when the work outlives any single agent. Work one agent could finish inside the session's budget is not a program.
|
|
4
|
-
|
|
5
|
-
Ceremony must scale with the program. On cheap near-identical units, collapse it as each section directs.
|
|
6
|
-
|
|
7
|
-
Three rules carry the rest.
|
|
8
|
-
|
|
9
|
-
- Completions are queue events, not interrupts.
|
|
10
|
-
- Every spawn and every resume carries the standing orders verbatim.
|
|
11
|
-
- The brief is the product. A vague brief fails quietly, because a worker cannot ask you a question.
|
|
12
|
-
|
|
13
|
-
#### Roles and placement
|
|
14
|
-
|
|
15
|
-
- **Coordinator (this chat).** Local. Frames, authors briefs, drains the inbox, owns the human report, makes judgment calls. It never authors or edits code. Conflicted merges, chain rebases, and code changes are always tasks. Mechanically landing a verified unit (fast-forward or clean cherry-pick of a worker's commit, then push) is bookkeeping the coordinator may do itself on repos where local git is cheap. Queueing finished work behind an idle stacker is how a deadline harvests nothing. The loop is agentic end to end. Agents are spawned, resumed, and drained only through the `pstack_subagent` tool. Pick each subagent's reasoning level and fast or standard speed for the job, per the Subagents section. State reads and writes go through `scripts/orch/orch.ts` at drain points, one command in and one line out. The CLI never spawns, waits, or wakes anything.
|
|
16
|
-
- **Sub-coordinator.** Always local, durable, one per track, and only when the program exceeds what one coordinator's drains can manage. A track the coordinator can drain itself needs no middle layer. Each nested layer re-pays a full orientation preamble, and a blocking sub-coordinator hides its children while the parent idles. Owns its track's units and boards, authors its workers' briefs, spawns its own workers and verifiers (nesting works to depth 3, and a nested spawn has the full `pstack_subagent` schema including `agent`, `role`, `cwd`, and `prompt`). Rolls up aggregates at wave boundaries. Never forwards raw child reports. Cap in-flight children at what one drain can process, roughly ten, as a rolling window. Never as blocking batches, which cost the slowest child of every batch.
|
|
17
|
-
- **Worker / verifier.** A `pstack_subagent` with its own git worktree. Verification runs the project verification skill. Reading session logs, simulators, and local IDE state need this machine. Prefer fewer, broader workers. One writer per worktree or branch (principle-separate-before-serializing-shared-state). Run a unit's verifier on a different route from its worker.
|
|
18
|
-
|
|
19
|
-
Depth stays at coordinator, track, worker. Author the track decomposition per project (build, landing, and verification are common cuts, not a required shape). Hard-coded swarm trees were tried and parked as too rigid.
|
|
20
|
-
|
|
21
|
-
#### Store layout
|
|
22
|
-
|
|
23
|
-
Create `orchestrate/<project-slug>/` in the current agent's store (path in the system prompt). Every file has exactly one writer. Owners publish facts, readers aggregate at read time. Use `bun scripts/orch/orch.ts` for bookkeeping, written below as `orch`, while its canonical plain TSV and JSON stay readable without the CLI.
|
|
24
|
-
|
|
25
|
-
- `preferences.md` is the standing-orders register: numbered lines, one constraint each (model policy, stack shape and count, verification bar, forbidden paths, escalation policy). Paste it verbatim into every spawn and every resume. Directives decay across resumes, and each dropped one costs a human turn. When you catch yourself restating an instruction, append the line before you act (principle-encode-lessons-in-structure).
|
|
26
|
-
- `overview.md` is the durable PR and issue DB. Append. Never rewrite wholesale per event.
|
|
27
|
-
- `units.tsv` has one row per unit: id, track, state, branch, PR, head SHA, brief path. Update rows in place.
|
|
28
|
-
- `frontier.json` is the computed merge frontier, per Stack safety.
|
|
29
|
-
- `ledger.tsv` is the verification ledger, per Verification.
|
|
30
|
-
- `inbox/` holds completion pointers. `gates.md` parks human gates (question, options, default on no answer).
|
|
31
|
-
- `decisions.tsv` is the trail via the show-me-your-work skill.
|
|
32
|
-
- `status.md` is derived from `units.tsv` and `ledger.tsv` at each drain, never hand-maintained. Regenerate it from the tables instead of narrating events into it.
|
|
33
|
-
|
|
34
|
-
#### The brief
|
|
35
|
-
|
|
36
|
-
Your prompts to agents are your only product, and a sloppy brief compounds into slop across the whole tree. Every spawn carries all of it. A field you cannot fill is a unit you have not scoped yet.
|
|
37
|
-
|
|
38
|
-
```
|
|
39
|
-
GOAL one sentence, the outcome, executable by a stranger with no chat access
|
|
40
|
-
SCOPE paths this unit may write; paths it may not; its exclusive worktree or branch
|
|
41
|
-
CONTEXT pointers to files and PRs; upstream reports pasted in full when this unit
|
|
42
|
-
depends on them, because workers cannot see siblings
|
|
43
|
-
ACCEPTANCE checkable criteria, one per line
|
|
44
|
-
VERIFY exact commands or the control-skill path, plus known gotchas
|
|
45
|
-
TIMEBOX rough cap on runtime; on expiry, return partial findings and stop rather than run on
|
|
46
|
-
FORBIDDEN no PR retargets or merges, no rebase, no force-push, no fixes outside scope,
|
|
47
|
-
plus unit-specific bans
|
|
48
|
-
REPORT status, branch, head SHA, PRs, verdict, what you actually ran, deviations,
|
|
49
|
-
suggested follow-ups
|
|
50
|
-
STANDING <preferences.md pasted verbatim>
|
|
51
|
-
```
|
|
52
|
-
|
|
53
|
-
Size the brief to the unit. A one-command unit gets the template collapsed to a paragraph that still names goal, scope, the verify command, and the report shape. A 4KB scaffold around a two-line edit costs more to write and obey than the edit. Local spawns may reference the standing-orders file by store path. Verbatim paste is for cloud spawns and every resume.
|
|
54
|
-
|
|
55
|
-
A sub-coordinator brief adds its track boundary and unit list, its spawn budget with the cloud default and the local exception list, the drain protocol, and the rollup format (per child: name, status, PR, head SHA, verdict, one line, plus track status and frontier delta).
|
|
56
|
-
|
|
57
|
-
A dependency is a context relay, not just ordering. Undeclared upstream context makes the worker guess. Missing fields are a refuse-to-spawn condition. Audit one sampled worker brief per sub-coordinator per wave, concurrently with the wave it samples, never as a gate in front of it. A failing brief stops that track and fixes the sub-coordinator's instructions, not just the worker, because brief quality decays late in a run. Never resume-chain a brief. Respawn fresh with consolidated scope.
|
|
58
|
-
|
|
59
|
-
#### Steps
|
|
60
|
-
|
|
61
|
-
1. **Frame.** State the done predicate as something countable ("all 126 units merged, each ledger-verified `unit-test-verified` or better"). Quantify scope: units, rough effort, expected stacks, and the wall-clock budget. If one agent could finish inside that budget, stop here and run Autonomous run instead. Collapsing must not depend on another document being present. It means do the work directly in this session, plain workers where they help, verification inline, landing as you go, and none of the store, register, or pilot machinery below. Schedule landing against the budget. By roughly 70% of it, stop spawning and land what is verified. Name the tracks per project. A contested decomposition or one-way door goes through the arena skill before the pilot. Present the framing once. Reversible prep proceeds without waiting.
|
|
62
|
-
2. **Install the runtime.** Run `orch init`. Open the trail via the show-me-your-work skill, write the standing orders before any spawn, and seed `frontier.json` from existing PRs with `orch frontier set --repo <repo-dir>`, adding `--forge origin` when the forge is Origin.
|
|
63
|
-
3. **Pilot.** Push one unit through the whole path: brief, worker, verification, stack entry, ledger row, merge. The pilot exists to falsify the brief template, the verify recipe, and the unit size while that costs one agent instead of fifty. Fix the contract from pilot evidence before any fan-out. Scale the pilot to the unit. On programs of near-identical cheap units, the first unit is the pilot, run as a normal unit with its verify command inline, and fan-out starts the moment it lands. The dedicated pilot pipeline (separate verifier agent, audit gate) is for expensive or novel unit shapes, not for clone-units where a serialized pilot has nothing to falsify.
|
|
64
|
-
4. **Scale.** Spawn a rolling window of workers up to the in-flight cap, refilling as children finish. Blocking batches pay the slowest child of every batch. Spawn track sub-coordinators only past the one-drain threshold in Roles. Recompute ready work after each drain. Relay upstream reports into downstream briefs. Keep sibling communication upward only. The sampled brief audit runs alongside the wave it samples and stops the next refill on failure, not the current one.
|
|
65
|
-
5. **Drain.** Run the queue discipline below at every drain point.
|
|
66
|
-
6. **Land.** Landing is continuous, never a terminal phase. Integration starts with the first verified unit and runs alongside the remaining waves. On heavy repos the stacker is a standing role from wave one, integrating as units verify. On repos where local git is cheap, the coordinator lands verified units itself per Roles. Keep the frontier green before upper-stack work. Stack safety governs. Advance `frontier.json` only on merge or reported new head SHAs.
|
|
67
|
-
7. **Close.** Drain the final inbox, reconcile every spawned agent to a terminal row (done, abandoned, zombie-reconciled), confirm the predicate on the real artifact, confirm every landed PR has a verdict for its current head SHA, audit the trail per show-me-your-work including its cross-model review, encode recurring corrections into `preferences.md` or the brief template. Leave the store intact. It is the postmortem.
|
|
68
|
-
|
|
69
|
-
#### Queue and drain
|
|
70
|
-
|
|
71
|
-
- On a completion notification, run `orch inbox push <agent> <unit> <status> [--report PATH]` and return to what you were doing. Never deep-review inline. A completion that needs review becomes a verifier unit. Never review a diff inside a drain.
|
|
72
|
-
- Drain in batches at four points: the end of a critical section, a track rollup, a frontier watcher wake (arm it via the loop skill, with a long heartbeat fallback), and before a human report. Begin each batch with `orch inbox drain`. Arrivals during a drain wait for the next one.
|
|
73
|
-
- Critical sections you finish first: authoring a brief, a stack operation, a conflict decision, writing a gate, updating ledger or frontier.
|
|
74
|
-
- Each drain classifies every pointer (landed, needs-verify, failed, zombie, noise), writes the resulting rows through `orch unit add`, `orch unit set`, and `orch ledger record`, runs `orch status`, then spawns the next wave in one message.
|
|
75
|
-
- Account for every spawned child at its track's rollup: arrived, respawned, or its scope explicitly absorbed. Silently redoing a missing child's work hides both the wasted spend and the coverage gap its result existed to close.
|
|
76
|
-
- A drain turn ends with the three lines from `orch status`: counts against the states, what changed, gates open. Detail lives in `status.md`. The full reply contract applies at checkpoints and close.
|
|
77
|
-
|
|
78
|
-
#### Stack safety
|
|
79
|
-
|
|
80
|
-
- The frontier is a computed object, never narrative. Recompute `frontier.json` after every merge and stack mutation: ordered PR list, branch names, head SHAs, a generation number, the lowest unmerged PR. The command walks the PR base chain through the checkout's current branch, so chain order and PR states come from the forge. It uses `gh` by default. Pass `--forge origin` when the program resolved the forge to Origin. Head SHAs come from local branch refs, so resolve it from the stacker's clone. A branch with no PR errors rather than guessing.
|
|
81
|
-
- Exactly one stacker per stack may mutate topology (chain rebases, force-pushes, base retargets, merges), serialized within its stack. Record the holder in the standing orders. Chain rebases run in cloud. A local rebase at this scale takes the laptop down.
|
|
82
|
-
- Workers never rebase and never retarget or merge PRs. Babysitters follow `playbooks/babysit.md`, one per stack, scoped to one immutable frontier generation. They report conflicts to the stacker rather than rebasing.
|
|
83
|
-
- PR closes and retargets go through the stacker only. Closing a base PR orphans every chain above it. Merges and stack surgery are units with briefs like any other.
|
|
84
|
-
- One retro watcher follows merged PRs for reverts, post-merge CI breaks, and orphaned follow-ups.
|
|
85
|
-
|
|
86
|
-
#### Verification
|
|
87
|
-
|
|
88
|
-
Scale verification to the unit. When VERIFY is a single cheap command, the worker runs it and reports the output, and the coordinator spot-checks receipts. A dedicated verifier agent (on a different model family than the worker) is for units whose verification is expensive, judgment-laden, or high-blast-radius. A verifier agent whose entire product would be rerunning one command is ceremony, not verification.
|
|
89
|
-
|
|
90
|
-
Write ledger rows with `orch ledger record`. Check the current PR and head SHA with `orch ledger check`. `ledger.tsv`, one row per verdict, keyed by PR number plus head SHA: `live-ui-verified | unit-test-verified | type-check-only | verifier-blocked | verifier-failed`. CI green is an input to a verdict, not a verdict. Behavioral work needs better than `type-check-only`. `verifier-blocked` is not a pass. Respawn when the environment heals. `verifier-failed` gets a fix unit, not a re-verify. A worker may self-report. A verifier overrides it on the same key. A new head SHA voids the row, so re-verify after restack. The ledger answers "was this verified", not memory and not the transcript.
|
|
91
|
-
|
|
92
|
-
A unit is not done until its output is externalized the moment it lands, never batched to the end of the run. A worker pushes its branch, a verifier writes its ledger row, receipts land in the store. Work that exists only on one VM when that VM dies was never done.
|
|
93
|
-
|
|
94
|
-
#### Liveness and failure
|
|
95
|
-
|
|
96
|
-
- Never resume an agent to check on it. A resume restarts an idle agent. Probe read-only: the ledger, `units.tsv`, `gh`, pushed branches. Session-log mtime is not liveness.
|
|
97
|
-
- A silent death gets a synthetic postmortem row in the inbox (unit, failure mode, last evidence, options). Replan on evidence as it arrives. Never wait for full quiescence.
|
|
98
|
-
- Retry by mode: cap-hit or oom, respawn with smaller scope. Network-drop, retry as-is. Tool-error, retry on a different model. Unknown, retry once. Two retries, then abandon the unit and replan around it.
|
|
99
|
-
- A zombie that returns hours late reconciles against the current frontier and ledger before anything is accepted. Salvage unique findings through a fresh unit, never a blind merge.
|
|
100
|
-
- When continued spawning would produce garbage tree-wide (bad upstream output, broken acceptance, dead infra), write a stop line at the top of the standing orders, let in-flight work finish, fix the cause, clear it.
|
|
101
|
-
- Bound your own infra retries the same way you bound a child's. After a few consecutive tool aborts, stop retrying. Write a terminal handoff to durable state (what is done, where it lives, the exact command to resume) and end the run.
|
|
102
|
-
- After a harness restart: local agents are dead. Re-read the standing orders and `units.tsv`, recompute the frontier, reattach work by PR and branch rather than agent id, respawn one sub-coordinator per track from its stored brief plus current state, drain, resume. The dead session's store lock clears itself on the next write. `orch` replaces a lock whose holder pid is gone.
|
|
103
|
-
|
|
104
|
-
#### Escalation
|
|
105
|
-
|
|
106
|
-
Reaches the human, batched into the status page rather than per item: irreversible actions (force-push to shared branches, deploys, deletions, closing someone else's PR), genuine product or preference calls no experiment settles, a standing order that contradicts observed reality, a program-level dead end that survived a replan. Park each as a `gates.md` entry before asking, and route work around it.
|
|
107
|
-
|
|
108
|
-
Never reaches the human: frontier nudges, rebase mechanics, retries, CI flake triage, review-thread triage, format fixes, scope the brief already forbids (refuse and continue), and "should I keep going". When in doubt, act and log.
|
|
109
|
-
|
|
110
|
-
Mid-run discoveries fix only what blocks the frontier. Everything else parks in follow-ups. At this fan-out a small scope leak multiplies into PRs nobody asked for.
|
|
111
|
-
|
|
112
|
-
**Reply:** at checkpoints and close: the predicate and the count against it from `units.tsv` and `ledger.tsv`, tracks and what each landed, the frontier (PR list plus SHAs), verdicts summary, what was abandoned and why, gates awaiting the human (the only asks), the store path, and the trail path. Numbers from the tables, not narrative. Include PR links.
|
|
@@ -1,25 +0,0 @@
|
|
|
1
|
-
### Perf issue
|
|
2
|
-
|
|
3
|
-
**You own the measurement story. Plan, review, verify the numbers.** Tie every fix to a measurement, don't read source instead of measuring.
|
|
4
|
-
|
|
5
|
-
1. Capture a baseline trace via the matching verification skill. Vet the baseline, and each later number, with the **benchmark-checklist** skill.
|
|
6
|
-
2. `how` to ground hypotheses. Don't claim a perf ceiling without running it first.
|
|
7
|
-
Try the performance mantras in order, cheapest first:
|
|
8
|
-
1. Don't do it. Stop work whose result nothing uses rather than cheapening it.
|
|
9
|
-
2. Do it, but don't do it again.
|
|
10
|
-
3. Do it less.
|
|
11
|
-
4. Do it later.
|
|
12
|
-
5. Do it when they're not looking.
|
|
13
|
-
6. Do it concurrently.
|
|
14
|
-
7. Do it cheaper.
|
|
15
|
-
|
|
16
|
-
When an earlier mantra meets the target, stop.
|
|
17
|
-
3. Plan the fix from the trace. If it crosses a function boundary, `architect` first. Delegate implementation to a subagent using your configured perf-issue model (the configured role route). Pick each subagent's reasoning level and fast or standard speed for the job, per the Subagents section. Review the diff. Capture a post-fix trace.
|
|
18
|
-
Apply the **sequence-verifiable-units** principle skill, verifying each attempt before trying the next.
|
|
19
|
-
4. Parse and compare the artifacts (JSON to sqlite, diff). "Inconclusive" or wrong-surface is not a pass. Flag it.
|
|
20
|
-
5. Cite the measurement in the PR.
|
|
21
|
-
6. Run **Opening a PR**.
|
|
22
|
-
|
|
23
|
-
For sustained improvement against a metric rather than a one-off fix, use the Hillclimb playbook (`playbooks/hillclimb.md`).
|
|
24
|
-
|
|
25
|
-
**Reply:** baseline number, post-fix number, delta, artifact path.
|
|
@@ -1,16 +0,0 @@
|
|
|
1
|
-
### Refactoring
|
|
2
|
-
|
|
3
|
-
**You own the contract. The structure changes. The behavior does not.** Distinct from Feature, which adds behavior, and Bug fix, which corrects it.
|
|
4
|
-
|
|
5
|
-
If the cleanup reveals a missing feature or a real bug, split it out and ship the structural change first against the pinned contract. A redesign is allowed, but name it and route to Feature. Large or cross-cutting structural work belongs to the **figure-it-out** skill. This playbook is the focused-to-medium change.
|
|
6
|
-
|
|
7
|
-
1. Pin the behavior contract first. Run the **how** skill over the affected subsystem to learn the contract, then write a characterization test, snapshot, or equivalence harness that captures current behavior before any structure moves. If the area has no coverage, write the pin before touching structure. Type check and lint are not a pin.
|
|
8
|
-
2. Name the structure the code is missing per **principle-model-the-domain**. Boring code stays when the shape is already clear and local. The reshape must delete branches or invalid states, not add indirection.
|
|
9
|
-
3. Name the target shape. State what the module layout, types, and call graph should be if built today (**principle-foundational-thinking**, **principle-redesign-from-first-principles**). If the target crosses a function boundary, run the **architect** skill for parallel design exploration of the shape before the move.
|
|
10
|
-
4. Subtract before you add. Delete dead code, collapse one-caller wrappers, drop redundant validators, and remove orphan references before introducing the new shape (**principle-subtract-before-you-add**). The smallest change that reaches the target shape ships (**principle-laziness-protocol**). A speculative cleanup that "might help" gets reverted.
|
|
11
|
-
5. Move in small behavior-preserving steps, each keeping the pin green. For API reshapes, migrate every caller and delete the old API in the same wave (**principle-migrate-callers-then-delete-legacy-apis**). No compatibility shims, no parallel old-and-new paths. Spot-check every rename against the actual files. Renames silently miss usages in strings, prose, and back-references. Delegate the mechanical edits to a subagent using your configured refactoring model (the configured role route) with a specific scope (file paths, the names being moved, the behavior to hold). Pick each subagent's reasoning level and fast or standard speed for the job, per the Subagents section.
|
|
12
|
-
6. Prove behavior is unchanged on the real artifact, not "it compiles" (**principle-prove-it-works**). For larger reshapes, run an equivalence check: a script that diffs old-vs-new outputs, a recorded baseline replayed against the new code, or a smoke run on the matching surface via the relevant verification skill.
|
|
13
|
-
7. Confirm the change is worth keeping. The success measure is reduced reader load (**principle-minimize-reader-load**). If the diff does not lower reader load somewhere, revert it.
|
|
14
|
-
8. Rebase into small ordered commits. A subtraction commit, then the reshape, then any follow-on cleanup. Shape them with the **sequence-verifiable-units** principle skill, so each behavior-preserving slice stays green before the next. Run **Opening a PR**.
|
|
15
|
-
|
|
16
|
-
**Reply:** the structure that changed, the pin you held it against, the equivalence proof, the reader-load delta, what shipped and what got reverted. No new behavior.
|
|
@@ -1,12 +0,0 @@
|
|
|
1
|
-
### Shipping
|
|
2
|
-
|
|
3
|
-
**You own what lands. Verify each PR independently, land only the verified run from the root, then keep your hands off the stack.**
|
|
4
|
-
|
|
5
|
-
1. **Resolve the forge, then verify each PR independently before it lands.** GitHub CLI (`gh`) is the default. If `command -v origin` succeeds and Origin can resolve the repository, use `origin pr` for every PR operation. Otherwise stay on `gh` and record the fallback. Never require Graphite (`gt`). One verifier per PR, each a worktree subagent, runs the change the way a user would with the matching verification skill (such as the project verification skill), parent against head, and posts `PASS`, `PASS+NOTES`, or `FAIL` on that PR. Only a verdict from an agent that did not write the code counts, because an author checks what it meant to build. Green CI and an approving bot review are not verdicts, because neither runs the change as a user would.
|
|
6
|
-
2. **Land only the contiguous verified run rooted at the bottom.** Walk up from the lowest unmerged PR and stop at the first one without `PASS` or `PASS+NOTES`. The PRs below it are the run, and the top one is the ceiling. A verified PR above an unverified one waits, because it cannot land without the code below it. One whose branch neither holds nor needs that code can move onto trunk and land on its own. It needs a fresh verdict first, because its old one ran with that code beneath it and trunk does not have it.
|
|
7
|
-
3. **Re-check that the verdicts still describe the code.** A verdict covers a patch, and a chain rebase moves every PR above it to a new SHA without failing any check. Compare `git patch-id` at the verdict SHA with the current head before trusting an older verdict. When the patches differ only in tests, docs, or lint config, a lane's result stands if what it ran builds the same at both SHAs apart from noise. Noise is a difference that also shows up between two builds of the verdict SHA, or an embedded commit SHA. Report each kind of noise with its files, so a reader can check the call. The change itself still gets fresh checks and a review, because the old verdict never saw it. A lane with no build output, such as a dev server, cannot show this, so rerun it, and re-verify anything else that drifted.
|
|
8
|
-
4. **Land bottom-up, one PR at a time.** Always merge the run's lowest unmerged PR, with `origin pr merge <pr>` or `gh pr merge <pr> --squash`. On Origin the plain command also merges every PR below the one you name, and on GitHub a PR whose base is still its parent's branch merges into that branch, not trunk. Read the PR back for the result (`origin pr view <pr>` or `gh pr view <pr> --json state,mergedAt,baseRefName`), because a merge command can report success when a merge queue only queued the PR, and a requested auto-merge is not a merge. A landed PR reads merged with trunk as its base, not its parent's branch. Arm `--auto` (Origin merge-when-ready or GitHub auto-merge) only on a PR whose verdict covers its current head, because it lands whatever head is ready. After a merge lands, retarget the PR whose base was the merged branch to trunk (`origin pr edit <pr> --base <trunk>` or `gh pr edit <pr> --base <trunk>`), move its patch onto the merge result, and push with `--force-with-lease`. The verdict covers the patch, not its commits, so step 3's patch-id rule decides whether the verdict survives. Merge it once its checks pass and its verdict survives.
|
|
9
|
-
5. **Leave the stack alone while it lands.** Step 4's move of the next PR is the only change to a branch or base, because a merge lands whatever its branch and base hold at that moment, verdict or not. On GitHub, watch the run with the queued watcher from `playbooks/babysit.md` (`scripts/watch-pr/watch-pr --queued-stack --stack-prs <bottom-to-top>`) under `schedule_create` until it reports `COMPLETE` at the ceiling. On Origin, re-read the current PR with `origin pr view <pr> --checks` each time `origin pr checks <pr> --watch` returns, until the ceiling reads merged. A base that moves to trunk when its parent merges is expected, not damage to repair. If a merge stalls, find out why before you change anything.
|
|
10
|
-
6. **Stop at the ceiling.** Extending the run takes new verdicts, so it is a new pass through step 1.
|
|
11
|
-
|
|
12
|
-
**Reply:** the verified run and its ceiling, each PR's verdict and who produced it, what landed and how you confirmed it, and what the next gap needs.
|