Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
26 changes: 13 additions & 13 deletions FORK-SYNC-LOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -8,27 +8,27 @@ One table per sync. One row per upstream commit that touches `pstack/` or the co
|---|---|---|---|---|
| `ea32d95` | feat(pstack): show /ketchup decisions as before/after visuals (#570) | adapt (planned) | D | /ketchup visuals, rendered with T3 html_render |
| `08bd59b` | refactor(pstack): cut unneeded sections from seven skills (#571) | adapt (planned) | D | section cuts, kept where fork text is T3-specific |
| `de2dba6` | fix(pstack): rename Comment Sicko agent id so Grok can spawn it (#486) | take (planned) | B | agent id rename, harmless under delegate_task |
| `87c8103` | fix(pstack): respect fenced code blocks in plan checks (#536) | adapt (planned) | B | plan checker fix, keep the origin/lim re-read rule (Trunk row) |
| `ff8f83d` | fix(watch-pr): paginate review threads instead of reading only the first 100 (#484) | take (planned) | B | watch-pr pagination bug, babysit still uses watch-pr on GitHub |
| `bc697d0` | fix(pstack): drop "Must always apply." from unslop description (#572) | take (planned) | B | unslop description fix |
| `cf9a111` | fix(pstack): worktree-audit checks MERGED against the default branch, not origin/main (#574) | adapt (planned) | B | worktree audit uses the default branch (Trunk row) |
| `2bd5dd4` | fix(pstack): make the /poteto-mode chat the runner, poteto-agent a delegate (#575) | adapt (planned) | B | the chat runs the playbook, keep absolute install paths (Install row) |
| `de2dba6` | fix(pstack): rename Comment Sicko agent id so Grok can spawn it (#486) | take | B | agent file and README renamed, no-comments already spawns by file |
| `87c8103` | fix(pstack): respect fenced code blocks in plan checks (#536) | adapt | B | test fixture re-reads origin/lim, not origin/main (Trunk row). The drift check caught it |
| `ff8f83d` | fix(watch-pr): paginate review threads instead of reading only the first 100 (#484) | take | B | cherry-picked unchanged |
| `bc697d0` | fix(pstack): drop "Must always apply." from unslop description (#572) | take | B | applied by hand, the fork keeps its named-only sentence |
| `cf9a111` | fix(pstack): worktree-audit checks MERGED against the default branch, not origin/main (#574) | adapt | B | merged with --threads. The base comes from GitHub's default branch, then origin/HEAD, because origin/HEAD here still says main. Upstream's origin/main and origin/master guesses are removed on purpose, so with neither lookup available the script stops and asks for -b (Trunk row) |
| `2bd5dd4` | fix(pstack): make the /poteto-mode chat the runner, poteto-agent a delegate (#575) | adapt | B | runner and delegate wording in poteto-mode, poteto-agent and README, with delegate_task and absolute paths (Subagents and Install rows) |
| `e5a02f8` | feat(pstack): add Agent Plugins v1 root manifest (#576) | skip (planned) | | Cursor marketplace manifest, the fork installs per user (Install row) |
| `c49b37a` | fix(pstack): create-verification-skill readiness means the app is usable (#573) | take (planned) | B | verification-skill readiness fix |
| `c49b37a` | fix(pstack): create-verification-skill readiness means the app is usable (#573) | take | B | applied by hand onto the fork's .agents/skills paths |
| `1b6d44f` | chore(pstack): bump to 0.15.20 (#581) | skip (planned) | | version bump, versions are not used by the per-user install |
| `364a77e` | fix(pstack): tell agents where bundled leaf skills live (#577) | adapt (planned) | B | superseded by the fork's absolute paths (Install row), take any remaining wording |
| `364a77e` | fix(pstack): tell agents where bundled leaf skills live (#577) | adapt | B | leaf paths given as ~/.agents/skills/<name>/SKILL.md instead of ../<name> (Install row) |
| `997ffc7` | chore(pstack): bump to 0.15.21 (#584) | skip (planned) | | version bump |
| `b93e811` | fix(pstack): let poteto-agent find poteto-mode, drop ignored frontmatter, document the / menu (#597) | adapt (planned) | B | wording taken, path lookup superseded by absolute paths (Install row) |
| `7d8d909` | feat(pstack): add /in-your-own-words to play back the goal before work (#602) | adapt (planned) | B | new skill /in-your-own-words, made visible and named-only (Skill visibility row) |
| `b93e811` | fix(pstack): let poteto-agent find poteto-mode, drop ignored frontmatter, document the / menu (#597) | adapt | B | poteto-agent wording taken. Plugin-folder search skipped (Install row). The fork never had the mode and reminder keys. The slash-menu README line is Cursor-only |
| `7d8d909` | feat(pstack): add /in-your-own-words to play back the goal before work (#602) | adapt | B | visible and named-only (Skill visibility row) |
| `d00ba6e` | feat(pstack): shorten /ketchup replies and build them on real visuals (#595) | adapt (planned) | D | /ketchup rewrite, T3 visuals |
| `36cecbf` | feat(pstack): propose a cheap always-on signal after a deep debugging dig (#604) | take (planned) | B | debugging signal suggestion |
| `36cecbf` | feat(pstack): propose a cheap always-on signal after a deep debugging dig (#604) | take | B | cherry-picked unchanged |
| `3177dab` | chore(pstack): bump to 0.15.22 (#605) | skip (planned) | | version bump |
| `dbf4981` | refactor(pstack): reword /in-your-own-words around goals and the problem (#606) | adapt (planned) | B | /in-your-own-words rewording |
| `dbf4981` | refactor(pstack): reword /in-your-own-words around goals and the problem (#606) | adapt | B | taken with 7d8d909, version bump left out |
| `c86f349` | refactor(pstack): make /ketchup read like /bro in 150 words (#609) | adapt (planned) | D | /ketchup rewrite |
| `ce649c0` | feat(pstack): match subagent effort to the job, drop Graphite from orchestrate, and cut playbooks to principles (#613) | adapt (planned) | C | effort rule as lower-only, no Claude fast (Speed row), Graphite out, swarm cadence, shorter playbooks with T3 steps kept |
| `8043881` | pstack: autopilot loops catch the operator up with /ketchup (#616) | adapt (planned) | C | autopilot loops use /ketchup |
| `79afd75` | feat(pstack): add /sharpen (#615) | adapt (planned) | B | new skill /sharpen, made visible and named-only (Skill visibility row) |
| `79afd75` | feat(pstack): add /sharpen (#615) | adapt | B | visible and named-only (Skill visibility row) |
| `1e5c90a` | chore(pstack): bump to 0.15.24 (#617) | skip (planned) | | version bump |
| `afd51cf` | feat(pstack): have /ketchup explain changes with screenshots, videos, and diagrams (#628) | adapt (planned) | D | /ketchup screenshots and videos via T3 tools |
| `6ce45c5` | chore(pstack): bump to 0.15.25 (#614) | skip (planned) | | version bump |
Expand Down
8 changes: 5 additions & 3 deletions pstack/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -111,6 +111,8 @@ start each task thread with [`/poteto-mode`](./skills/poteto-mode/SKILL.md). it
|---|---|
| [`/poteto-mode`](./skills/poteto-mode/SKILL.md) | default entry point for any non-trivial task. |
| [`/poteto-help`](./skills/poteto-help/SKILL.md) | you're new to pstack, or unsure which skill, playbook, or principle fits. finds out what you're trying to do, answers that part, and hands you a prompt to type. runs only when you type `/poteto-help`. |
| [`/in-your-own-words`](./skills/in-your-own-words/SKILL.md) | you want the agent to play back your goal and the problem before it starts. runs only when you type `/in-your-own-words`. |
| [`/sharpen`](./skills/sharpen/SKILL.md) | you want a task approached the way a top expert would, aimed at what you're really after, without overspecifying it or deciding your choices for you. |
| [`/how`](./skills/how/SKILL.md) | you want a walkthrough of how a subsystem works. |
| [`/why`](./skills/why/SKILL.md) | you want to know why something was built this way. discovers available MCPs at run time and queries each evidence category in parallel (source control, issue tracker, long-form docs, real-time chat, infra observability, error tracking, analytics warehouse). |
| [`/recall`](./skills/recall/SKILL.md) | you're starting or resuming work and want your recent context on a topic rebuilt from your own chat history and the shared record, handed back as a tight current-state brief. |
Expand Down Expand Up @@ -191,11 +193,11 @@ help: /poteto-help which skill should i use to review this branch?

## the `poteto-agent` and Comment Sicko subagents

pstack also ships a subagent that runs my style end to end. spawn it from a parent agent via [`subagent_type: "poteto-agent"`](./agents/poteto-agent.md). it reads `poteto-mode` in full, including its inline principles index, before doing any work. substituting `generalPurpose` skips that read and drifts.
[`/poteto-mode`](./skills/poteto-mode/SKILL.md) runs in the chat that receives it. that chat owns the playbook, the todo list, and every `delegate_task` spawn.

[`/poteto-mode`](./skills/poteto-mode/SKILL.md) and [`subagent_type: "poteto-agent"`](./agents/poteto-agent.md) route through the same wrapper.
pstack also ships [`poteto-agent`](./agents/poteto-agent.md) as the wrapper for delegates spawned during a run. a delegate's brief tells it to read `~/.agents/skills/poteto-mode/SKILL.md` in full, including its inline principles index, before any work. do not spawn `poteto-agent` to run the playbook itself.

pstack also ships [Comment Sicko](./agents/comment-sicko.md), a read-only comment reviewer available as `subagent_type: "Comment Sicko"`. usually invoke it through [`/no-comments`](./skills/no-comments/SKILL.md), not directly.
pstack also ships [Comment Sicko](./agents/comment-sicko.md), a read-only comment reviewer spawned as a `delegate_task` child. usually invoke it through [`/no-comments`](./skills/no-comments/SKILL.md), not directly.

## principles

Expand Down
2 changes: 1 addition & 1 deletion pstack/agents/comment-sicko.md
Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@
---
name: Comment Sicko
name: comment-sicko
description: A deranged comment-hater that savors deletion and condemns workaround code.
---

Expand Down
4 changes: 2 additions & 2 deletions pstack/agents/poteto-agent.md
Original file line number Diff line number Diff line change
@@ -1,8 +1,8 @@
---
name: poteto-agent
description: Routing target for `/poteto-mode` and any request for poteto's style. Spawn a fresh `poteto-agent` for each new task, and resume one only in the strict cases that poteto-mode's Subagents section names. Reads the `poteto-mode` skill's `SKILL.md` in full before any work, including its inline Principles index. Substituting `generalPurpose` skips that read and drifts.
description: Delegate wrapper for code-writing and helper tasks spawned as `delegate_task` children during a `/poteto-mode` run. Not the runner for `/poteto-mode` itself. Spawn a fresh `poteto-agent` for each new task, and resume one only in the strict cases that poteto-mode's Subagents section names. Reads `~/.agents/skills/poteto-mode/SKILL.md` in full before any work, including its inline Principles index. A delegate that skips that read drifts.
---

# Poteto subagent

You are operating as poteto-mode's full agent style. Read the `poteto-mode` skill's `SKILL.md` in full before doing any work, including its inline Principles index. Navigate to a leaf `principle-*` skill whenever you apply that principle.
You are operating as poteto-mode's full agent style. The chat that receives `/poteto-mode` owns the playbook, the todo list, and every `delegate_task` spawn. You are one of its delegates. Read `~/.agents/skills/poteto-mode/SKILL.md` in full before doing any work, including its inline Principles index. Every skill it names is at `~/.agents/skills/<name>/SKILL.md`. Read a leaf `principle-*` skill whenever you apply that principle.
6 changes: 3 additions & 3 deletions pstack/skills/create-verification-skill/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -23,7 +23,7 @@ If the checkout doesn't build or start as-is, fix that first (or report it preci

Write `.agents/skills/verify-<app>/SKILL.md` with YAML frontmatter (`name: verify-<app>` and a `description` that names the app, the surface, and when to reach for it — without frontmatter the skill never registers) and these sections, each grounded in what the interview actually found (no placeholders left):

- **Launch:** the exact command that starts the app for verification, and how to tell it's ready (a log line, a port answering, a prompt). Include teardown. For a short-lived CLI or TUI there is no server to keep alive: launch means build the binary (or install deps) once, then start each drive in its own isolated PTY or tmux session.
- **Launch:** the exact command that starts the app for verification, and how to tell it's ready (a log line, a prompt). Launch must reach a usable state from an empty data dir, including any migrations and seed data. Ready means usable, not just that a process answers. A database health check can pass while its init scripts are still running. Include teardown. For a short-lived CLI or TUI there is no server to keep alive: launch means build the binary (or install deps) once, then start each drive in its own isolated PTY or tmux session.
- **Doctor:** one read-only check that answers "is this instance worth driving?" — process up, right version/build, port owned by us, auth valid. An agent runs this first whenever anything looks off.
- **Drive:** the harness recipe with real selectors/commands from this repo, not examples. Prefer stable handles (ARIA labels, data attributes, prompt strings, route paths) over coordinates and tab order.
- **Evidence:** what to capture for a proof and where it goes. State the proof standards: exercise the real user path, not internal setters or test-only endpoints; capture the action and the resulting state, not just the final screen; verify side effects (files written, rows inserted, messages sent) alongside what's visible; mocks only where a production boundary already isolates the external system. When the safe path is a dry-run or test mode, verify what it actually skips by observing (files, network, git refs) rather than trusting its name: some dry-runs still touch the network or open a browser.
Expand All @@ -32,11 +32,11 @@ Write `.agents/skills/verify-<app>/SKILL.md` with YAML frontmatter (`name: verif

## 3. Seed the feature map

Create `.agents/skills/verify-<app>/features/README.md` plus one file per user-facing feature you can identify (aim for the top 3-5 to start, from routes, commands, menus, or docs). Follow the shape in [`references/feature-map-example/`](references/feature-map-example/), with a README index and one file per feature. Each file answers, from the user's point of view: what the feature is, how to reach it, how to drive it with the harness, and what observable end state proves it works. The four H2s are `Sub-features`, `How to get to it (user POV)`, `Driving it with <harness>`, and `Gotchas`. The map is the repo's maintained verification source; a proof that drives one convenient entry point is incomplete when the map lists others.
Create `.agents/skills/verify-<app>/features/README.md` plus one file per user-facing feature you can identify (aim for the top 3-5 to start, from routes, commands, menus, or docs). Follow the shape in [`references/feature-map-example/`](references/feature-map-example/), with a README index and one file per feature. Each file answers, from the user's point of view: what the feature is, how to reach it, how to drive it with the harness, and what observable end state proves it works. The four H2s are `Sub-features`, `How to get to it (user POV)`, `Driving it with <harness>`, and `Gotchas`. If the seed data lacks a precondition that a journey needs, the journey reports a failure and the reason goes in that feature's `Gotchas`. Never weaken the journey to make it pass. The map is the repo's maintained verification source; a proof that drives one convenient entry point is incomplete when the map lists others.

## 4. Prove the generated skill before handing it over

Run its own instructions end to end once: launch, doctor, drive ONE mapped feature (one is enough; the map exists so later runs can cover the rest), capture evidence, clean up. After cleanup, confirm the evidence still exists at the named location — a cleanup that eats the proof fails this step. Fix what fails, and run the generated cleanup after every failed iteration too, so broken attempts don't strand processes and ports. A generated skill that was never executed is a draft, not a deliverable.
Run its own instructions end to end once: launch, doctor, drive ONE mapped feature (one is enough; the map exists so later runs can cover the rest), capture evidence, clean up. After cleanup, confirm the evidence still exists at the named location — a cleanup that eats the proof fails this step. Fix what fails, and run the generated cleanup after every failed iteration too, so broken attempts don't strand processes and ports. A generated skill that was never executed is a draft, not a deliverable. If you proved it in a stand-in for the real target (a container in place of a fresh VM, a local stack in place of a remote one), list every setup step the stand-in did that the target will not. Those steps stay unverified until a run on the real target covers them.

## 5. Offer the maintenance loop

Expand Down
6 changes: 6 additions & 0 deletions pstack/skills/in-your-own-words/SKILL.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,6 @@
---
name: in-your-own-words
description: "Restate in your own words what you think the user's goals are and what problem they're trying to solve. Use for /in-your-own-words. Use only when the user or another skill names it."
---

Restate in your own words what you think the user's goals are and what problem they're trying to solve.
2 changes: 2 additions & 0 deletions pstack/skills/poteto-help/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -58,6 +58,8 @@ The default answer is `/poteto-mode`, which runs most of the others when its ste
| The user wants to | Skill |
|---|---|
| Do any non-trivial task with rigor | [`/poteto-mode`](../poteto-mode/SKILL.md) |
| Check that the agent understood their goal and the problem before it starts | [`/in-your-own-words`](../in-your-own-words/SKILL.md) |
| Aim a task higher before starting: more expert, more outcome-focused, not overspecified | [`/sharpen`](../sharpen/SKILL.md) |
| Know how code works now, or where new code should live | [`/how`](../how/SKILL.md) |
| Know why code is shaped this way, or where a number came from | [`/why`](../why/SKILL.md) |
| Understand a change or subsystem, explained plainly | [`/teach`](../teach/SKILL.md) |
Expand Down
2 changes: 2 additions & 0 deletions pstack/skills/poteto-help/references/recipes.md
Original file line number Diff line number Diff line change
Expand Up @@ -5,6 +5,8 @@ Swap in the real paths, skills, and done checks. Informal wording works.
## Understand

- `/poteto-mode read <thread>. restate the underlying issue in your own words, in plain english.`
- `/in-your-own-words <long or messy ask>`
- `/sharpen <your task>`
- `/poteto-mode investigate why <symptom>. give me what we know, what data you used, and your best hypotheses. don't change any code yet.`
- `use /how to understand <subsystem>. then use /why to find out why it broke recently.`
- `/recall my work on <topic> from last week, then read <issue>.`
Expand Down
Loading