@mccune1224/pi-pstack 0.1.0
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 +21 -0
- package/README.md +142 -0
- package/agents/comment-sicko.md +37 -0
- package/agents/poteto-agent.md +16 -0
- package/docs/guide/01-setup.md +49 -0
- package/docs/guide/02-poteto-mode.md +98 -0
- package/docs/guide/03-understand.md +61 -0
- package/docs/guide/04-design.md +81 -0
- package/docs/guide/05-build-and-clean.md +75 -0
- package/docs/guide/06-verify-and-ship.md +87 -0
- package/docs/guide/07-overnight.md +81 -0
- package/docs/guide/08-principles.md +69 -0
- package/docs/guide/09-make-it-yours.md +67 -0
- package/docs/guide/10-recipes-and-pitfalls.md +94 -0
- package/docs/guide/README.md +30 -0
- package/docs/guide/images/design.jpg +0 -0
- package/docs/guide/images/overnight.jpg +0 -0
- package/docs/guide/images/recipes.jpg +0 -0
- package/docs/guide/images/router.jpg +0 -0
- package/docs/guide/images/understanding.jpg +0 -0
- package/docs/guide/images/verification.jpg +0 -0
- package/extensions/index.ts +358 -0
- package/extensions/settings.test.ts +110 -0
- package/extensions/settings.ts +240 -0
- package/package.json +77 -0
- package/skills/architect/SKILL.md +83 -0
- package/skills/architect/references/design-red-flags.md +33 -0
- package/skills/architect/references/rationale-template.md +35 -0
- package/skills/architect/references/runner-prompt.md +20 -0
- package/skills/arena/SKILL.md +71 -0
- package/skills/automate-me/SKILL.md +109 -0
- package/skills/blast-radius/SKILL.md +50 -0
- package/skills/bro/SKILL.md +7 -0
- package/skills/control-cli/SKILL.md +109 -0
- package/skills/control-ui/SKILL.md +109 -0
- package/skills/create-skill/SKILL.md +69 -0
- package/skills/create-verification-skill/SKILL.md +44 -0
- package/skills/create-verification-skill/references/feature-map-example/README.md +47 -0
- package/skills/create-verification-skill/references/feature-map-example/create-note.md +39 -0
- package/skills/create-verification-skill/references/feature-map-example/search.md +45 -0
- package/skills/deslop/SKILL.md +22 -0
- package/skills/figure-it-out/SKILL.md +55 -0
- package/skills/how/SKILL.md +130 -0
- package/skills/how/references/critic-prompt.md +59 -0
- package/skills/how/references/critique-rubric.md +58 -0
- package/skills/how/references/explainer-prompt.md +55 -0
- package/skills/how/references/explorer-prompt.md +52 -0
- package/skills/interrogate/SKILL.md +112 -0
- package/skills/interrogate/references/code-quality-review.md +47 -0
- package/skills/interrogate/references/lead-judgment.md +58 -0
- package/skills/interrogate/references/reviewer-prompt.md +72 -0
- package/skills/interrogate/references/rubric.md +77 -0
- package/skills/maintain-verification-skill/SKILL.md +39 -0
- package/skills/no-comments/SKILL.md +24 -0
- package/skills/poteto-mode/SKILL.md +142 -0
- package/skills/poteto-mode/playbooks/authoring-a-skill.md +12 -0
- package/skills/poteto-mode/playbooks/autonomous-run.md +13 -0
- package/skills/poteto-mode/playbooks/autopilot-full.md +13 -0
- package/skills/poteto-mode/playbooks/autopilot-stack.md +16 -0
- package/skills/poteto-mode/playbooks/babysit.md +27 -0
- package/skills/poteto-mode/playbooks/bug-fix.md +17 -0
- package/skills/poteto-mode/playbooks/eval.md +27 -0
- package/skills/poteto-mode/playbooks/feature.md +21 -0
- package/skills/poteto-mode/playbooks/hillclimb.md +21 -0
- package/skills/poteto-mode/playbooks/investigation.md +14 -0
- package/skills/poteto-mode/playbooks/multi-phase-plan.md +155 -0
- package/skills/poteto-mode/playbooks/opening-a-pr.md +29 -0
- package/skills/poteto-mode/playbooks/orchestrate.md +113 -0
- package/skills/poteto-mode/playbooks/pause-safely.md +10 -0
- package/skills/poteto-mode/playbooks/perf-issue.md +24 -0
- package/skills/poteto-mode/playbooks/prototype.md +14 -0
- package/skills/poteto-mode/playbooks/refactoring.md +16 -0
- package/skills/poteto-mode/playbooks/runtime-forensics.md +11 -0
- package/skills/poteto-mode/playbooks/session-pickup.md +13 -0
- package/skills/poteto-mode/playbooks/shipping.md +20 -0
- package/skills/poteto-mode/playbooks/trace-forensics.md +14 -0
- package/skills/poteto-mode/playbooks/visual-parity.md +11 -0
- package/skills/poteto-mode/playbooks/worktree-cleanup.md +14 -0
- package/skills/poteto-mode/references/bugbot-triage.md +142 -0
- package/skills/poteto-mode/scripts/bootstrap.ts +62 -0
- package/skills/poteto-mode/scripts/bun.lock +67 -0
- package/skills/poteto-mode/scripts/check-plan.mjs +186 -0
- package/skills/poteto-mode/scripts/orch/orch.test.ts +634 -0
- package/skills/poteto-mode/scripts/orch/orch.ts +578 -0
- package/skills/poteto-mode/scripts/orch/store.ts +1607 -0
- package/skills/poteto-mode/scripts/package.json +16 -0
- package/skills/poteto-mode/scripts/watch-pr/cli.test.ts +224 -0
- package/skills/poteto-mode/scripts/watch-pr/cli.ts +223 -0
- package/skills/poteto-mode/scripts/watch-pr/fakes.test-helper.ts +118 -0
- package/skills/poteto-mode/scripts/watch-pr/github.test.ts +306 -0
- package/skills/poteto-mode/scripts/watch-pr/github.ts +699 -0
- package/skills/poteto-mode/scripts/watch-pr/policy.test.ts +420 -0
- package/skills/poteto-mode/scripts/watch-pr/policy.ts +832 -0
- package/skills/poteto-mode/scripts/watch-pr/render.ts +169 -0
- package/skills/poteto-mode/scripts/watch-pr/tsconfig.json +13 -0
- package/skills/poteto-mode/scripts/watch-pr/types.compile.ts +93 -0
- package/skills/poteto-mode/scripts/watch-pr/types.ts +401 -0
- package/skills/poteto-mode/scripts/watch-pr/watch-pr +6 -0
- package/skills/poteto-mode/scripts/worktree-audit.mjs +178 -0
- package/skills/principle-boundary-discipline/SKILL.md +34 -0
- package/skills/principle-build-the-lever/SKILL.md +23 -0
- package/skills/principle-encode-lessons-in-structure/SKILL.md +31 -0
- package/skills/principle-exhaust-the-design-space/SKILL.md +21 -0
- package/skills/principle-experience-first/SKILL.md +19 -0
- package/skills/principle-fix-root-causes/SKILL.md +23 -0
- package/skills/principle-foundational-thinking/SKILL.md +21 -0
- package/skills/principle-guard-the-context-window/SKILL.md +17 -0
- package/skills/principle-laziness-protocol/SKILL.md +18 -0
- package/skills/principle-make-operations-idempotent/SKILL.md +24 -0
- package/skills/principle-migrate-callers-then-delete-legacy-apis/SKILL.md +22 -0
- package/skills/principle-minimize-reader-load/SKILL.md +23 -0
- package/skills/principle-model-the-domain/SKILL.md +26 -0
- package/skills/principle-never-block-on-the-human/SKILL.md +23 -0
- package/skills/principle-outcome-oriented-execution/SKILL.md +22 -0
- package/skills/principle-prove-it-works/SKILL.md +33 -0
- package/skills/principle-redesign-from-first-principles/SKILL.md +16 -0
- package/skills/principle-separate-before-serializing-shared-state/SKILL.md +16 -0
- package/skills/principle-sequence-verifiable-units/SKILL.md +22 -0
- package/skills/principle-subtract-before-you-add/SKILL.md +22 -0
- package/skills/principle-type-system-discipline/SKILL.md +31 -0
- package/skills/recall/SKILL.md +35 -0
- package/skills/reflect/SKILL.md +77 -0
- package/skills/reflect/references/divergent-reviewer.md +43 -0
- package/skills/reflect/references/judgment-reviewer.md +42 -0
- package/skills/reflect/references/synthesizer.md +56 -0
- package/skills/reflect/references/tooling-reviewer.md +57 -0
- package/skills/setup-pstack/SKILL.md +92 -0
- package/skills/show-me-your-work/SKILL.md +82 -0
- package/skills/show-me-your-work/references/decision-log-template.tsv +1 -0
- package/skills/show-me-your-work/scripts/log.mjs +30 -0
- package/skills/swarm/SKILL.md +46 -0
- package/skills/tdd/SKILL.md +44 -0
- package/skills/teach/SKILL.md +21 -0
- package/skills/technical-writing/SKILL.md +130 -0
- package/skills/typescript-best-practices/SKILL.md +28 -0
- package/skills/typescript-best-practices/references/patterns.md +292 -0
- package/skills/unslop/SKILL.md +80 -0
- package/skills/why/SKILL.md +229 -0
- package/skills/why/references/epistemics.md +144 -0
- package/skills/why/references/investigator-prompt.md +103 -0
- package/skills/why/references/source-playbook.md +17 -0
- package/skills/why/references/sources/code-archaeology.md +88 -0
- package/skills/why/references/sources/databricks.md +70 -0
- package/skills/why/references/sources/datadog.md +99 -0
- package/skills/why/references/sources/incident-postmortem.md +15 -0
- package/skills/why/references/sources/linear.md +48 -0
- package/skills/why/references/sources/notion.md +55 -0
- package/skills/why/references/sources/sentry.md +100 -0
- package/skills/why/references/sources/slack.md +54 -0
- package/skills/why/references/synthesizer-prompt.md +135 -0
|
@@ -0,0 +1,87 @@
|
|
|
1
|
+
# Verify the result and open a PR
|
|
2
|
+
|
|
3
|
+
"It compiles" is not evidence. The [Prove It Works principle](../../skills/principle-prove-it-works/SKILL.md) makes the agent check the real artifact before it reports success, and your job is to make "the real artifact" checkable. This page covers stating a finish condition, generating a verification skill for your app, opening the PR, and driving it to merged.
|
|
4
|
+
|
|
5
|
+

