diff --git a/docs/guide/02-poteto-mode.md b/docs/guide/02-poteto-mode.md index 52d5a3b..6051f7a 100644 --- a/docs/guide/02-poteto-mode.md +++ b/docs/guide/02-poteto-mode.md @@ -1,8 +1,5 @@ # Route work through `/poteto-mode` -> Codex port: use `$skill-name` to invoke skills. The [Codex adapter](../harness/codex.md) translates the upstream tool names, model defaults, history, and automation instructions below. Follow the [README](../../README.md) for installation; upstream UI gestures and external service availability depend on the host. - - `/poteto-mode` is the front door. You give it a goal, it matches one of twenty-three playbooks, copies that playbook's steps into the todo list, and calls the other skills as the steps need them. In this page you learn what a good prompt looks like, and how little of one you actually need. ![A dispatcher pulls a switch lever to route robots on rail handcars toward lit gates, under a /poteto-mode departure board listing BUG FIX, FEATURE, and INVESTIGATION.](./images/router.jpg) diff --git a/docs/guide/03-understand.md b/docs/guide/03-understand.md index 228b3d6..1398d98 100644 --- a/docs/guide/03-understand.md +++ b/docs/guide/03-understand.md @@ -1,8 +1,5 @@ # Understand the code before changing it -> Codex port: use `$skill-name` to invoke skills. The [Codex adapter](../harness/codex.md) translates the upstream tool names, model defaults, history, and automation instructions below. Follow the [README](../../README.md) for installation; upstream UI gestures and external service availability depend on the host. - - Editing code you don't understand is how subtle regressions ship, and that's as true for the agent as for you. Agents usually fail in one of two ways. They misread what you want, or they don't have the context to do the work right. [What goes in a prompt](./02-poteto-mode.md#what-goes-in-a-prompt) handles the first. This page handles the second. pstack gives you four ways in. `/how` explains what the code does now. `/why` digs up the reasons it's shaped that way. `/teach` blends both into one explanation. `/recall` rebuilds your own recent context on a topic. Each one also makes the agent explain itself in words you can check. That's how you supervise an agent that may know the code better than you do. diff --git a/docs/guide/04-design.md b/docs/guide/04-design.md index a2eb511..ddba23c 100644 --- a/docs/guide/04-design.md +++ b/docs/guide/04-design.md @@ -1,8 +1,5 @@ # Design before you write code -> Codex port: use `$skill-name` to invoke skills. The [Codex adapter](../harness/codex.md) translates the upstream tool names, model defaults, history, and automation instructions below. Follow the [README](../../README.md) for installation; upstream UI gestures and external service availability depend on the host. - - One attempt at a hard design locks in the first shape the model thought of. `/architect` settles types and boundaries before implementation. `/arena` runs several attempts at the same brief and merges the best parts. `/interrogate` has other models try to break the result. When the job is coverage rather than design synthesis, `/swarm` fans out slices or races and aggregates their results. The two most common design mistakes are taking the agent's first design and polishing a plan that no code has tested. This page fixes both. You plan through code. Prototypes answer the open questions, a README or tutorial sets the target, and the written plan comes last. diff --git a/docs/guide/05-build-and-clean.md b/docs/guide/05-build-and-clean.md index 2616b1f..a5de632 100644 --- a/docs/guide/05-build-and-clean.md +++ b/docs/guide/05-build-and-clean.md @@ -1,8 +1,5 @@ # Build the change and clean the diff -> Codex port: use `$skill-name` to invoke skills. The [Codex adapter](../harness/codex.md) translates the upstream tool names, model defaults, history, and automation instructions below. Follow the [README](../../README.md) for installation; upstream UI gestures and external service availability depend on the host. - - The build playbooks share one discipline. Say what you observed, and let the playbook demand the evidence. This page shows what to put in the prompt for each common build task, then the cleanup habit that keeps diffs reviewable. ## Prompt each build playbook with what you know diff --git a/docs/guide/06-verify-and-ship.md b/docs/guide/06-verify-and-ship.md index 629f6f3..738154b 100644 --- a/docs/guide/06-verify-and-ship.md +++ b/docs/guide/06-verify-and-ship.md @@ -1,8 +1,5 @@ # Verify the result and open a PR -> Codex port: use `$skill-name` to invoke skills. The [Codex adapter](../harness/codex.md) translates the upstream tool names, model defaults, history, and automation instructions below. Follow the [README](../../README.md) for installation; upstream UI gestures and external service availability depend on the host. - - "It compiles" is not evidence. The [Prove It Works principle](../../.agents/skills/principle-prove-it-works/SKILL.md) makes the agent check the real artifact before it reports success, and your job is to make "the real artifact" checkable. This page covers stating a finish condition, vetting a measured number, generating a verification skill for your app, formally verifying a property tests rarely reach, opening the PR, and driving it to merged. Verification is the slowest step in most agent work, because it's the step that usually waits on a human. Make the agent able to do it, and you stop being the bottleneck. Skip it, and running more agents only gets you more unchecked work to review. diff --git a/docs/guide/07-overnight.md b/docs/guide/07-overnight.md index 5b36b8b..7bbfd1a 100644 --- a/docs/guide/07-overnight.md +++ b/docs/guide/07-overnight.md @@ -1,8 +1,5 @@ # Run work while you sleep -> Codex port: use `$skill-name` to invoke skills. The [Codex adapter](../harness/codex.md) translates the upstream tool names, model defaults, history, and automation instructions below. Follow the [README](../../README.md) for installation; upstream UI gestures and external service availability depend on the host. - - This is the payoff for everything before it. An agent you can trust to verify its own work is an agent you can leave alone with a hard task. What makes that safe isn't hope. It's a checkable finish condition, an isolated worktree or cloud agent, and a decision log you audit in the morning. ![She waves goodnight from the door while robots keep the factory running, one updating a DECISION LOG wall board under a BUILD LOOP ACTIVE sign.](./images/overnight.jpg) diff --git a/docs/guide/08-principles.md b/docs/guide/08-principles.md index e95d242..4975a0f 100644 --- a/docs/guide/08-principles.md +++ b/docs/guide/08-principles.md @@ -1,8 +1,5 @@ # Steer with principle names -> Codex port: use `$skill-name` to invoke skills. The [Codex adapter](../harness/codex.md) translates the upstream tool names, model defaults, history, and automation instructions below. Follow the [README](../../README.md) for installation; upstream UI gestures and external service availability depend on the host. - - pstack ships 24 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. 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. diff --git a/docs/guide/09-make-it-yours.md b/docs/guide/09-make-it-yours.md index 37f2cc8..8a7fd3b 100644 --- a/docs/guide/09-make-it-yours.md +++ b/docs/guide/09-make-it-yours.md @@ -1,8 +1,5 @@ # Make it yours -> Codex port: use `$skill-name` to invoke skills. The [Codex adapter](../harness/codex.md) translates the upstream tool names, model defaults, history, and automation instructions below. Follow the [README](../../README.md) for installation; upstream UI gestures and external service availability depend on the host. - - poteto-mode is one person's style. The playbooks, routing, and model roles underneath it work just as well with yours. This page covers generating a personal mode, capturing lessons from a session, fixing the repo so agents stop repeating mistakes, authoring a focused skill, and testing a skill change before you trust it. Start smaller than you think. You don't need many skills on day one, or even this whole plugin. Prompt plainly, watch where agents fail, and add a skill or a check when the same failure shows up twice. diff --git a/docs/guide/10-recipes-and-pitfalls.md b/docs/guide/10-recipes-and-pitfalls.md index f6a47a2..fd2d93b 100644 --- a/docs/guide/10-recipes-and-pitfalls.md +++ b/docs/guide/10-recipes-and-pitfalls.md @@ -1,8 +1,5 @@ # Recipes and pitfalls -> Codex port: use `$skill-name` to invoke skills. The [Codex adapter](../harness/codex.md) translates the upstream tool names, model defaults, history, and automation instructions below. Follow the [README](../../README.md) for installation; upstream UI gestures and external service availability depend on the host. - - 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. ![She tastes a finished dish while robots cook from a recipe box, with pinned cards reading /how, /tdd, and /loop above the counter.](./images/recipes.jpg) diff --git a/docs/guide/README.md b/docs/guide/README.md index 150e81e..9ebdd47 100644 --- a/docs/guide/README.md +++ b/docs/guide/README.md @@ -1,8 +1,5 @@ # The pstack guide -> Codex port: use `$skill-name` to invoke skills. The [Codex adapter](../harness/codex.md) translates the upstream tool names, model defaults, history, and automation instructions below. Follow the [README](../../README.md) for installation; upstream UI gestures and external service availability depend on the host. - - 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. Here's what you'll learn: