From 788b7e2a7856224fa53fe4c4215fd5eb28709011 Mon Sep 17 00:00:00 2001 From: alebairos Date: Sun, 2 Aug 2026 01:32:11 -0300 Subject: [PATCH 1/2] Teach poteto-mode to detect and operate a PDCA harness. When OPERATOR.md or HARNESS.md is present, load the repo contract and route delivery through intake/build stations instead of inventing board state. Co-authored-by: Cursor --- pstack/skills/poteto-mode/SKILL.md | 2 ++ .../playbooks/operate-pdca-harness.md | 14 +++++++++ .../poteto-mode/references/pdca-harness.md | 29 +++++++++++++++++++ 3 files changed, 45 insertions(+) create mode 100644 pstack/skills/poteto-mode/playbooks/operate-pdca-harness.md create mode 100644 pstack/skills/poteto-mode/references/pdca-harness.md diff --git a/pstack/skills/poteto-mode/SKILL.md b/pstack/skills/poteto-mode/SKILL.md index b624d80..52b0df6 100644 --- a/pstack/skills/poteto-mode/SKILL.md +++ b/pstack/skills/poteto-mode/SKILL.md @@ -32,6 +32,7 @@ Remaining triggers: - Bugbot or the agentic security review commented → skeptical posture. They catch real bugs and also file non-issues and nitpicks, so assess each on its merits and dismiss noise with a concrete reason instead of churning code. Triage fix / dismiss / ask via the built-in **babysit** skill. - Broken skill mid-task → fix it in its own PR. Don't block. Don't silently work around it. - Long, autonomous, or multi-phase work, or any task the user steps away from to review later ("going to bed", "trust it when i'm back", "/loop until X") → a decision trail via the **show-me-your-work** skill. Commit it when stakes need an auditable record; keep it local otherwise. +- Workspace has a PDCA harness (`docs/OPERATOR.md`, `docs/HARNESS.md`, or `harness/`) → read `references/pdca-harness.md`, then the repo operator contract. You are the preferred Orchestrator. Advance Plan/Do only via `/intake-next` and `/build-next`. Do not invent board state from chat. Do not `/loop /poteto-mode` as a station. Delivery / pre-implementation / validate-upstream asks → playbook **Operate PDCA harness**. ## Principles @@ -132,4 +133,5 @@ A large or cross-cutting effort (a migration across many call sites, an ambitiou - **Session pickup.** Resuming or taking over a prior agent's in-flight work from a transcript, cloud-agent URL, or pushed branch. `playbooks/session-pickup.md`. - **Pause safely.** Suspending in-flight work cleanly so it can be resumed, on an explicit pause, going offline, a Cursor restart, or imminent context compaction. The complement to Session pickup. Full steps: `playbooks/pause-safely.md`. - **Multi-phase or multi-PR plan.** Work that spans phases or stacked PRs. `playbooks/multi-phase-plan.md`. +- **Operate PDCA harness.** Repo has `docs/OPERATOR.md` / `docs/HARNESS.md` / `harness/` and the user wants delivery advanced, validated, or operated. `playbooks/operate-pdca-harness.md`. - **Opening a PR.** Invoked at the end of every other playbook. `playbooks/opening-a-pr.md`. diff --git a/pstack/skills/poteto-mode/playbooks/operate-pdca-harness.md b/pstack/skills/poteto-mode/playbooks/operate-pdca-harness.md new file mode 100644 index 0000000..6a6e474 --- /dev/null +++ b/pstack/skills/poteto-mode/playbooks/operate-pdca-harness.md @@ -0,0 +1,14 @@ +### Operate PDCA harness + +**You are Orchestrator.** The shelf is authority. Load the kit contract; do not invent board state. + +Triggered when the workspace has a PDCA harness (`docs/OPERATOR.md`, `docs/HARNESS.md`, or `harness/`) and the user wants delivery advanced, validated, or explained as an operator. + +1. Read `references/pdca-harness.md`, then `docs/OPERATOR.md` (or `docs/HARNESS.md` / `harness/tree/…` equivalents). +2. Throughput checkpoint stays one line: `throughput checkpoint: n/a, harness operator` unless a Feature/Bug fix playbook also applies to product code. +3. Match the user ask to a station. Plan → `/intake-next`. Pin → `/build-next wi-N`. Do/Check/Act → `/build-next`. Pre-Do validation → intake loop with re-`gate_check` and never pin (text in OPERATOR.md). +4. Run one tick of the matched station skill (or tell the human the exact `/loop` command if they only asked what to run). Spawn Planner / Gate Reviewer / Implementer / Reviewer as `poteto-agent` per the harness roles doc. +5. Emit the tick status line the skill requires. Stop on the published signals. +6. Apply **unslop** to the reply. + +No nested `/loop` from inside a tick. Opening a PR only when a station or product Feature asks for it. diff --git a/pstack/skills/poteto-mode/references/pdca-harness.md b/pstack/skills/poteto-mode/references/pdca-harness.md new file mode 100644 index 0000000..1448701 --- /dev/null +++ b/pstack/skills/poteto-mode/references/pdca-harness.md @@ -0,0 +1,29 @@ +# PDCA harness detection + +When the workspace has a PDCA harness, poteto-mode is the **preferred Orchestrator**. The harness kit owns the protocol. This file does not duplicate it. + +## Detect + +Any of these means a harness is present: + +- `docs/OPERATOR.md` +- `docs/HARNESS.md` +- `harness/tree/docs/OPERATOR.md` or `harness/tree/docs/HARNESS.md` +- `.cursor/skills/intake-next/SKILL.md` and `.cursor/skills/build-next/SKILL.md` + +Prefer `docs/OPERATOR.md` (or the `harness/tree/…` equivalent). Fall back to `docs/HARNESS.md`. + +## Load + +1. Read the operator contract (OPERATOR, else HARNESS). +2. Do not invent Plan/Do board moves from chat. +3. Advance only via station skills: `/intake-next`, `/build-next`, pin `/build-next wi-N`. +4. Before HITL yes, expect `python3 scripts/gate_check.py --gate ` (exit 1 → Planner, exit 2 → Gate Reviewer, exit 0 → human yes/no). +5. Spawn role agents with `subagent_type: "poteto-agent"` per the harness `docs/AGENT-ROLES.md`. +6. Pre-implementation stop is `AWAITING_PIN`. Never pin from intake. Never treat `/loop /poteto-mode` as a station. + +## Route phrases + +If the user asks to run delivery, validate upstream, run until pre-implementation, or check the plan without naming a station, point them at (or run) the Plan loop from OPERATOR.md. For pre-Do re-check, use the validation prompt in OPERATOR.md (re-`gate_check`, never pin, never `/build-next`). + +If only `/poteto-mode` is attached with no station and the request is clearly delivery, load OPERATOR and either run one `/intake-next` tick or name the two loop commands. Do not freestyle a parallel backlog. From 5d72b40e26f395e737120d2b7073a6b211d526c6 Mon Sep 17 00:00:00 2001 From: alebairos Date: Sun, 2 Aug 2026 01:38:09 -0300 Subject: [PATCH 2/2] Map PDCA harness human aliases in poteto detect path. Expand plan/validate/pin/build/status via the repo OPERATOR.md full commands before running. Co-authored-by: Cursor --- .../playbooks/operate-pdca-harness.md | 4 ++-- .../poteto-mode/references/pdca-harness.md | 18 ++++++++++++++++-- 2 files changed, 18 insertions(+), 4 deletions(-) diff --git a/pstack/skills/poteto-mode/playbooks/operate-pdca-harness.md b/pstack/skills/poteto-mode/playbooks/operate-pdca-harness.md index 6a6e474..e9a9f73 100644 --- a/pstack/skills/poteto-mode/playbooks/operate-pdca-harness.md +++ b/pstack/skills/poteto-mode/playbooks/operate-pdca-harness.md @@ -6,8 +6,8 @@ Triggered when the workspace has a PDCA harness (`docs/OPERATOR.md`, `docs/HARNE 1. Read `references/pdca-harness.md`, then `docs/OPERATOR.md` (or `docs/HARNESS.md` / `harness/tree/…` equivalents). 2. Throughput checkpoint stays one line: `throughput checkpoint: n/a, harness operator` unless a Feature/Bug fix playbook also applies to product code. -3. Match the user ask to a station. Plan → `/intake-next`. Pin → `/build-next wi-N`. Do/Check/Act → `/build-next`. Pre-Do validation → intake loop with re-`gate_check` and never pin (text in OPERATOR.md). -4. Run one tick of the matched station skill (or tell the human the exact `/loop` command if they only asked what to run). Spawn Planner / Gate Reviewer / Implementer / Reviewer as `poteto-agent` per the harness roles doc. +3. Match the user ask to an **alias** in `docs/OPERATOR.md` (`plan`, `validate`/`pre-do`, `pin wi-N`, `build`/`do`, `status`). Expand to that file’s **Full commands** block. Echo the expansion in `action:`. +4. Run one tick of the expanded station skill (or print the full `/loop` text if they only asked what to run). Spawn Planner / Gate Reviewer / Implementer / Reviewer as `poteto-agent` per the harness roles doc. 5. Emit the tick status line the skill requires. Stop on the published signals. 6. Apply **unslop** to the reply. diff --git a/pstack/skills/poteto-mode/references/pdca-harness.md b/pstack/skills/poteto-mode/references/pdca-harness.md index 1448701..9f9f295 100644 --- a/pstack/skills/poteto-mode/references/pdca-harness.md +++ b/pstack/skills/poteto-mode/references/pdca-harness.md @@ -22,8 +22,22 @@ Prefer `docs/OPERATOR.md` (or the `harness/tree/…` equivalent). Fall back to ` 5. Spawn role agents with `subagent_type: "poteto-agent"` per the harness `docs/AGENT-ROLES.md`. 6. Pre-implementation stop is `AWAITING_PIN`. Never pin from intake. Never treat `/loop /poteto-mode` as a station. +## Aliases + +If the user says a short name, expand using the **Aliases** table in `docs/OPERATOR.md`, then run the matching **Full commands** block. Echo the expansion in the tick `action:`. + +| Alias | Station | +| --- | --- | +| `plan` / `intake` | Plan loop | +| `validate` / `pre-do` | Pre-Do validation loop | +| `pin wi-N` | `/build-next wi-N` | +| `build` / `do` | Do loop | +| `status` | Read-only shelf report | + +Synonyms (“validate upstream”, “run until pre-implementation”, “advance plan”) use the same rows. Do not invent new Cursor slash skills for aliases. + ## Route phrases -If the user asks to run delivery, validate upstream, run until pre-implementation, or check the plan without naming a station, point them at (or run) the Plan loop from OPERATOR.md. For pre-Do re-check, use the validation prompt in OPERATOR.md (re-`gate_check`, never pin, never `/build-next`). +If the user asks to run delivery or names an alias without a station slash command, expand via OPERATOR.md and run (or print) that full command. Do not freestyle a parallel backlog. -If only `/poteto-mode` is attached with no station and the request is clearly delivery, load OPERATOR and either run one `/intake-next` tick or name the two loop commands. Do not freestyle a parallel backlog. +If only `/poteto-mode` is attached with no station and the request is clearly delivery, load OPERATOR and either expand `plan`/`validate` or name the alias table. Do not freestyle a parallel backlog.