|
|
6
|
+
|
|
7
|
+
## State the finish condition up front
|
|
8
|
+
|
|
9
|
+
Put what done means in the first prompt, in whatever words fit:
|
|
10
|
+
|
|
11
|
+
```text
|
|
12
|
+
/poteto-mode add json output to this command. text output stays byte-identical, the json parses, both run against the sample project. show me the evidence.
|
|
13
|
+
```
|
|
14
|
+
|
|
15
|
+
Now the agent has three checks it can run, not a mood to satisfy. When the reply comes back, it should carry the exact commands and outputs. If a check couldn't run, a good reply says "inconclusive", and you should treat a confident reply without evidence as a red flag.
|
|
16
|
+
|
|
17
|
+
Match the check to the change:
|
|
18
|
+
|
|
19
|
+
- A CLI change runs the real command.
|
|
20
|
+
- A UI change walks the changed flow in the running app.
|
|
21
|
+
- A parser or migration replays a saved input.
|
|
22
|
+
- A perf change compares before and after profiles.
|
|
23
|
+
- A storage change reads back the written value.
|
|
24
|
+
|
|
25
|
+
For a small diff you don't fully trust, [`/blast-radius`](../../skills/blast-radius/SKILL.md) finds what it could break elsewhere. It picks the one fact the change is safe because of and proves it by running code instead of writing an essay about it.
|
|
26
|
+
|
|
27
|
+
## Create a project verification skill
|
|
28
|
+
|
|
29
|
+
The UI bullet above hides a real requirement. The agent needs a scripted way to drive your app. If your project has one, great. If not, run:
|
|
30
|
+
|
|
31
|
+
```text
|
|
32
|
+
/create-verification-skill
|
|
33
|
+
```
|
|
34
|
+
|
|
35
|
+
[`/create-verification-skill`](../../skills/create-verification-skill/SKILL.md) interviews the repository, not you. It works out what a user touches, how the app launches locally, what can drive it (an existing harness first, otherwise browser and CDP, a PTY, or plain HTTP), what evidence proves behavior, and whether two instances can run side by side. It asks you only what the code can't answer.
|
|
36
|
+
|
|
37
|
+
It writes `.pi/skills/verify-<app>/`, agent-facing instructions with exact Launch, Doctor, Drive, Evidence, and Cleanup sections, plus a feature map under `features/` that indexes what the app does and what result proves each feature works. The skill ships a [worked feature-map example](../../skills/create-verification-skill/references/feature-map-example/) with a README index and one file per feature using the four required H2s. Before handing it over, the generator proves the skill once end to end: launch, doctor check, drive one feature, capture evidence, clean up. If that proof fails, don't use the output.
|
|
38
|
+
|
|
39
|
+
From then on, "verify it in the app" is a step any agent can execute, in this repo, with no setup conversation.
|
|
40
|
+
|
|
41
|
+
Once the verify skill works, a [`/swarm`](../../skills/swarm/SKILL.md) can split a full pass by feature-map entry and aggregate the results.
|
|
42
|
+
|
|
43
|
+
## Keep the verification skill honest
|
|
44
|
+
|
|
45
|
+
Apps change and feature maps rot. When yours drifts, run:
|
|
46
|
+
|
|
47
|
+
```text
|
|
48
|
+
/maintain-verification-skill
|
|
49
|
+
```
|
|
50
|
+
|
|
51
|
+
[`/maintain-verification-skill`](../../skills/maintain-verification-skill/SKILL.md) audits the generated skill: one read-only source reader per feature in parallel, then one live pass that drives every mapped feature. It ends in exactly one of three outcomes. `clean` means full coverage and nothing to ship. `changed` means one PR of proven corrections, confined to the verification skill's own directory. `blocked` names the blocker. It never edits product code. If the live pass catches a product regression, it reports the regression instead of papering over it in docs.
|
|
52
|
+
|
|
53
|
+
## Open the PR
|
|
54
|
+
|
|
55
|
+
```text
|
|
56
|
+
/poteto-mode open the pr. small ordered commits, evidence in the description.
|
|
57
|
+
```
|
|
58
|
+
|
|
59
|
+
The [Opening a PR playbook](../../skills/poteto-mode/playbooks/opening-a-pr.md) works from a worktree, rebases the work into small ordered commits, cleans the diff, unslops the prose, and returns the PR link. Five narrow PRs beat one fat one, and stacked follow-ups beat a growing branch.
|
|
60
|
+
|
|
61
|
+
## Drive the PR to merge-ready with Babysit
|
|
62
|
+
|
|
63
|
+
An open PR starts collecting blockers immediately. Checks fail, reviewers comment, trunk moves. Hand that churn to the [Babysit playbook](../../skills/poteto-mode/playbooks/babysit.md):
|
|
64
|
+
|
|
65
|
+
```text
|
|
66
|
+
/poteto-mode babysit this pr. get it green.
|
|
67
|
+
```
|
|
68
|
+
|
|
69
|
+
Babysit watches the PR with a bundled watcher and takes blockers in order: conflicts, then review threads, then CI. Every known fix batches into one push, so the checks restart once instead of after every fix. The comment triage is skeptical, because humans and bots file real catches and noise in the same list. A real finding gets a fix, and noise gets dismissed with the disproof posted on the thread. When all you want is status, ask smaller and Babysit answers without starting the loop:
|
|
70
|
+
|
|
71
|
+
```text
|
|
72
|
+
/poteto-mode check on pr 123. anything outstanding?
|
|
73
|
+
```
|
|
74
|
+
|
|
75
|
+
Babysit stops at merge-ready. It never merges, even with everything green, because merging is a different decision.
|
|
76
|
+
|
|
77
|
+
## Land the stack with Shipping
|
|
78
|
+
|
|
79
|
+
Green is not the same as safe. When you're ready to land, say so:
|
|
80
|
+
|
|
81
|
+
```text
|
|
82
|
+
/poteto-mode land the stack.
|
|
83
|
+
```
|
|
84
|
+
|
|
85
|
+
The [Shipping playbook](../../skills/poteto-mode/playbooks/shipping.md) verifies each PR independently before it arms anything. One fresh agent per PR proves the behavior live, and the agent that judges a change is never the one that wrote it. Then Shipping lands only the contiguous verified run from the bottom, through Graphite merge-when-ready, and reports the first PR that breaks the chain. A verified PR sitting above an unverified one waits, because merging it would pull the gap in underneath.
|
|
86
|
+
|
|
87
|
+
Next: [Run work while you sleep](./07-overnight.md).
|
|
@@ -0,0 +1,81 @@
|
|
|
1
|
+
# Run work while you sleep
|
|
2
|
+
|
|
3
|
+
This is the payoff for everything before it. An agent you can trust to verify its own work is an agent you can leave alone with a hard task. What makes that safe isn't hope. It's a checkable finish condition, an isolated worktree, and a decision log you audit in the morning.
|
|
4
|
+
|
|
5
|
+

|
|
6
|
+
|
|
7
|
+
## The overnight contract
|
|
8
|
+
|
|
9
|
+
A good handoff has the goal, the finish condition, permissions, and an escape hatch. It doesn't need to be long:
|
|
10
|
+
|
|
11
|
+
```text
|
|
12
|
+
/poteto-mode im going to bed. migrate every caller to the new parser in a fresh worktree off <base>.
|
|
13
|
+
done means zero old callers, all parser fixtures pass, old api deleted.
|
|
14
|
+
keep a decision log. don't ask me before committing.
|
|
15
|
+
/loop until done. if you're truly stuck after a few hours, stop and write up why.
|
|
16
|
+
```
|
|
17
|
+
|
|
18
|
+
Walk through what each line buys you:
|
|
19
|
+
|
|
20
|
+
- "im going to bed" is a session override. The agent stops asking and keeps going.
|
|
21
|
+
- "done means..." turns the goal into checks every iteration can run.
|
|
22
|
+
- "fresh worktree off `<base>`" keeps the run from colliding with anything else you have open.
|
|
23
|
+
- "don't ask me before committing" pre-answers the permission the agent would otherwise block on.
|
|
24
|
+
- Pi has no `/loop`. The [Autonomous run playbook](../../skills/poteto-mode/playbooks/autonomous-run.md) re-checks the finish condition on events or a heartbeat. Saying "keep going until the goal is done" keeps the run alive without one.
|
|
25
|
+
- The escape hatch lets it stop at a genuine dead end and write up why, which beats eight hours of creative goal reinterpretation.
|
|
26
|
+
|
|
27
|
+
Because you'll review this work after stepping away, `/poteto-mode` routes it through [`/figure-it-out`](../../skills/figure-it-out/SKILL.md), which designs the run's phases before any code and wires in the decision log.
|
|
28
|
+
|
|
29
|
+
## What the loop does all night
|
|
30
|
+
|
|
31
|
+
```mermaid
|
|
32
|
+
flowchart TD
|
|
33
|
+
A[Check the finish condition] --> B[Make the smallest justified change]
|
|
34
|
+
B --> C[Verify against the real artifact]
|
|
35
|
+
C --> D{Progress?}
|
|
36
|
+
D -->|Yes| E[Commit]
|
|
37
|
+
D -->|No| F[Discard]
|
|
38
|
+
E --> G[Log one decision row]
|
|
39
|
+
F --> G
|
|
40
|
+
G --> A
|
|
41
|
+
```
|
|
42
|
+
|
|
43
|
+
One change, one check, one log row, every iteration. Changes that didn't help get discarded, not left to ride. A plateau means pivot, not stop, and the finish condition never quietly relaxes to declare victory.
|
|
44
|
+
|
|
45
|
+
## The morning audit
|
|
46
|
+
|
|
47
|
+
[`/show-me-your-work`](../../skills/show-me-your-work/SKILL.md) is what makes the run reviewable. Each row records the time, phase, decision, reason, an evidence pointer, and the result, in a TSV at `decisions.tsv` (or `.audit/<task-slug>.tsv` when several runs share a directory). It stays local by default. Commit it when the work is ambitious enough that a reviewer needs the trail to trust the result.
|
|
48
|
+
|
|
49
|
+
When you're back, ask for the run in review form:
|
|
50
|
+
|
|
51
|
+
```text
|
|
52
|
+
/show-me-your-work catch me up on what you did last night
|
|
53
|
+
```
|
|
54
|
+
|
|
55
|
+
Before the skill hands back its summary, it spawns a reviewer on a different model family to read the trail and the transcript, and the reply ends with an Attention section listing what deserves your scrutiny. Read that section first, then the log rows it points at. You're auditing decisions, not re-reading the whole night.
|
|
56
|
+
|
|
57
|
+
## When the night holds a queue, not a task
|
|
58
|
+
|
|
59
|
+
The contract above drives one task to one finish condition. Some nights hold more, a queue of independent changes or a whole program. Three playbooks scale the same trust up.
|
|
60
|
+
|
|
61
|
+
[Autopilot-full](../../skills/poteto-mode/playbooks/autopilot-full.md) runs a queue of independent PRs to merged. Each PR gets one owner agent that carries it from build through merge, and no owner merges on its own verdict. A swarm of fresh verifiers checks every merge-ready head, and only a clean verdict authorizes the merge:
|
|
62
|
+
|
|
63
|
+
```text
|
|
64
|
+
/poteto-mode full autopilot on this queue. each item is independent. i want them merged by morning.
|
|
65
|
+
```
|
|
66
|
+
|
|
67
|
+
[Autopilot-stack](../../skills/poteto-mode/playbooks/autopilot-stack.md) runs the same owner loop but ships nothing. You wake up to one linear Graphite stack with a verifier's verdict on every link, and you review and land it yourself. Pick it over Autopilot-full when the changes are coupled, or when you want your own eyes on the work before anything merges:
|
|
68
|
+
|
|
69
|
+
```text
|
|
70
|
+
/poteto-mode autopilot these five changes but stack them, don't ship. i'll land the stack in the morning.
|
|
71
|
+
```
|
|
72
|
+
|
|
73
|
+
[Orchestrate](../../skills/poteto-mode/playbooks/orchestrate.md) is for a program that outlives any single agent: multi-day, many stacked PRs, fleets of subagents under one standing coordinator chat. The coordinator authors briefs, collects what its subagents finish, keeps the lowest unmerged PR green, and never writes code itself. It's deliberately heavy machinery. If one agent could finish the work in a session, the playbook itself routes you back to the overnight contract above:
|
|
74
|
+
|
|
75
|
+
```text
|
|
76
|
+
/poteto-mode orchestrate the store migration. own it until every package is converted and merged. i'll check in twice a day.
|
|
77
|
+
```
|
|
78
|
+
|
|
79
|
+
**Pitfall:** a duration is not a finish condition. "work on this for 4 hours" gives the agent nothing to check, and you'll wake up to four hours of motion instead of a result. Give `/loop` a predicate that can pass or fail.
|
|
80
|
+
|
|
81
|
+
Next: [Steer with principle names](./08-principles.md).
|
|
@@ -0,0 +1,69 @@
|
|
|
1
|
+
# Steer with principle names
|
|
2
|
+
|
|
3
|
+
pstack ships 21 principles as individual skills. `/poteto-mode` reads their index at the start of every multi-step task, applies the ones the task triggers, and names each applied principle in its reply along with the decision it changed.
|
|
4
|
+
|
|
5
|
+
You don't invoke principles. You use their names to steer. Each name points at a complete rule the agent has already read, so one phrase redirects the work more precisely than a paragraph of instructions.
|
|
6
|
+
|
|
7
|
+
## Steering in practice
|
|
8
|
+
|
|
9
|
+
Say the agent is about to bolt a new adapter onto three existing ones:
|
|
10
|
+
|
|
11
|
+
```text
|
|
12
|
+
use subtract before you add. delete the obsolete adapters first, then design what's left.
|
|
13
|
+
```
|
|
14
|
+
|
|
15
|
+
Say it claims success because the build passed:
|
|
16
|
+
|
|
17
|
+
```text
|
|
18
|
+
apply prove it works. run the real import flow and show me the written records.
|
|
19
|
+
```
|
|
20
|
+
|
|
21
|
+
Say two parallel attempts are about to write to the same branch:
|
|
22
|
+
|
|
23
|
+
```text
|
|
24
|
+
separate before serializing shared state. give each attempt its own worktree, no locks.
|
|
25
|
+
```
|
|
26
|
+
|
|
27
|
+
Each phrase lands because the rule behind it is specific. The agent still has to say, in its reply, which decision the rule changed. A principle citation with no decision behind it is the tell that it name-dropped instead of applying.
|
|
28
|
+
|
|
29
|
+
## The 21, briefly
|
|
30
|
+
|
|
31
|
+
The core principles decide how much to build and when to rethink the design:
|
|
32
|
+
|
|
33
|
+
- [Laziness Protocol](../../skills/principle-laziness-protocol/SKILL.md) prefers deletion and the smallest change that solves the problem.
|
|
34
|
+
- [Foundational Thinking](../../skills/principle-foundational-thinking/SKILL.md) chooses the core data structures before writing logic.
|
|
35
|
+
- [Redesign from First Principles](../../skills/principle-redesign-from-first-principles/SKILL.md) integrates a new requirement as if it had been there from day one.
|
|
36
|
+
- [Subtract Before You Add](../../skills/principle-subtract-before-you-add/SKILL.md) removes dead weight before building on top of it.
|
|
37
|
+
- [Minimize Reader Load](../../skills/principle-minimize-reader-load/SKILL.md) collapses layers and hidden state a reader must hold in their head.
|
|
38
|
+
- [Outcome-Oriented Execution](../../skills/principle-outcome-oriented-execution/SKILL.md) converges rewrites on the target design instead of preserving throwaway compatibility states.
|
|
39
|
+
- [Experience First](../../skills/principle-experience-first/SKILL.md) chooses the user's result over implementation convenience.
|
|
40
|
+
- [Exhaust the Design Space](../../skills/principle-exhaust-the-design-space/SKILL.md) builds two or three competing prototypes when there's no precedent.
|
|
41
|
+
- [Build the Lever](../../skills/principle-build-the-lever/SKILL.md) builds the script that does or proves the work, so a reviewer can rerun it.
|
|
42
|
+
|
|
43
|
+
The architecture principles decide where state, validation, and compatibility live:
|
|
44
|
+
|
|
45
|
+
- [Model the Domain](../../skills/principle-model-the-domain/SKILL.md) encodes repeated rules in one structure, not scattered conditionals.
|
|
46
|
+
- [Boundary Discipline](../../skills/principle-boundary-discipline/SKILL.md) validates at the boundary and trusts internal types.
|
|
47
|
+
- [Type System Discipline](../../skills/principle-type-system-discipline/SKILL.md) makes illegal states unrepresentable.
|
|
48
|
+
- [Make Operations Idempotent](../../skills/principle-make-operations-idempotent/SKILL.md) converges retries on the same end state.
|
|
49
|
+
- [Migrate Callers Then Delete Legacy APIs](../../skills/principle-migrate-callers-then-delete-legacy-apis/SKILL.md) migrates and deletes in one wave.
|
|
50
|
+
- [Separate Before Serializing Shared State](../../skills/principle-separate-before-serializing-shared-state/SKILL.md) removes the sharing before adding coordination.
|
|
51
|
+
|
|
52
|
+
The verification principles define what counts as proof:
|
|
53
|
+
|
|
54
|
+
- [Prove It Works](../../skills/principle-prove-it-works/SKILL.md) verifies the real artifact, not a proxy.
|
|
55
|
+
- [Fix Root Causes](../../skills/principle-fix-root-causes/SKILL.md) reproduces and traces to the cause before changing code.
|
|
56
|
+
- [Sequence Work into Verifiable Units](../../skills/principle-sequence-verifiable-units/SKILL.md) ends each small unit in a check before starting the next.
|
|
57
|
+
|
|
58
|
+
The delegation principles keep parallel work sane:
|
|
59
|
+
|
|
60
|
+
- [Guard the Context Window](../../skills/principle-guard-the-context-window/SKILL.md) routes bulk reading to subagents and keeps findings in the main chat.
|
|
61
|
+
- [Never Block on the Human](../../skills/principle-never-block-on-the-human/SKILL.md) proceeds on reversible work and presents the result.
|
|
62
|
+
|
|
63
|
+
And one meta principle:
|
|
64
|
+
|
|
65
|
+
- [Encode Lessons in Structure](../../skills/principle-encode-lessons-in-structure/SKILL.md) turns advice you've repeated twice into a lint, check, or script.
|
|
66
|
+
|
|
67
|
+
Don't memorize the list. Skim it now, then come back when you catch the agent doing something a name here would have prevented. That's how the vocabulary sticks.
|
|
68
|
+
|
|
69
|
+
Next: [Make it yours](./09-make-it-yours.md).
|
|
@@ -0,0 +1,67 @@
|
|
|
1
|
+
# Make it yours
|
|
2
|
+
|
|
3
|
+
poteto-mode is one person's style. The machinery underneath, playbooks, routing, model roles, works just as well wearing yours. This page covers generating a personal mode, capturing lessons from a session, authoring a focused skill, and testing a skill change before you trust it.
|
|
4
|
+
|
|
5
|
+
## Generate your own mode with `/automate-me`
|
|
6
|
+
|
|
7
|
+
```text
|
|
8
|
+
/automate-me
|
|
9
|
+
```
|
|
10
|
+
|
|
11
|
+
You don't describe your style, because [`/automate-me`](../../skills/automate-me/SKILL.md) reads it out of your history. It mines your recent transcripts in the active workspace for repeated preferences, in how you like replies, delegation, verification, code, prose, and process, then asks you which patterns are really you. It drafts `<your-name>-mode` as a skill through this package's [`create-skill`](../../skills/create-skill/SKILL.md) flow, runs the draft through [`/unslop`](../../skills/unslop/SKILL.md), and opens a PR from a worktree so you review it like any other change.
|
|
12
|
+
|
|
13
|
+
Run it again whenever your habits drift:
|
|
14
|
+
|
|
15
|
+
```text
|
|
16
|
+
/automate-me update my mode skill with everything since its last edit
|
|
17
|
+
```
|
|
18
|
+
|
|
19
|
+
Update mode mines only the history since the skill last changed. It keeps rules you haven't contradicted, revises the ones with new evidence, and adds sections only for genuinely new patterns.
|
|
20
|
+
|
|
21
|
+
## Capture a session's lessons with `/reflect`
|
|
22
|
+
|
|
23
|
+
Right after a task that taught you something, run:
|
|
24
|
+
|
|
25
|
+
```text
|
|
26
|
+
/reflect that took way too long. capture what we learned so the next run doesn't repeat it.
|
|
27
|
+
```
|
|
28
|
+
|
|
29
|
+
[`/reflect`](../../skills/reflect/SKILL.md) sends the transcript to three parallel reviewers, then a synthesizer sorts the proposals into `Accepted`, `Rejected`, and `Backlog` and waits for your approval before any skill changes. Approve a proposal only if it would change a future decision. One weird session is an anecdote, not a rule.
|
|
30
|
+
|
|
31
|
+
## Author a focused skill
|
|
32
|
+
|
|
33
|
+
When you already know the workflow you want to capture:
|
|
34
|
+
|
|
35
|
+
```text
|
|
36
|
+
/poteto-mode write a skill for verifying database migrations in this repo
|
|
37
|
+
```
|
|
38
|
+
|
|
39
|
+
Writing a skill matches the [Authoring or modifying a skill playbook](../../skills/poteto-mode/playbooks/authoring-a-skill.md), which routes through this package's [`create-skill`](../../skills/create-skill/SKILL.md) skill, validates the frontmatter and links, and ships the result through the Opening a PR playbook. Agent-facing prose has a higher bar than human prose, because an unhelpful sentence becomes an instruction some future agent follows. Let the playbook hold that bar rather than writing a `SKILL.md` freehand.
|
|
40
|
+
|
|
41
|
+
One special case has its own generator. A skill that must drive your app and prove behavior is a verification skill, so use [`/create-verification-skill`](../../skills/create-verification-skill/SKILL.md) and [`/maintain-verification-skill`](../../skills/maintain-verification-skill/SKILL.md) instead. [Verify and ship](./06-verify-and-ship.md#create-a-project-verification-skill) covers both.
|
|
42
|
+
|
|
43
|
+
## Write docs to a standard with `/technical-writing`
|
|
44
|
+
|
|
45
|
+
Skills aren't the only prose you ship. For docs, RFCs, readmes, PR descriptions, and commit messages:
|
|
46
|
+
|
|
47
|
+
```text
|
|
48
|
+
/technical-writing review the readme changes
|
|
49
|
+
```
|
|
50
|
+
|
|
51
|
+
[`/technical-writing`](../../skills/technical-writing/SKILL.md) applies a layered standard with one goal, prose a tired engineer understands on the first read. It picks the document's mode first (tutorial, how-to, reference, or explanation), then works sentence by sentence: who does what, one thought per sentence, nothing readable two ways. Use it to review what you or an agent just wrote, or name it up front when you ask for a doc.
|
|
52
|
+
|
|
53
|
+
## Test a skill change blind
|
|
54
|
+
|
|
55
|
+
A skill edit affects every future session, so test it like the experiment it is:
|
|
56
|
+
|
|
57
|
+
```text
|
|
58
|
+
/poteto-mode run the eval playbook on this skill change. same task for both variants, candidates stay blind.
|
|
59
|
+
```
|
|
60
|
+
|
|
61
|
+
The [Eval playbook](../../skills/poteto-mode/playbooks/eval.md) is built around one failure mode, the observer effect. An agent that knows it's being evaluated behaves differently. So candidate agents get an organic-looking task in sanitized directories, never the words "eval" or "candidate", and never each other's existence. One judge scores all outputs under neutral labels, and chain-following gets graded from which files each candidate actually read, not from what it claims.
|
|
62
|
+
|
|
63
|
+
Read every output yourself before accepting the verdict. If you disagree with the judge, suspect the rubric before you suspect your judgment.
|
|
64
|
+
|
|
65
|
+
**Pitfall:** don't edit a skill mid-task because it's misbehaving. Fix it in its own PR and keep the task moving. A skill edit that ships tangled into feature work is invisible to review and impossible to evaluate.
|
|
66
|
+
|
|
67
|
+
Next: [Recipes and pitfalls](./10-recipes-and-pitfalls.md).
|
|
@@ -0,0 +1,94 @@
|
|
|
1
|
+
# Recipes and pitfalls
|
|
2
|
+
|
|
3
|
+
Prompts worth copying, then the mistakes everyone makes once. Swap in your own paths and finish conditions. The recipes are deliberately informal. That's how they get typed in practice, and the skills read intent fine.
|
|
4
|
+
|
|
5
|
+

|
|
6
|
+
|
|
7
|
+
## Understand an unfamiliar subsystem
|
|
8
|
+
|
|
9
|
+
```text
|
|
10
|
+
use /how first to understand how this initialization works. then use /why to figure out why it broke recently.
|
|
11
|
+
```
|
|
12
|
+
|
|
13
|
+
Mechanics first, history second. Each skill's report tells you which sources it searched, so you know what the answer is grounded in.
|
|
14
|
+
|
|
15
|
+
## Get a second opinion on a design
|
|
16
|
+
|
|
17
|
+
```text
|
|
18
|
+
ask /arena for a second opinion on this thread and our approach
|
|
19
|
+
```
|
|
20
|
+
|
|
21
|
+
Your current design becomes one candidate among several, and the synthesis tells you whether the panel found something better or confirmed what you had. Cheap insurance before a costly commitment.
|
|
22
|
+
|
|
23
|
+
## Check independent slices in parallel
|
|
24
|
+
|
|
25
|
+
```text
|
|
26
|
+
/swarm check every package under packages/ against its check.sh. one worker per package. one report.
|
|
27
|
+
```
|
|
28
|
+
|
|
29
|
+
Each worker owns one package. The parent waits for every slice and returns one `PASS`, `ISSUES`, or `BLOCKED` report instead of raw worker dumps.
|
|
30
|
+
|
|
31
|
+
## Review a branch skeptically
|
|
32
|
+
|
|
33
|
+
```text
|
|
34
|
+
/interrogate the whole branch, but skeptically. don't change anything yet. no nitpicks unless it's an actual bug or regression in behavior.
|
|
35
|
+
```
|
|
36
|
+
|
|
37
|
+
The qualifiers do real work. "don't change anything yet" keeps it read-only, and the nitpick rule pre-filters the noise so `Act on` findings are worth your time.
|
|
38
|
+
|
|
39
|
+
## Fix a bug through a failing test
|
|
40
|
+
|
|
41
|
+
```text
|
|
42
|
+
/poteto-mode repro the duplicate write first. if there's a cheap test path, /tdd it. then fix and rerun.
|
|
43
|
+
```
|
|
44
|
+
|
|
45
|
+
"if there's a cheap test path" matters. Forcing a test through brittle mocks proves less than running the real command, and the playbook is allowed to say so.
|
|
46
|
+
|
|
47
|
+
## Keep a run honest while you're away
|
|
48
|
+
|
|
49
|
+
```text
|
|
50
|
+
im going to bed, keep going autonomously until every fixture passes. do not stop. keep a decision log i can audit in the morning.
|
|
51
|
+
```
|
|
52
|
+
|
|
53
|
+
The full contract is on the [overnight page](./07-overnight.md). The short form works once the task and finish condition are already in the conversation.
|
|
54
|
+
|
|
55
|
+
## Redirect a drifting run
|
|
56
|
+
|
|
57
|
+
Steering prompts are one line:
|
|
58
|
+
|
|
59
|
+
```text
|
|
60
|
+
i said the goal is to repro. i did not ask for a fix yet.
|
|
61
|
+
```
|
|
62
|
+
|
|
63
|
+
```text
|
|
64
|
+
apply prove it works. show me the real output, not the build log.
|
|
65
|
+
```
|
|
66
|
+
|
|
67
|
+
```text
|
|
68
|
+
/unslop that, no emdashes
|
|
69
|
+
```
|
|
70
|
+
|
|
71
|
+
You rarely need more words. You need the right name, and [the principles page](./08-principles.md) is the vocabulary.
|
|
72
|
+
|
|
73
|
+
## Get the reply in plain words
|
|
74
|
+
|
|
75
|
+
```text
|
|
76
|
+
/bro
|
|
77
|
+
```
|
|
78
|
+
|
|
79
|
+
That's the whole prompt. [`/bro`](../../skills/bro/SKILL.md) restates the last message like one human talking to another, no jargon, shorter. Use it when a reply is technically thorough and you still don't know what it said.
|
|
80
|
+
|
|
81
|
+
## The pitfalls
|
|
82
|
+
|
|
83
|
+
- **Enumerating skills in the prompt.** "use /how then /architect then /arena" reorders steps the playbook already sequences. State the goal and constraints. Name a skill only to override a default.
|
|
84
|
+
- **A vague finish condition.** "make it better" gives `/loop` nothing to check. Give a command or artifact that can pass or fail.
|
|
85
|
+
- **Parallel agents in one worktree.** They overwrite each other and the diff becomes archaeology. Say "own worktree per attempt" and the isolation is free.
|
|
86
|
+
- **Using `/arena` for coverage.** `/arena` repeats one design or code brief, then picks a base and grafts the best parts. `/swarm` partitions slices or declared race arms and aggregates one report.
|
|
87
|
+
- **Accepting every review comment.** Bots and humans both file real catches and noise in one list. `/interrogate` sorts findings into act-on and dismissed buckets with reasons, and you can override either way.
|
|
88
|
+
- **Treating `auto` as a model slug.** `auto` and `inherit-parent` mean "omit the model field so the subagent inherits the parent chat model." [Setup](./01-setup.md) covers the roles.
|
|
89
|
+
- **Reporting success off a green build.** A build proves it compiles. Ask for the real command, flow, stored value, or profile, and expect the evidence in the reply.
|
|
90
|
+
- **Writing a `SKILL.md` freehand.** Route it through the [Authoring or modifying a skill playbook](../../skills/poteto-mode/playbooks/authoring-a-skill.md) so validation and review happen.
|
|
91
|
+
|
|
92
|
+
That's the guide. If you skipped ahead, go back to [setup](./01-setup.md) and run one real task. The habits stick from use, not from reading.
|
|
93
|
+
|
|
94
|
+
Back to the [guide index](./README.md).
|
|
@@ -0,0 +1,30 @@
|
|
|
1
|
+
# The pstack guide
|
|
2
|
+
|
|
3
|
+
pstack works best when you stop micromanaging the agent. You describe what you want and how you'll know it's done. `/poteto-mode` picks the playbook, runs the other skills as the steps need them, and shows you the evidence. This guide teaches that habit with realistic prompts.
|
|
4
|
+
|
|
5
|
+
Here's what you'll learn:
|
|
6
|
+
|
|
7
|
+
1. [Set up pstack](./01-setup.md). Install the plugin and pick your models.
|
|
8
|
+
2. [Route work through `/poteto-mode`](./02-poteto-mode.md). Give it a goal and watch it pick a playbook.
|
|
9
|
+
3. [Understand the code](./03-understand.md). `/how`, `/why`, `/teach`, and `/recall` before you edit anything.
|
|
10
|
+
4. [Design the change](./04-design.md). `/architect`, `/arena`, `/swarm`, and `/interrogate` before code locks in a shape.
|
|
11
|
+
5. [Build and clean the change](./05-build-and-clean.md). The build playbooks, `/tdd`, `/unslop`, and `/no-comments`.
|
|
12
|
+
6. [Verify and ship](./06-verify-and-ship.md). Prove behavior on the real app, then open a focused PR and drive it to merged.
|
|
13
|
+
7. [Run work while you sleep](./07-overnight.md). An overnight contract, a decision log you can audit, and the playbooks that scale past one agent.
|
|
14
|
+
8. [Steer with principle names](./08-principles.md). The 21 names that redirect an agent mid-task.
|
|
15
|
+
9. [Make it yours](./09-make-it-yours.md). Your own mode, plus how to test a skill change.
|
|
16
|
+
10. [Recipes and pitfalls](./10-recipes-and-pitfalls.md). Prompts to copy and mistakes to skip.
|
|
17
|
+
|
|
18
|
+
Read the pages in order the first time. After that, each page stands alone.
|
|
19
|
+
|
|
20
|
+
## If you only remember one thing
|
|
21
|
+
|
|
22
|
+
Give the agent a goal and a way to check it, in your own words:
|
|
23
|
+
|
|
24
|
+
```text
|
|
25
|
+
/poteto-mode the export writes duplicate rows when a retry lands mid-run. repro first, then fix and verify.
|
|
26
|
+
```
|
|
27
|
+
|
|
28
|
+
You don't need to name a playbook or list skills. "repro first" and a checkable outcome are all the routing signal `/poteto-mode` needs. It matches the Bug fix playbook, copies the steps into a todo list, and calls the right skills as each step fires.
|
|
29
|
+
|
|
30
|
+
Next: [Set up pstack](./01-setup.md).
|
|
Binary file
|
|
Binary file
|
|
Binary file
|
|
Binary file
|
|
Binary file
|
|
Binary file
|