From 8be406f9347fcea5f7ebc0556a90fb33f3c10f9a Mon Sep 17 00:00:00 2001 From: Go7hic Date: Sat, 8 Aug 2026 12:12:54 +0800 Subject: [PATCH 1/4] Harden portability audit coverage after the baseline merge. Expand vendor-leak patterns with fixtures, neutralize reflect skill-path assumptions, and prefer the GitHub install path so remaining Cursor playbook debt stays visible instead of silent. Co-authored-by: Cursor --- CONTRIBUTING.md | 5 +- INSTALL.md | 21 +++-- README.md | 4 +- scripts/audit_portability.py | 85 ++++++++++++++++++- scripts/fixtures/portability/README.md | 6 ++ .../portability/bad/agent-transcripts.md | 1 + .../portability/bad/ambiguous-helper.md | 1 + .../portability/bad/ambiguous-model-role.md | 1 + .../fixtures/portability/bad/ask-question.md | 1 + .../portability/bad/control-surface.md | 1 + .../portability/bad/cursor-builtin.md | 1 + .../fixtures/portability/bad/cursor-cloud.md | 1 + .../portability/bad/cursor-fs-path.md | 1 + .../portability/bad/cursor-model-slug.md | 1 + .../portability/bad/cursor-team-kit.md | 1 + .../fixtures/portability/bad/readonly-flag.md | 1 + .../portability/bad/run-in-background.md | 1 + .../fixtures/portability/bad/subagent-type.md | 1 + .../portability/good/capability-first.md | 4 + .../reflect/references/divergent-reviewer.md | 2 +- .../reflect/references/judgment-reviewer.md | 2 +- skills/reflect/references/tooling-reviewer.md | 2 +- 22 files changed, 130 insertions(+), 14 deletions(-) create mode 100644 scripts/fixtures/portability/README.md create mode 100644 scripts/fixtures/portability/bad/agent-transcripts.md create mode 100644 scripts/fixtures/portability/bad/ambiguous-helper.md create mode 100644 scripts/fixtures/portability/bad/ambiguous-model-role.md create mode 100644 scripts/fixtures/portability/bad/ask-question.md create mode 100644 scripts/fixtures/portability/bad/control-surface.md create mode 100644 scripts/fixtures/portability/bad/cursor-builtin.md create mode 100644 scripts/fixtures/portability/bad/cursor-cloud.md create mode 100644 scripts/fixtures/portability/bad/cursor-fs-path.md create mode 100644 scripts/fixtures/portability/bad/cursor-model-slug.md create mode 100644 scripts/fixtures/portability/bad/cursor-team-kit.md create mode 100644 scripts/fixtures/portability/bad/readonly-flag.md create mode 100644 scripts/fixtures/portability/bad/run-in-background.md create mode 100644 scripts/fixtures/portability/bad/subagent-type.md create mode 100644 scripts/fixtures/portability/good/capability-first.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 214e325..7896b1b 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -52,9 +52,10 @@ The baseline audit checks: - the complete playbook and adapter inventories; - byte-identical playbook, adapter, and capability-contract mirrors; - Cursor-only frontmatter keys; -- portability smells such as concrete Cursor model slugs, `subagent_type`, `AskQuestion`, Cursor transcript paths, and ambiguous mechanical-rewrite wording. +- portability smells such as concrete Cursor model slugs, `subagent_type`, `AskQuestion`, Cursor filesystem assumptions, `control-cli` / `control-ui`, `agent-transcripts`, Cursor cloud/dashboard workflows, and ambiguous mechanical-rewrite wording; +- regression fixtures under `scripts/fixtures/portability/` for every portability pattern. -The non-strict repository-wide scan reports existing portability debt as warnings. The strict changed-file scan prevents a pull request from adding or preserving those patterns in files it touches. +The non-strict repository-wide scan reports existing portability debt as warnings. Known remaining debt after the portable baseline includes long-running playbooks such as Orchestrate, Shipping, and Autopilot; treat new warnings as work for issue #2 rather than suppressing patterns. The strict changed-file scan prevents a pull request from adding or preserving those patterns in files it touches. ## Semantic review after mechanical porting diff --git a/INSTALL.md b/INSTALL.md index b19e660..3939bd3 100644 --- a/INSTALL.md +++ b/INSTALL.md @@ -2,16 +2,16 @@ Use this portable pack on every Agent Skills–compatible coding agent **except** Cursor (keep Cursor’s official pstack plugin there). -## Recommended: skills.sh global install +## Recommended: GitHub global install ```bash -npx skills add https://skills.sh/p/3EVEFJjSrRBr1mI4 -g -s '*' -y +npx skills add Go7hic/pstack -g -s '*' -y ``` Add `-a` for specific agents if you do not want every discovered agent: ```bash -npx skills add https://skills.sh/p/3EVEFJjSrRBr1mI4 -g \ +npx skills add Go7hic/pstack -g \ -a claude-code -a codex -a opencode -a factory-droid \ -s '*' -y ``` @@ -28,12 +28,21 @@ npx skills add https://skills.sh/p/3EVEFJjSrRBr1mI4 -g \ After install, restart or reload the agent so it rescans skills. +## Optional: skills.sh pack URL + +If you already have a published skills.sh pack for this repo, you can install from that URL instead. Prefer the GitHub install above when the pack page is stale or the URL does not resolve to a valid skill archive. + +```bash +# Replace with your current pack URL only after confirming it installs cleanly. +npx skills add https://skills.sh/p/ -g -s '*' -y +``` + ## Optional: wire more agents from the install tree If the CLI already installed into one global tree and you need another agent that was not selected, symlink from that install location (not from this git checkout): ```bash -# After skills.sh -g, the shared tree is usually: +# After a global install, the shared tree is usually: SRC=~/.agents/skills # If your install only landed under one agent, point SRC there instead, e.g.: # SRC=~/.claude/skills @@ -55,7 +64,7 @@ Do **not** use `~/workspace/pstack/skills` as `SRC` unless you are developing th ### Codex cutover checklist -1. Prefer `npx skills add … -g -a codex` (or symlink from `SRC` above). +1. Prefer `npx skills add Go7hic/pstack -g -a codex` (or symlink from `SRC` above). 2. Delete the old pack if present: `rm -rf ~/.codex/skills/codex-pstack` 3. Point model overrides at `~/.codex/rules/pstack-models.md` (see `adapters/codex-models.md`). 4. Smoke-test: `/pstack` or `/how` and confirm the agent reads `adapters/codex.md` and spawns via `multi_agent_v1` (or current Codex multi-agent tools). @@ -90,4 +99,4 @@ Local checkout only when editing the pack: SRC=~/workspace/pstack/skills # or your clone path ``` -Day-to-day use should go through the skills.sh install path above. +Day-to-day use should go through the GitHub install path above. diff --git a/README.md b/README.md index f00a032..de8629b 100644 --- a/README.md +++ b/README.md @@ -9,10 +9,10 @@ It preserves the same engineering system—principles, playbooks, `how`, `why`, Use this portable pack on Agent Skills-compatible coding agents other than Cursor. Cursor users should keep the official pstack plugin. ```bash -npx skills add https://skills.sh/p/3EVEFJjSrRBr1mI4 -g -s '*' -y +npx skills add Go7hic/pstack -g -s '*' -y ``` -See [INSTALL.md](./INSTALL.md) for per-agent selection, model override paths, migration notes, and smoke tests. After global installation, skills usually land under an agent-specific directory such as `~/.claude/skills/`, `~/.codex/skills/`, or the shared `~/.agents/skills/` tree. +See [INSTALL.md](./INSTALL.md) for per-agent selection, optional skills.sh install, model override paths, migration notes, and smoke tests. After global installation, skills usually land under an agent-specific directory such as `~/.claude/skills/`, `~/.codex/skills/`, or the shared `~/.agents/skills/` tree. ## What is included diff --git a/scripts/audit_portability.py b/scripts/audit_portability.py index a493a03..e337dbd 100644 --- a/scripts/audit_portability.py +++ b/scripts/audit_portability.py @@ -13,6 +13,7 @@ ROOT = Path(__file__).resolve().parents[1] SKILLS = ROOT / "skills" +FIXTURES = ROOT / "scripts" / "fixtures" / "portability" PLAYBOOKS = { "investigation.md", @@ -71,9 +72,27 @@ ("Cursor-only background flag", re.compile(r"\brun_in_background\s*:")), ("runtime-specific readonly flag", re.compile(r"\breadonly\s*:")), ("Cursor AskQuestion API", re.compile(r"\bAskQuestion\b")), - ("Cursor project-history path", re.compile(r"~/\.cursor/projects/")), + ( + "Cursor filesystem path assumption", + re.compile(r"~/\.cursor/(?:projects|skills|plugins)/"), + ), ("Cursor built-in workflow", re.compile(r"Cursor(?:'s)? built-in", re.I)), ("cursor-team-kit dependency", re.compile(r"cursor-team-kit", re.I)), + ( + "Cursor control-surface dependency", + re.compile(r"\bcontrol-(?:cli|ui)\b", re.I), + ), + ( + "Cursor transcript directory assumption", + re.compile(r"\bagent-transcripts\b"), + ), + ( + "Cursor cloud/dashboard workflow", + re.compile( + r"\bCursor cloud(?: agent)?\b|\bCursor dashboard\b|\bCursor restart\b", + re.I, + ), + ), ( "ambiguous generated helper wording", re.compile(r"adapter\s+`?explore`?\s*/\s*`?implement`?\s+helpers?", re.I), @@ -216,6 +235,68 @@ def check_skills(findings: list[Finding]) -> None: findings.append(Finding("WARN", rel, "missing the standard portability block")) +def match_labels(text: str) -> set[str]: + labels: set[str] = set() + for label, pattern in PORTABILITY_PATTERNS: + if pattern.search(text): + labels.add(label) + return labels + + +def check_fixtures(findings: list[Finding]) -> None: + bad_dir = FIXTURES / "bad" + good_dir = FIXTURES / "good" + if not bad_dir.is_dir() or not good_dir.is_dir(): + findings.append( + Finding("ERROR", relative(FIXTURES), "bad/ and good/ fixture directories required") + ) + return + + bad_files = sorted(path for path in bad_dir.glob("*.md") if path.is_file()) + if not bad_files: + findings.append(Finding("ERROR", relative(bad_dir), "expected at least one bad fixture")) + + covered_labels: set[str] = set() + for path in bad_files: + labels = match_labels(read_text(path)) + if not labels: + findings.append( + Finding( + "ERROR", + relative(path), + "bad fixture matched no portability pattern", + ) + ) + continue + covered_labels.update(labels) + + expected_labels = {label for label, _ in PORTABILITY_PATTERNS} + for label in sorted(expected_labels - covered_labels): + findings.append( + Finding( + "ERROR", + relative(bad_dir), + f"no bad fixture covers pattern {label!r}", + ) + ) + + good_files = sorted(path for path in good_dir.glob("*.md") if path.is_file()) + if not good_files: + findings.append( + Finding("ERROR", relative(good_dir), "expected at least one good fixture") + ) + for path in good_files: + labels = match_labels(read_text(path)) + if labels: + findings.append( + Finding( + "ERROR", + relative(path), + "good fixture matched: " + ", ".join(sorted(labels)), + ) + ) + + def changed_paths(base_ref: str) -> set[str]: completed = subprocess.run( ["git", "diff", "--name-only", f"{base_ref}...HEAD"], @@ -291,6 +372,8 @@ def run(strict: bool, changed_from: str | None) -> list[Finding]: Finding("ERROR", "capability-contract.md", "shared reference mirror has drifted") ) + check_fixtures(findings) + selected = changed_paths(changed_from) if changed_from else None scan_portability(findings, selected=selected, strict=strict) return findings diff --git a/scripts/fixtures/portability/README.md b/scripts/fixtures/portability/README.md new file mode 100644 index 0000000..ee1a8dd --- /dev/null +++ b/scripts/fixtures/portability/README.md @@ -0,0 +1,6 @@ +# Portability audit fixtures + +`bad/` samples must trip at least one `PORTABILITY_PATTERNS` rule. +`good/` samples must trip none. + +`scripts/audit_portability.py` fails if a pattern lacks bad coverage or a good fixture regresses. diff --git a/scripts/fixtures/portability/bad/agent-transcripts.md b/scripts/fixtures/portability/bad/agent-transcripts.md new file mode 100644 index 0000000..dc187c5 --- /dev/null +++ b/scripts/fixtures/portability/bad/agent-transcripts.md @@ -0,0 +1 @@ +Scan local files under `agent-transcripts/`. diff --git a/scripts/fixtures/portability/bad/ambiguous-helper.md b/scripts/fixtures/portability/bad/ambiguous-helper.md new file mode 100644 index 0000000..428394f --- /dev/null +++ b/scripts/fixtures/portability/bad/ambiguous-helper.md @@ -0,0 +1 @@ +Use adapter `explore` / `implement` helpers for this step. diff --git a/scripts/fixtures/portability/bad/ambiguous-model-role.md b/scripts/fixtures/portability/bad/ambiguous-model-role.md new file mode 100644 index 0000000..404b7cb --- /dev/null +++ b/scripts/fixtures/portability/bad/ambiguous-model-role.md @@ -0,0 +1 @@ +Default to model_role:fast_explore / feature_impl. diff --git a/scripts/fixtures/portability/bad/ask-question.md b/scripts/fixtures/portability/bad/ask-question.md new file mode 100644 index 0000000..6c0e400 --- /dev/null +++ b/scripts/fixtures/portability/bad/ask-question.md @@ -0,0 +1 @@ +Call AskQuestion before continuing. diff --git a/scripts/fixtures/portability/bad/control-surface.md b/scripts/fixtures/portability/bad/control-surface.md new file mode 100644 index 0000000..85b07e9 --- /dev/null +++ b/scripts/fixtures/portability/bad/control-surface.md @@ -0,0 +1 @@ +Verify with `control-cli` or `control-ui`. diff --git a/scripts/fixtures/portability/bad/cursor-builtin.md b/scripts/fixtures/portability/bad/cursor-builtin.md new file mode 100644 index 0000000..f8edce0 --- /dev/null +++ b/scripts/fixtures/portability/bad/cursor-builtin.md @@ -0,0 +1 @@ +Use Cursor's built-in skill authoring flow. diff --git a/scripts/fixtures/portability/bad/cursor-cloud.md b/scripts/fixtures/portability/bad/cursor-cloud.md new file mode 100644 index 0000000..30c45c0 --- /dev/null +++ b/scripts/fixtures/portability/bad/cursor-cloud.md @@ -0,0 +1 @@ +Spawn one Cursor cloud agent and check the Cursor dashboard after a Cursor restart. diff --git a/scripts/fixtures/portability/bad/cursor-fs-path.md b/scripts/fixtures/portability/bad/cursor-fs-path.md new file mode 100644 index 0000000..49a2b23 --- /dev/null +++ b/scripts/fixtures/portability/bad/cursor-fs-path.md @@ -0,0 +1 @@ +Read history under `~/.cursor/projects/` and skills under `~/.cursor/skills/`. diff --git a/scripts/fixtures/portability/bad/cursor-model-slug.md b/scripts/fixtures/portability/bad/cursor-model-slug.md new file mode 100644 index 0000000..e0014fd --- /dev/null +++ b/scripts/fixtures/portability/bad/cursor-model-slug.md @@ -0,0 +1 @@ +Use `grok-4.5-fast-xhigh` for exploration. diff --git a/scripts/fixtures/portability/bad/cursor-team-kit.md b/scripts/fixtures/portability/bad/cursor-team-kit.md new file mode 100644 index 0000000..8d8cef4 --- /dev/null +++ b/scripts/fixtures/portability/bad/cursor-team-kit.md @@ -0,0 +1 @@ +Install cleanup from `cursor-team-kit`. diff --git a/scripts/fixtures/portability/bad/readonly-flag.md b/scripts/fixtures/portability/bad/readonly-flag.md new file mode 100644 index 0000000..7c2acf8 --- /dev/null +++ b/scripts/fixtures/portability/bad/readonly-flag.md @@ -0,0 +1 @@ +Pass `readonly: true` to the helper. diff --git a/scripts/fixtures/portability/bad/run-in-background.md b/scripts/fixtures/portability/bad/run-in-background.md new file mode 100644 index 0000000..ee16cbb --- /dev/null +++ b/scripts/fixtures/portability/bad/run-in-background.md @@ -0,0 +1 @@ +Set `run_in_background: true` and continue. diff --git a/scripts/fixtures/portability/bad/subagent-type.md b/scripts/fixtures/portability/bad/subagent-type.md new file mode 100644 index 0000000..41a2b98 --- /dev/null +++ b/scripts/fixtures/portability/bad/subagent-type.md @@ -0,0 +1 @@ +Spawn with `subagent_type: generalPurpose`. diff --git a/scripts/fixtures/portability/good/capability-first.md b/scripts/fixtures/portability/good/capability-first.md new file mode 100644 index 0000000..03596c5 --- /dev/null +++ b/scripts/fixtures/portability/good/capability-first.md @@ -0,0 +1,4 @@ +Use `explore` for read-only tracing and `implement` for disjoint writes. +Resolve models through `model_role:fast_explore`. +Verify on the real surface exposed by the active adapter. +When helper spawning is unavailable, collapse to the lead agent and say so. diff --git a/skills/reflect/references/divergent-reviewer.md b/skills/reflect/references/divergent-reviewer.md index 02ac9b7..92f64de 100644 --- a/skills/reflect/references/divergent-reviewer.md +++ b/skills/reflect/references/divergent-reviewer.md @@ -20,7 +20,7 @@ Scan for: Findings must point to skills, tools, or MCPs invoked in this transcript. Speculative routings to skills the parent never opened do not count. To check whether a skill was used, scan the transcript for: -- `Read` tool calls against any `SKILL.md` file (workspace `.cursor/skills/`, user-level `~/.cursor/skills/`, or plugin-installed paths under `~/.cursor/plugins/`) +- read/open tool calls against any `SKILL.md` path that appears in the transcript (workspace, user-global, or agent-install trees such as `~/.claude/skills/`, `~/.codex/skills/`, `~/.agents/skills/`, or another host skill directory) - adapter delegation prompts that name a skill path - Tool calls (Shell, Grep, MCP, etc.) that match a skill's documented commands diff --git a/skills/reflect/references/judgment-reviewer.md b/skills/reflect/references/judgment-reviewer.md index a987125..b6842df 100644 --- a/skills/reflect/references/judgment-reviewer.md +++ b/skills/reflect/references/judgment-reviewer.md @@ -19,7 +19,7 @@ Scan for: Findings must point to skills, tools, or MCPs invoked in this transcript. Speculative routings to skills the parent never opened do not count. To check whether a skill was used, scan the transcript for: -- `Read` tool calls against any `SKILL.md` file (workspace `.cursor/skills/`, user-level `~/.cursor/skills/`, or plugin-installed paths under `~/.cursor/plugins/`) +- read/open tool calls against any `SKILL.md` path that appears in the transcript (workspace, user-global, or agent-install trees such as `~/.claude/skills/`, `~/.codex/skills/`, `~/.agents/skills/`, or another host skill directory) - adapter delegation prompts that name a skill path - Tool calls (Shell, Grep, MCP, etc.) that match a skill's documented commands diff --git a/skills/reflect/references/tooling-reviewer.md b/skills/reflect/references/tooling-reviewer.md index 0b135bd..a1353c0 100644 --- a/skills/reflect/references/tooling-reviewer.md +++ b/skills/reflect/references/tooling-reviewer.md @@ -34,7 +34,7 @@ Scan for: Findings must point to skills, tools, or MCPs invoked in this transcript. Speculative routings to skills the parent never opened do not count. To check whether a skill was used, scan the transcript for: -- `Read` tool calls against any `SKILL.md` file (workspace `.cursor/skills/`, user-level `~/.cursor/skills/`, or plugin-installed paths under `~/.cursor/plugins/`) +- read/open tool calls against any `SKILL.md` path that appears in the transcript (workspace, user-global, or agent-install trees such as `~/.claude/skills/`, `~/.codex/skills/`, `~/.agents/skills/`, or another host skill directory) - adapter delegation prompts that name a skill path - Tool calls (Shell, Grep, MCP, etc.) that match a skill's documented commands From 5cbeeb0b51a10231f9e77bbcb71d44c8a3eef0ee Mon Sep 17 00:00:00 2001 From: Go7hic Date: Sat, 8 Aug 2026 12:22:20 +0800 Subject: [PATCH 2/4] Neutralize long-running playbooks for non-Cursor hosts. Rewrite Orchestrate, Shipping, and Autopilot playbooks around portable capabilities and host fallbacks so the audit no longer hides Cursor cloud, control-surface, or transcript-path assumptions. Co-authored-by: Cursor --- .../poteto-mode/playbooks/autopilot-full.md | 8 ++-- .../poteto-mode/playbooks/autopilot-stack.md | 16 +++---- skills/poteto-mode/playbooks/orchestrate.md | 42 +++++++++---------- skills/poteto-mode/playbooks/shipping.md | 15 +++---- skills/pstack/playbooks/autopilot-full.md | 8 ++-- skills/pstack/playbooks/autopilot-stack.md | 16 +++---- skills/pstack/playbooks/orchestrate.md | 42 +++++++++---------- skills/pstack/playbooks/shipping.md | 15 +++---- 8 files changed, 82 insertions(+), 80 deletions(-) diff --git a/skills/poteto-mode/playbooks/autopilot-full.md b/skills/poteto-mode/playbooks/autopilot-full.md index d29d74c..c4b14dd 100644 --- a/skills/poteto-mode/playbooks/autopilot-full.md +++ b/skills/poteto-mode/playbooks/autopilot-full.md @@ -3,11 +3,11 @@ **You own the verdicts, never the PRs. One owner runs each PR from build to merge, and nothing merges without your clean swarm verdict.** For "autopilot this queue", "full autopilot", and one-owner-per-PR programs. The job is a queue of independent PRs handed over to drive to merged with full autonomy. Orchestrate runs a standing program whose coordinator lands verified work itself and whose workers never merge; here each PR's owner carries the whole lifecycle through the merge, and the root keeps only verification, countersigns, and audits. 1. **Mark the operator's items and honor state-then-wait.** Items the operator names stay hers. She reviews and she clicks, and no owner merges one. When she asks for the protocol or the plan to be stated, deliver the statement and stop. Execution starts only on her explicit go. -2. **Spawn one owner per PR with the full lifecycle.** One Cursor cloud agent per PR owns build, gt registration, self-proof on the real artifact (the **prove-it-works** principle skill), skeptical Bugbot triage per `../references/bugbot-triage.md`, a slop-strip (a local deslop / cleanup pass if available; otherwise apply `unslop` + simplicity review before commit), `/no-comments` (the **no-comments** skill), a restack onto current trunk, the babysit loop to green (`playbooks/babysit.md`), and the merge itself. The restack always precedes babysit and never waits for drift or conflicts. Every owner keeps a decisions.tsv trail per the **show-me-your-work** skill, never committed, returned with its reports. The merge is the one step an owner may not take alone; step 4 gates it. -3. **Run owners in true parallel and never stack.** Many owners at once when PRs are self-contained: one writer per branch, disjoint files, cross-PR drift absorbed by rebase. Only genuinely overlapping work serializes. Self-contained PRs branch straight off main, and sequenced work is merge-then-branch. Every PR is still gt-registered; the Graphite-metadata rule is about the UI, not stacks. One exception: an owner that must split a genuinely dependent change may hold a short private stack. -4. **Swarm-verify every merge-ready head before its merge.** At the owner's merge-ready head SHA, fan out parallel independent verifiers per the **swarm** skill and aggregate to one verdict. The fan-out mechanics live there; do not restate them. The lanes: re-run the gates at that SHA; prove the load-bearing behavior live on the real surface the change touches (the real CLI/TUI or browser/UI surface available in this runtime); audit the receipts and the diff, distrusting the PR body. The live lane is the floor, and a verdict without it is not clean. No merge without the root's clean verdict. Findings go back to the owner for fix-forward, and the new head gets a fresh swarm and a fresh verdict. +2. **Spawn one owner per PR with the full lifecycle.** Use `parallel` with one `implement` helper per PR when the active adapter can spawn workers; prefer isolated or cloud workers when available so owners do not share a writable checkout. Each owner owns build, stack/PR registration, self-proof on the real artifact (the **prove-it-works** principle skill), skeptical automated-review triage per `../references/bugbot-triage.md`, a local simplicity and cleanup pass when available (otherwise `unslop` plus a simplicity review before commit), `/no-comments` (the **no-comments** skill), a restack onto current trunk, the babysit loop to green (`playbooks/babysit.md`), and the merge itself. The restack always precedes babysit and never waits for drift or conflicts. Every owner keeps a decisions.tsv trail per the **show-me-your-work** skill, never committed, returned with its reports. The merge is the one step an owner may not take alone; step 4 gates it. When helper spawning is unavailable, serialize owners on the lead agent and state the degraded path. +3. **Run owners in true parallel and never stack.** Many owners at once when PRs are self-contained: one writer per branch, disjoint files, cross-PR drift absorbed by rebase. Only genuinely overlapping work serializes. Self-contained PRs branch straight off main, and sequenced work is merge-then-branch. Every PR is still registered with the repo's stack or forge tooling; metadata rules are about the review UI, not stacks. One exception: an owner that must split a genuinely dependent change may hold a short private stack. +4. **Swarm-verify every merge-ready head before its merge.** At the owner's merge-ready head SHA, fan out parallel independent verifiers per the **swarm** skill and aggregate to one verdict. The fan-out mechanics live there; do not restate them. The lanes: re-run the gates at that SHA; prove the load-bearing behavior live with `verify` on the real surface the change touches; audit the receipts and the diff, distrusting the PR body. The live lane is the floor, and a verdict without it is not clean. No merge without the root's clean verdict. Findings go back to the owner for fix-forward, and the new head gets a fresh swarm and a fresh verdict. 5. **On a clean verdict the owner merges and takes the next item.** The owner merges only from a head freshly restacked on trunk. The merge-ready report is made at a trunk-current head, and the swarm verdict pins that SHA. If trunk moves again before the merge, the patch-id rule in `playbooks/shipping.md` governs re-verification; a new head voids the verdict unless the patch-id is unchanged. The owner squash-merges its own PR and picks up its next self-contained item from the queue. The operator's full-autonomy grant plus the root's clean verdict is the merge authorization that babysitting alone never has. Operator-named items stop at merge-ready and wait for her click. -6. **Run the root layer.** A genuinely new raise of a pinned gate or budget value (a limit CI only lets tighten) needs your fresh countersign, granted only after verifier proof. Absorbing values that already landed on main is drift, not a raise. Run an audit tick over all owners roughly every 30 minutes, riding a cloud-sleeper wake chain (a sleeping cloud agent that re-arms its own wake). Each tick probes liveness via a cloud-agent status / liveness probe, audits both progress and protocol adherence, and collects the decision trails. When merges batch, run a retro pass and a post-merge bot-comment sweep. +6. **Run the root layer.** A genuinely new raise of a pinned gate or budget value (a limit CI only lets tighten) needs your fresh countersign, granted only after verifier proof. Absorbing values that already landed on main is drift, not a raise. Run an audit tick over all owners roughly every 30 minutes through the host's long-running, wake, or loop mechanism when available; otherwise poll with a bounded cadence and state the degraded path. Each tick probes owner liveness through forge status, branch activity, and helper/task status the adapter exposes; audits both progress and protocol adherence; and collects the decision trails. When merges batch, run a retro pass and a post-merge bot-comment sweep. 7. **Stand down instantly on the operator's stop.** Her hold or stand-down reaches every owner as a zero-writes order immediately. Owners hold their briefs until she releases them. **Reply:** the queue with each PR's owner, state, and head SHA; each verdict and the swarm that produced it; what merged and what each owner took next; countersigns granted and why; open operator gates; where the collected decision trails live. diff --git a/skills/poteto-mode/playbooks/autopilot-stack.md b/skills/poteto-mode/playbooks/autopilot-stack.md index 45e41d7..4fb7078 100644 --- a/skills/poteto-mode/playbooks/autopilot-stack.md +++ b/skills/poteto-mode/playbooks/autopilot-stack.md @@ -1,15 +1,15 @@ ### Autopilot-stack -**You own the stack, never the landing. Build and verify the queue with full autonomy, then hand the operator one linear Graphite stack she reviews and lands herself.** For "autopilot-stack", "stack them, don't ship", "build the stack, I'll land it". The sibling of **Autopilot-full**. The owner loop and the verification gate are the same; only the terminal differs. There a clean verdict authorizes the owner's merge. Here it appends a link to the one reviewed chain, and nothing auto-ships. +**You own the stack, never the landing. Build and verify the queue with full autonomy, then hand the operator one linear stack she reviews and lands herself.** For "autopilot-stack", "stack them, don't ship", "build the stack, I'll land it". The sibling of **Autopilot-full**. The owner loop and the verification gate are the same; only the terminal differs. There a clean verdict authorizes the owner's merge. Here it appends a link to the one reviewed chain, and nothing auto-ships. -1. **Run the owner loop unchanged.** One Cursor cloud agent per PR owns its change end to end: build, `gt` registration of its own PR, self-proof (gates, CI, receipts), skeptical Bugbot triage per `../references/bugbot-triage.md`, a slop-strip (a local deslop / cleanup pass if available; otherwise apply `unslop` + simplicity review before commit), `/no-comments` (the **no-comments** skill), and babysit to green per `playbooks/babysit.md`. Owners parallelize when the work is self-contained. Every owner keeps a `decisions.tsv` trail per the **show-me-your-work** skill, never committed, returned in its report. -2. **Audit on the wake chain.** The root runs audit ticks roughly every 30 minutes on a cloud-sleeper wake chain: cloud-agent liveness per owner, progress, and protocol adherence. +1. **Run the owner loop unchanged.** Use `parallel` with one `implement` helper per PR when the active adapter can spawn workers; prefer isolated or cloud workers when available. Each owner owns its change end to end: build, registration of its own PR with the repo's stack or forge tooling, self-proof (gates, CI, receipts), skeptical automated-review triage per `../references/bugbot-triage.md`, a local simplicity and cleanup pass when available (otherwise `unslop` plus a simplicity review before commit), `/no-comments` (the **no-comments** skill), and babysit to green per `playbooks/babysit.md`. Owners parallelize when the work is self-contained. Every owner keeps a `decisions.tsv` trail per the **show-me-your-work** skill, never committed, returned in its report. When helper spawning is unavailable, serialize owners and state the degraded path. +2. **Audit on the wake chain.** The root runs audit ticks roughly every 30 minutes through the host's long-running, wake, or loop mechanism when available; otherwise poll with a bounded cadence. Each tick checks owner liveness, progress, and protocol adherence. 3. **Hold the operator gates.** State-then-wait, so a request to state the plan is not a go. On her stop, every owner takes an immediate zero-writes hold. -4. **Verify at STACK-READY.** The owner reports STACK-READY with the exact head SHA. The root swarm-verifies that SHA, fan-out per the **swarm** skill: parallel independent verifiers re-running the gates at that SHA, a live runtime floor over the load-bearing behavior, and a receipts-and-diff audit that distrusts the PR body. The swarm aggregates to one verdict. Findings go back to the owner, and nothing enters the stack unverified. -5. **Append on a clean verdict, never ship.** No owner merges, arms auto-merge, or closes. A clean verdict appends the PR to the one linear Graphite stack, in verified order or an order the operator specified. -6. **Single writer on topology, parallel writers on builds.** Stack mechanics follow Graphite (`gt`), with the division of labor the cloud environment forces. An owner pushes only its own branch, `git push --force-with-lease` after an ls-remote check, and reports its tip and intended parent. The root owns stack topology and registers each append locally: `gt track -p `, then `gt submit --no-interactive --stack` from the tip. `gt submit` walks from trunk, and a cloud agent must never pull branches below its own into that walk; when instructed, it may set its bottom PR's base directly instead. -7. **Absorb drift at the root, then re-verify what moved.** The root absorbs trunk movement by restacking the chain (`gt restack`, `gt sync`); when a restack surfaces conflicts in an owner's files, that owner fixes its own slice and the root pushes the result. A restack rewrites every SHA above it and voids the verdicts at the old SHAs. Compare `git patch-id` at each verdict SHA against the new head. Anything that actually drifted goes back through step 4 before delivery. The countersign rule is unchanged from Autopilot-full. A genuinely new pin raises a stop for the root's fresh countersign; absorbing drift of landed values is not a raise. -8. **Deliver the chain.** The deliverable is one linear chain of verified PRs, reviewable bottom-up in the Graphite UI, every link carrying its verifier verdict in the PR body or a comment. The operator reviews and lands it, with her own clicks or with merge-when-ready she arms herself. +4. **Verify at STACK-READY.** The owner reports STACK-READY with the exact head SHA. The root swarm-verifies that SHA, fan-out per the **swarm** skill: parallel independent verifiers re-running the gates at that SHA, a live `verify` floor over the load-bearing behavior, and a receipts-and-diff audit that distrusts the PR body. The swarm aggregates to one verdict. Findings go back to the owner, and nothing enters the stack unverified. +5. **Append on a clean verdict, never ship.** No owner merges, arms auto-merge, or closes. A clean verdict appends the PR to the one linear stack, in verified order or an order the operator specified. +6. **Single writer on topology, parallel writers on builds.** Stack mechanics follow the repo's stack tool (commonly Graphite `gt`). An owner pushes only its own branch, `git push --force-with-lease` after an ls-remote check, and reports its tip and intended parent. The root owns stack topology and registers each append: track the parent tip, then submit the stack from the tip without interactive prompts. A worker must never pull branches below its own into a stack-wide submit walk; when instructed, it may set its bottom PR's base directly instead. +7. **Absorb drift at the root, then re-verify what moved.** The root absorbs trunk movement by restacking the chain; when a restack surfaces conflicts in an owner's files, that owner fixes its own slice and the root pushes the result. A restack rewrites every SHA above it and voids the verdicts at the old SHAs. Compare `git patch-id` at each verdict SHA against the new head. Anything that actually drifted goes back through step 4 before delivery. The countersign rule is unchanged from Autopilot-full. A genuinely new pin raises a stop for the root's fresh countersign; absorbing drift of landed values is not a raise. +8. **Deliver the chain.** The deliverable is one linear chain of verified PRs, reviewable bottom-up in the forge or stack UI, every link carrying its verifier verdict in the PR body or a comment. The operator reviews and lands it, with her own clicks or with merge-when-ready she arms herself. **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. diff --git a/skills/poteto-mode/playbooks/orchestrate.md b/skills/poteto-mode/playbooks/orchestrate.md index 73694d6..8f08127 100644 --- a/skills/poteto-mode/playbooks/orchestrate.md +++ b/skills/poteto-mode/playbooks/orchestrate.md @@ -1,6 +1,6 @@ ### Orchestrate -**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; measured head-to-head, this playbook's ceremony turned a half-hour 12-unit job into 1 landed unit while a plain agent landed all 12. Below that line, route to Autonomous run. +**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 helpers, 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; measured head-to-head, this playbook's ceremony turned a half-hour 12-unit job into 1 landed unit while a plain agent landed all 12. Below that line, route to Autonomous run. Ceremony must scale with the program. Every gate below prices in coordinator minutes; on cheap near-identical units, collapse it as each section directs rather than paying list price. @@ -14,15 +14,15 @@ Open a todolist with the steps below copied in verbatim. A step you skip stays l #### Roles and placement -- **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, restacks, 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 delegation tool. State reads and writes go through `scripts/orch/orch.ts` at drain points, one command in and one line out, to conserve context. The CLI never spawns, waits, or wakes anything. -- **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 adapter delegation schema including `environment`). 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. -- **Worker / verifier.** Always isolated/cloud worker environment when the adapter supports it unless the task needs this machine: `control-ui` or `control-cli` runtime verification (if available in this environment); reading local transcripts under `agent-transcripts/`; simulators and local IDE state; auth that exists only here. Cloud agents cannot read the local store, so their briefs inline what they need or point at repo paths. Prefer fewer, broader workers; one writer per worktree or branch (principle-separate-before-serializing-shared-state). Run a unit's verifier on a different model family from its worker. +- **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, restacks, 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. Helpers are spawned, resumed, and drained only through the active adapter's delegation tools (`parallel`, `implement`, `explore`, `review`). State reads and writes go through `scripts/orch/orch.ts` at drain points, one command in and one line out, to conserve context. The CLI never spawns, waits, or wakes anything. +- **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 carries the full adapter delegation contract including isolation or environment when the host supports it). 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. +- **Worker / verifier.** Prefer an isolated or cloud worker environment when the adapter supports it, unless the task needs this machine: `verify` on the real CLI, TUI, browser, API, or other runtime surface; reading a host-provided session or transcript resource for the current program; simulators and local IDE state; auth that exists only here. Isolated workers cannot read the local store, so their briefs inline what they need or point at repo paths. Prefer fewer, broader workers; one writer per worktree or branch (principle-separate-before-serializing-shared-state). Run a unit's verifier on a different model family from its worker when `model_role` selection is available. 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. #### Store layout -Create `orchestrate//` 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. +Create `orchestrate//` in the current agent's durable store (path from the host system prompt or adapter). 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. When the orch CLI is unavailable, keep the same file layout and update it with ordinary edits; do not invent a second schema. - `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). - `overview.md` is the durable PR and issue DB. Append; never rewrite wholesale per event. @@ -43,34 +43,34 @@ SCOPE paths this unit may write; paths it may not; its exclusive worktree CONTEXT pointers to files and PRs; upstream reports pasted in full when this unit depends on them, because workers cannot see siblings ACCEPTANCE checkable criteria, one per line -VERIFY exact commands or the control-skill path, plus known gotchas +VERIFY exact commands or the active-host verify recipe, plus known gotchas TIMEBOX rough cap on runtime; on expiry, return partial findings and stop rather than run on -FORBIDDEN no gt, no rebase, no force-push, no fixes outside scope, plus unit-specific bans +FORBIDDEN no stack surgery, no rebase, no force-push, no fixes outside scope, plus unit-specific bans REPORT status, branch, head SHA, PRs, verdict, what you actually ran, deviations, suggested follow-ups STANDING ``` -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. +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 isolated or cloud spawns and every resume. -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). +A sub-coordinator brief adds its track boundary and unit list, its spawn budget with the isolated/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). 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. #### Steps 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, because finished-but-unlanded work counts as zero. 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. -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 `. +2. **Install the runtime.** Run `orch init` when available. 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 ` or an equivalent write. 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. -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. +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. Prefer real `parallel` fan-out; collapse only when the adapter cannot spawn helpers. 5. **Drain.** Run the queue discipline below at every drain point. 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. -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. +7. **Close.** Drain the final inbox, reconcile every spawned helper 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. #### Queue and drain - On a completion notification, run `orch inbox push [--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. -- 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. +- Drain in batches at four points: the end of a critical section, a track rollup, a frontier watcher wake (arm it through the host's long-running or loop mechanism, 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. - Critical sections you finish first: authoring a brief, a stack operation, a conflict decision, writing a gate, updating ledger or frontier. - 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. - 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. @@ -78,29 +78,29 @@ A dependency is a context relay, not just ordering: undeclared upstream context #### Stack safety -- The frontier is a computed object, never narrative. Recompute `frontier.json` from `gt` after every merge and stack mutation because GitHub base refs drift mid-restack while gt tracking is authoritative: ordered PR list, branch names, head SHAs, a generation number, the lowest unmerged PR. Resolve it where gt knows the stack, normally the stacker's clone; a checkout whose gt metadata never saw the submits reports no PRs and the command errors rather than guessing. -- Exactly one stacker per stack may run `gt`, serialized within its stack; record the holder in the standing orders. Restacks run in cloud; a local restack at this scale takes the laptop down. -- Workers never rebase and never run `gt`. Babysitters follow `playbooks/babysit.md`, one per stack, scoped to one immutable frontier generation; they report conflicts to the stacker rather than restacking. +- The frontier is a computed object, never narrative. Recompute `frontier.json` from the repo's stack tool after every merge and stack mutation because forge base refs drift mid-restack while stack tracking is authoritative: ordered PR list, branch names, head SHAs, a generation number, the lowest unmerged PR. Resolve it where the stack tool knows the stack, normally the stacker's clone; a checkout whose stack metadata never saw the submits reports no PRs and the command errors rather than guessing. +- Exactly one stacker per stack may run stack mutations, serialized within its stack; record the holder in the standing orders. Prefer isolated or cloud restacks when available; a large local restack can stall the coordinator machine. +- Workers never rebase and never run stack surgery. Babysitters follow `playbooks/babysit.md`, one per stack, scoped to one immutable frontier generation; they report conflicts to the stacker rather than restacking. - 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. - One retro watcher follows merged PRs for reverts, post-merge CI breaks, and orphaned follow-ups. #### Verification -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. +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 helper (on a different model family than the worker when possible) is for units whose verification is expensive, judgment-laden, or high-blast-radius. A verifier helper whose entire product would be rerunning one command is ceremony, not verification. -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. +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 a transcript dump. -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. +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 machine when that machine dies was never done. #### Liveness and failure -- Never resume an agent to check on it; a resume restarts an idle agent. Probe read-only: the ledger, `units.tsv`, `gh`, pushed branches, the cloud agent's status in the Cursor dashboard. Transcript mtime is not liveness. +- Never resume a helper only to check on it; a resume can restart idle work. Probe read-only: the ledger, `units.tsv`, forge CLI or API, pushed branches, and any helper or cloud-worker status the active adapter exposes. Transcript mtime is not liveness. - 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. - 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. - A zombie that returns hours late reconciles against the current frontier and ledger before anything is accepted; the world moved while it slept. Salvage unique findings through a fresh unit, never a blind merge. - 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. - 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. Hours of retry loops against a dead executor produce nothing a handoff would not. -- After a Cursor restart: local agents are dead, cloud work is not. Re-read the standing orders and `units.tsv`, recompute the frontier, reattach cloud 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. +- After a coordinator session restart or context reset: local helpers are dead; isolated or cloud work may still be alive. Re-read the standing orders and `units.tsv`, recompute the frontier, reattach remote work by PR and branch rather than helper 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. #### Escalation diff --git a/skills/poteto-mode/playbooks/shipping.md b/skills/poteto-mode/playbooks/shipping.md index 62c0b1c..a6f86e3 100644 --- a/skills/poteto-mode/playbooks/shipping.md +++ b/skills/poteto-mode/playbooks/shipping.md @@ -2,19 +2,20 @@ **You own what lands. Verify each PR independently, land only the verified run from the root, then keep your hands off the queue.** For "land the stack", "ship it", "enable merge when ready", or the second half of a stack that **Babysit** already drove to green. -This is the half after `playbooks/babysit.md`. Babysit makes a stack mergeable. Shipping decides what is actually safe to merge and lets Graphite drain it. Green is not safe, and the gap between those two words is where this playbook lives. +This is the half after `playbooks/babysit.md`. Babysit makes a stack mergeable. Shipping decides what is actually safe to merge and lets the stack tool drain it. Green is not safe, and the gap between those two words is where this playbook lives. -1. **Verify every PR independently before arming anything.** One subagent per PR, not batched, each a Cursor cloud agent, each exercising the real surface (`control-ui` or `control-cli` if available in this environment as the change demands) against parent versus head. Each returns `PASS`, `PASS+NOTES` or `FAIL` and posts that verdict on its own PR so the record outlives the chat. Safe means a verdict from an agent that did not write the code. CI green is not a verdict, and an approving bot review is not a verdict. +1. **Verify every PR independently before arming anything.** One helper per PR, not batched. Prefer an isolated or cloud worker when the active adapter supports it so the verifier did not write the code. Each helper uses `verify` on the real surface the change touches (CLI, TUI, browser, API, or other runtime the adapter can drive) against parent versus head. Each returns `PASS`, `PASS+NOTES`, or `FAIL` and posts that verdict on its own PR so the record outlives the chat. Safe means a verdict from an agent that did not write the code. CI green is not a verdict, and an approving bot review is not a verdict. When isolated helpers are unavailable, run verifiers sequentially on the lead with disjoint evidence packages and state the degraded path. 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 a passing verdict, where both `PASS` and `PASS+NOTES` pass. A verified PR sitting above an unverified one is not landable, because merging it would pull the gap in underneath it. Report the ceiling as a PR number and say what breaks the chain. 3. **Re-check that the verdicts still describe the code.** A restack rewrites every SHA above it and silently invalidates every verdict without touching a single check. Compare `git patch-id` at the verdict SHA against the current head before trusting an older verdict, and re-verify anything that actually drifted. Twenty-one verdicts went stale this way in one run with no signal at all. -4. **Arm merge-when-ready through Graphite, and pass `--always`.** A no-op submit skips the Graphite update and silently arms nothing, which reads exactly like success. +4. **Arm merge-when-ready through the stack tool the repo already uses, and force a real update.** On Graphite-managed stacks: ```bash gt submit --merge-when-ready --always --update-only --no-interactive ``` -5. **Never enable GitHub auto-merge on a stack.** Only the root targets protected trunk. Every child targets its unprotected parent branch and already reads `CLEAN`, so GitHub would merge children into parents immediately and collapse the stack into itself. Graphite is what makes the merges sequential. If a previous agent armed it, disarm with `gh pr merge --disable-auto` and confirm the field is back off. -6. **Do not read `autoMergeRequest` as proof that MWR is armed.** It stays off until Graphite reaches that PR at the queue front, so an unarmed reading is meaningless and acting on it leads to re-submitting branches that were already fine. Confirm arming from Graphite's own state, and if you cannot, say so rather than inferring it. -7. **Once the queue is draining, stop touching the stack.** No `gt sync`, no restack, no speculative pushes, and no `gt submit --stack`, which reaches downstack into PRs that are mid-merge. Even a plain `gt submit` can retarget a base if local Graphite tracking has diverged, so never run `gt` from a worktree whose parentage you have not just checked. Independent work gets re-parented onto trunk and shipped on its own. -8. **Watch the drain, do not drive it.** Arm the watcher in queued mode over the verified run and hold it under `long-runlong-run/loop` in dynamic mode, re-armed after any verdict you act on, until COMPLETE at the ceiling. ADVANCE is progress, not termination. Bases retarget and `graphite-base/*` refs get cut as each PR merges; that is Graphite working, not damage. Report each merge and the new ceiling. If the queue stalls, diagnose before mutating, because a stalled queue and a broken stack look identical from the outside. + A no-op submit skips the stack update and silently arms nothing, which reads exactly like success. On repos without Graphite, use the forge's sequential merge-queue or merge-when-ready equivalent and confirm the arming from that tool's own state. +5. **Never enable forge auto-merge on a mid-stack child.** Only the root targets protected trunk. Every child targets its unprotected parent branch and already reads mergeable, so forge auto-merge would merge children into parents immediately and collapse the stack into itself. The stack tool is what makes the merges sequential. If a previous agent armed forge auto-merge, disarm it and confirm the field is back off. +6. **Do not read a forge auto-merge field as proof that merge-when-ready is armed.** It often stays off until the queue reaches that PR, so an unarmed reading is meaningless and acting on it leads to re-submitting branches that were already fine. Confirm arming from the stack tool's own state, and if you cannot, say so rather than inferring it. +7. **Once the queue is draining, stop touching the stack.** No speculative sync, restack, or stack-wide submit that reaches downstack into PRs that are mid-merge. Even a plain stack submit can retarget a base if local tracking has diverged, so never run stack mutations from a worktree whose parentage you have not just checked. Independent work gets re-parented onto trunk and shipped on its own. +8. **Watch the drain, do not drive it.** Arm a watcher over the verified run through the host's long-running or loop mechanism when available; otherwise poll with a bounded cadence. Re-arm after any verdict you act on until COMPLETE at the ceiling. ADVANCE is progress, not termination. Bases retarget and temporary stack refs get cut as each PR merges; that is the stack tool working, not damage. Report each merge and the new ceiling. If the queue stalls, diagnose before mutating, because a stalled queue and a broken stack look identical from the outside. 9. **Stop at the ceiling.** When the verified run is merged, report what landed, what the next unverified PR is, and what verifying it would take. Extending the run is a new pass through step 1, not a judgment call you make at 3am. **Reply:** the verified run and its ceiling, each PR's verdict and who produced it, what you armed and how you confirmed it, what landed, and what the next gap needs. diff --git a/skills/pstack/playbooks/autopilot-full.md b/skills/pstack/playbooks/autopilot-full.md index d29d74c..c4b14dd 100644 --- a/skills/pstack/playbooks/autopilot-full.md +++ b/skills/pstack/playbooks/autopilot-full.md @@ -3,11 +3,11 @@ **You own the verdicts, never the PRs. One owner runs each PR from build to merge, and nothing merges without your clean swarm verdict.** For "autopilot this queue", "full autopilot", and one-owner-per-PR programs. The job is a queue of independent PRs handed over to drive to merged with full autonomy. Orchestrate runs a standing program whose coordinator lands verified work itself and whose workers never merge; here each PR's owner carries the whole lifecycle through the merge, and the root keeps only verification, countersigns, and audits. 1. **Mark the operator's items and honor state-then-wait.** Items the operator names stay hers. She reviews and she clicks, and no owner merges one. When she asks for the protocol or the plan to be stated, deliver the statement and stop. Execution starts only on her explicit go. -2. **Spawn one owner per PR with the full lifecycle.** One Cursor cloud agent per PR owns build, gt registration, self-proof on the real artifact (the **prove-it-works** principle skill), skeptical Bugbot triage per `../references/bugbot-triage.md`, a slop-strip (a local deslop / cleanup pass if available; otherwise apply `unslop` + simplicity review before commit), `/no-comments` (the **no-comments** skill), a restack onto current trunk, the babysit loop to green (`playbooks/babysit.md`), and the merge itself. The restack always precedes babysit and never waits for drift or conflicts. Every owner keeps a decisions.tsv trail per the **show-me-your-work** skill, never committed, returned with its reports. The merge is the one step an owner may not take alone; step 4 gates it. -3. **Run owners in true parallel and never stack.** Many owners at once when PRs are self-contained: one writer per branch, disjoint files, cross-PR drift absorbed by rebase. Only genuinely overlapping work serializes. Self-contained PRs branch straight off main, and sequenced work is merge-then-branch. Every PR is still gt-registered; the Graphite-metadata rule is about the UI, not stacks. One exception: an owner that must split a genuinely dependent change may hold a short private stack. -4. **Swarm-verify every merge-ready head before its merge.** At the owner's merge-ready head SHA, fan out parallel independent verifiers per the **swarm** skill and aggregate to one verdict. The fan-out mechanics live there; do not restate them. The lanes: re-run the gates at that SHA; prove the load-bearing behavior live on the real surface the change touches (the real CLI/TUI or browser/UI surface available in this runtime); audit the receipts and the diff, distrusting the PR body. The live lane is the floor, and a verdict without it is not clean. No merge without the root's clean verdict. Findings go back to the owner for fix-forward, and the new head gets a fresh swarm and a fresh verdict. +2. **Spawn one owner per PR with the full lifecycle.** Use `parallel` with one `implement` helper per PR when the active adapter can spawn workers; prefer isolated or cloud workers when available so owners do not share a writable checkout. Each owner owns build, stack/PR registration, self-proof on the real artifact (the **prove-it-works** principle skill), skeptical automated-review triage per `../references/bugbot-triage.md`, a local simplicity and cleanup pass when available (otherwise `unslop` plus a simplicity review before commit), `/no-comments` (the **no-comments** skill), a restack onto current trunk, the babysit loop to green (`playbooks/babysit.md`), and the merge itself. The restack always precedes babysit and never waits for drift or conflicts. Every owner keeps a decisions.tsv trail per the **show-me-your-work** skill, never committed, returned with its reports. The merge is the one step an owner may not take alone; step 4 gates it. When helper spawning is unavailable, serialize owners on the lead agent and state the degraded path. +3. **Run owners in true parallel and never stack.** Many owners at once when PRs are self-contained: one writer per branch, disjoint files, cross-PR drift absorbed by rebase. Only genuinely overlapping work serializes. Self-contained PRs branch straight off main, and sequenced work is merge-then-branch. Every PR is still registered with the repo's stack or forge tooling; metadata rules are about the review UI, not stacks. One exception: an owner that must split a genuinely dependent change may hold a short private stack. +4. **Swarm-verify every merge-ready head before its merge.** At the owner's merge-ready head SHA, fan out parallel independent verifiers per the **swarm** skill and aggregate to one verdict. The fan-out mechanics live there; do not restate them. The lanes: re-run the gates at that SHA; prove the load-bearing behavior live with `verify` on the real surface the change touches; audit the receipts and the diff, distrusting the PR body. The live lane is the floor, and a verdict without it is not clean. No merge without the root's clean verdict. Findings go back to the owner for fix-forward, and the new head gets a fresh swarm and a fresh verdict. 5. **On a clean verdict the owner merges and takes the next item.** The owner merges only from a head freshly restacked on trunk. The merge-ready report is made at a trunk-current head, and the swarm verdict pins that SHA. If trunk moves again before the merge, the patch-id rule in `playbooks/shipping.md` governs re-verification; a new head voids the verdict unless the patch-id is unchanged. The owner squash-merges its own PR and picks up its next self-contained item from the queue. The operator's full-autonomy grant plus the root's clean verdict is the merge authorization that babysitting alone never has. Operator-named items stop at merge-ready and wait for her click. -6. **Run the root layer.** A genuinely new raise of a pinned gate or budget value (a limit CI only lets tighten) needs your fresh countersign, granted only after verifier proof. Absorbing values that already landed on main is drift, not a raise. Run an audit tick over all owners roughly every 30 minutes, riding a cloud-sleeper wake chain (a sleeping cloud agent that re-arms its own wake). Each tick probes liveness via a cloud-agent status / liveness probe, audits both progress and protocol adherence, and collects the decision trails. When merges batch, run a retro pass and a post-merge bot-comment sweep. +6. **Run the root layer.** A genuinely new raise of a pinned gate or budget value (a limit CI only lets tighten) needs your fresh countersign, granted only after verifier proof. Absorbing values that already landed on main is drift, not a raise. Run an audit tick over all owners roughly every 30 minutes through the host's long-running, wake, or loop mechanism when available; otherwise poll with a bounded cadence and state the degraded path. Each tick probes owner liveness through forge status, branch activity, and helper/task status the adapter exposes; audits both progress and protocol adherence; and collects the decision trails. When merges batch, run a retro pass and a post-merge bot-comment sweep. 7. **Stand down instantly on the operator's stop.** Her hold or stand-down reaches every owner as a zero-writes order immediately. Owners hold their briefs until she releases them. **Reply:** the queue with each PR's owner, state, and head SHA; each verdict and the swarm that produced it; what merged and what each owner took next; countersigns granted and why; open operator gates; where the collected decision trails live. diff --git a/skills/pstack/playbooks/autopilot-stack.md b/skills/pstack/playbooks/autopilot-stack.md index 45e41d7..4fb7078 100644 --- a/skills/pstack/playbooks/autopilot-stack.md +++ b/skills/pstack/playbooks/autopilot-stack.md @@ -1,15 +1,15 @@ ### Autopilot-stack -**You own the stack, never the landing. Build and verify the queue with full autonomy, then hand the operator one linear Graphite stack she reviews and lands herself.** For "autopilot-stack", "stack them, don't ship", "build the stack, I'll land it". The sibling of **Autopilot-full**. The owner loop and the verification gate are the same; only the terminal differs. There a clean verdict authorizes the owner's merge. Here it appends a link to the one reviewed chain, and nothing auto-ships. +**You own the stack, never the landing. Build and verify the queue with full autonomy, then hand the operator one linear stack she reviews and lands herself.** For "autopilot-stack", "stack them, don't ship", "build the stack, I'll land it". The sibling of **Autopilot-full**. The owner loop and the verification gate are the same; only the terminal differs. There a clean verdict authorizes the owner's merge. Here it appends a link to the one reviewed chain, and nothing auto-ships. -1. **Run the owner loop unchanged.** One Cursor cloud agent per PR owns its change end to end: build, `gt` registration of its own PR, self-proof (gates, CI, receipts), skeptical Bugbot triage per `../references/bugbot-triage.md`, a slop-strip (a local deslop / cleanup pass if available; otherwise apply `unslop` + simplicity review before commit), `/no-comments` (the **no-comments** skill), and babysit to green per `playbooks/babysit.md`. Owners parallelize when the work is self-contained. Every owner keeps a `decisions.tsv` trail per the **show-me-your-work** skill, never committed, returned in its report. -2. **Audit on the wake chain.** The root runs audit ticks roughly every 30 minutes on a cloud-sleeper wake chain: cloud-agent liveness per owner, progress, and protocol adherence. +1. **Run the owner loop unchanged.** Use `parallel` with one `implement` helper per PR when the active adapter can spawn workers; prefer isolated or cloud workers when available. Each owner owns its change end to end: build, registration of its own PR with the repo's stack or forge tooling, self-proof (gates, CI, receipts), skeptical automated-review triage per `../references/bugbot-triage.md`, a local simplicity and cleanup pass when available (otherwise `unslop` plus a simplicity review before commit), `/no-comments` (the **no-comments** skill), and babysit to green per `playbooks/babysit.md`. Owners parallelize when the work is self-contained. Every owner keeps a `decisions.tsv` trail per the **show-me-your-work** skill, never committed, returned in its report. When helper spawning is unavailable, serialize owners and state the degraded path. +2. **Audit on the wake chain.** The root runs audit ticks roughly every 30 minutes through the host's long-running, wake, or loop mechanism when available; otherwise poll with a bounded cadence. Each tick checks owner liveness, progress, and protocol adherence. 3. **Hold the operator gates.** State-then-wait, so a request to state the plan is not a go. On her stop, every owner takes an immediate zero-writes hold. -4. **Verify at STACK-READY.** The owner reports STACK-READY with the exact head SHA. The root swarm-verifies that SHA, fan-out per the **swarm** skill: parallel independent verifiers re-running the gates at that SHA, a live runtime floor over the load-bearing behavior, and a receipts-and-diff audit that distrusts the PR body. The swarm aggregates to one verdict. Findings go back to the owner, and nothing enters the stack unverified. -5. **Append on a clean verdict, never ship.** No owner merges, arms auto-merge, or closes. A clean verdict appends the PR to the one linear Graphite stack, in verified order or an order the operator specified. -6. **Single writer on topology, parallel writers on builds.** Stack mechanics follow Graphite (`gt`), with the division of labor the cloud environment forces. An owner pushes only its own branch, `git push --force-with-lease` after an ls-remote check, and reports its tip and intended parent. The root owns stack topology and registers each append locally: `gt track -p `, then `gt submit --no-interactive --stack` from the tip. `gt submit` walks from trunk, and a cloud agent must never pull branches below its own into that walk; when instructed, it may set its bottom PR's base directly instead. -7. **Absorb drift at the root, then re-verify what moved.** The root absorbs trunk movement by restacking the chain (`gt restack`, `gt sync`); when a restack surfaces conflicts in an owner's files, that owner fixes its own slice and the root pushes the result. A restack rewrites every SHA above it and voids the verdicts at the old SHAs. Compare `git patch-id` at each verdict SHA against the new head. Anything that actually drifted goes back through step 4 before delivery. The countersign rule is unchanged from Autopilot-full. A genuinely new pin raises a stop for the root's fresh countersign; absorbing drift of landed values is not a raise. -8. **Deliver the chain.** The deliverable is one linear chain of verified PRs, reviewable bottom-up in the Graphite UI, every link carrying its verifier verdict in the PR body or a comment. The operator reviews and lands it, with her own clicks or with merge-when-ready she arms herself. +4. **Verify at STACK-READY.** The owner reports STACK-READY with the exact head SHA. The root swarm-verifies that SHA, fan-out per the **swarm** skill: parallel independent verifiers re-running the gates at that SHA, a live `verify` floor over the load-bearing behavior, and a receipts-and-diff audit that distrusts the PR body. The swarm aggregates to one verdict. Findings go back to the owner, and nothing enters the stack unverified. +5. **Append on a clean verdict, never ship.** No owner merges, arms auto-merge, or closes. A clean verdict appends the PR to the one linear stack, in verified order or an order the operator specified. +6. **Single writer on topology, parallel writers on builds.** Stack mechanics follow the repo's stack tool (commonly Graphite `gt`). An owner pushes only its own branch, `git push --force-with-lease` after an ls-remote check, and reports its tip and intended parent. The root owns stack topology and registers each append: track the parent tip, then submit the stack from the tip without interactive prompts. A worker must never pull branches below its own into a stack-wide submit walk; when instructed, it may set its bottom PR's base directly instead. +7. **Absorb drift at the root, then re-verify what moved.** The root absorbs trunk movement by restacking the chain; when a restack surfaces conflicts in an owner's files, that owner fixes its own slice and the root pushes the result. A restack rewrites every SHA above it and voids the verdicts at the old SHAs. Compare `git patch-id` at each verdict SHA against the new head. Anything that actually drifted goes back through step 4 before delivery. The countersign rule is unchanged from Autopilot-full. A genuinely new pin raises a stop for the root's fresh countersign; absorbing drift of landed values is not a raise. +8. **Deliver the chain.** The deliverable is one linear chain of verified PRs, reviewable bottom-up in the forge or stack UI, every link carrying its verifier verdict in the PR body or a comment. The operator reviews and lands it, with her own clicks or with merge-when-ready she arms herself. **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. diff --git a/skills/pstack/playbooks/orchestrate.md b/skills/pstack/playbooks/orchestrate.md index 73694d6..8f08127 100644 --- a/skills/pstack/playbooks/orchestrate.md +++ b/skills/pstack/playbooks/orchestrate.md @@ -1,6 +1,6 @@ ### Orchestrate -**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; measured head-to-head, this playbook's ceremony turned a half-hour 12-unit job into 1 landed unit while a plain agent landed all 12. Below that line, route to Autonomous run. +**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 helpers, 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; measured head-to-head, this playbook's ceremony turned a half-hour 12-unit job into 1 landed unit while a plain agent landed all 12. Below that line, route to Autonomous run. Ceremony must scale with the program. Every gate below prices in coordinator minutes; on cheap near-identical units, collapse it as each section directs rather than paying list price. @@ -14,15 +14,15 @@ Open a todolist with the steps below copied in verbatim. A step you skip stays l #### Roles and placement -- **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, restacks, 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 delegation tool. State reads and writes go through `scripts/orch/orch.ts` at drain points, one command in and one line out, to conserve context. The CLI never spawns, waits, or wakes anything. -- **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 adapter delegation schema including `environment`). 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. -- **Worker / verifier.** Always isolated/cloud worker environment when the adapter supports it unless the task needs this machine: `control-ui` or `control-cli` runtime verification (if available in this environment); reading local transcripts under `agent-transcripts/`; simulators and local IDE state; auth that exists only here. Cloud agents cannot read the local store, so their briefs inline what they need or point at repo paths. Prefer fewer, broader workers; one writer per worktree or branch (principle-separate-before-serializing-shared-state). Run a unit's verifier on a different model family from its worker. +- **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, restacks, 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. Helpers are spawned, resumed, and drained only through the active adapter's delegation tools (`parallel`, `implement`, `explore`, `review`). State reads and writes go through `scripts/orch/orch.ts` at drain points, one command in and one line out, to conserve context. The CLI never spawns, waits, or wakes anything. +- **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 carries the full adapter delegation contract including isolation or environment when the host supports it). 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. +- **Worker / verifier.** Prefer an isolated or cloud worker environment when the adapter supports it, unless the task needs this machine: `verify` on the real CLI, TUI, browser, API, or other runtime surface; reading a host-provided session or transcript resource for the current program; simulators and local IDE state; auth that exists only here. Isolated workers cannot read the local store, so their briefs inline what they need or point at repo paths. Prefer fewer, broader workers; one writer per worktree or branch (principle-separate-before-serializing-shared-state). Run a unit's verifier on a different model family from its worker when `model_role` selection is available. 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. #### Store layout -Create `orchestrate//` 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. +Create `orchestrate//` in the current agent's durable store (path from the host system prompt or adapter). 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. When the orch CLI is unavailable, keep the same file layout and update it with ordinary edits; do not invent a second schema. - `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). - `overview.md` is the durable PR and issue DB. Append; never rewrite wholesale per event. @@ -43,34 +43,34 @@ SCOPE paths this unit may write; paths it may not; its exclusive worktree CONTEXT pointers to files and PRs; upstream reports pasted in full when this unit depends on them, because workers cannot see siblings ACCEPTANCE checkable criteria, one per line -VERIFY exact commands or the control-skill path, plus known gotchas +VERIFY exact commands or the active-host verify recipe, plus known gotchas TIMEBOX rough cap on runtime; on expiry, return partial findings and stop rather than run on -FORBIDDEN no gt, no rebase, no force-push, no fixes outside scope, plus unit-specific bans +FORBIDDEN no stack surgery, no rebase, no force-push, no fixes outside scope, plus unit-specific bans REPORT status, branch, head SHA, PRs, verdict, what you actually ran, deviations, suggested follow-ups STANDING ``` -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. +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 isolated or cloud spawns and every resume. -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). +A sub-coordinator brief adds its track boundary and unit list, its spawn budget with the isolated/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). 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. #### Steps 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, because finished-but-unlanded work counts as zero. 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. -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 `. +2. **Install the runtime.** Run `orch init` when available. 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 ` or an equivalent write. 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. -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. +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. Prefer real `parallel` fan-out; collapse only when the adapter cannot spawn helpers. 5. **Drain.** Run the queue discipline below at every drain point. 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. -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. +7. **Close.** Drain the final inbox, reconcile every spawned helper 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. #### Queue and drain - On a completion notification, run `orch inbox push [--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. -- 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. +- Drain in batches at four points: the end of a critical section, a track rollup, a frontier watcher wake (arm it through the host's long-running or loop mechanism, 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. - Critical sections you finish first: authoring a brief, a stack operation, a conflict decision, writing a gate, updating ledger or frontier. - 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. - 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. @@ -78,29 +78,29 @@ A dependency is a context relay, not just ordering: undeclared upstream context #### Stack safety -- The frontier is a computed object, never narrative. Recompute `frontier.json` from `gt` after every merge and stack mutation because GitHub base refs drift mid-restack while gt tracking is authoritative: ordered PR list, branch names, head SHAs, a generation number, the lowest unmerged PR. Resolve it where gt knows the stack, normally the stacker's clone; a checkout whose gt metadata never saw the submits reports no PRs and the command errors rather than guessing. -- Exactly one stacker per stack may run `gt`, serialized within its stack; record the holder in the standing orders. Restacks run in cloud; a local restack at this scale takes the laptop down. -- Workers never rebase and never run `gt`. Babysitters follow `playbooks/babysit.md`, one per stack, scoped to one immutable frontier generation; they report conflicts to the stacker rather than restacking. +- The frontier is a computed object, never narrative. Recompute `frontier.json` from the repo's stack tool after every merge and stack mutation because forge base refs drift mid-restack while stack tracking is authoritative: ordered PR list, branch names, head SHAs, a generation number, the lowest unmerged PR. Resolve it where the stack tool knows the stack, normally the stacker's clone; a checkout whose stack metadata never saw the submits reports no PRs and the command errors rather than guessing. +- Exactly one stacker per stack may run stack mutations, serialized within its stack; record the holder in the standing orders. Prefer isolated or cloud restacks when available; a large local restack can stall the coordinator machine. +- Workers never rebase and never run stack surgery. Babysitters follow `playbooks/babysit.md`, one per stack, scoped to one immutable frontier generation; they report conflicts to the stacker rather than restacking. - 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. - One retro watcher follows merged PRs for reverts, post-merge CI breaks, and orphaned follow-ups. #### Verification -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. +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 helper (on a different model family than the worker when possible) is for units whose verification is expensive, judgment-laden, or high-blast-radius. A verifier helper whose entire product would be rerunning one command is ceremony, not verification. -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. +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 a transcript dump. -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. +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 machine when that machine dies was never done. #### Liveness and failure -- Never resume an agent to check on it; a resume restarts an idle agent. Probe read-only: the ledger, `units.tsv`, `gh`, pushed branches, the cloud agent's status in the Cursor dashboard. Transcript mtime is not liveness. +- Never resume a helper only to check on it; a resume can restart idle work. Probe read-only: the ledger, `units.tsv`, forge CLI or API, pushed branches, and any helper or cloud-worker status the active adapter exposes. Transcript mtime is not liveness. - 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. - 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. - A zombie that returns hours late reconciles against the current frontier and ledger before anything is accepted; the world moved while it slept. Salvage unique findings through a fresh unit, never a blind merge. - 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. - 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. Hours of retry loops against a dead executor produce nothing a handoff would not. -- After a Cursor restart: local agents are dead, cloud work is not. Re-read the standing orders and `units.tsv`, recompute the frontier, reattach cloud 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. +- After a coordinator session restart or context reset: local helpers are dead; isolated or cloud work may still be alive. Re-read the standing orders and `units.tsv`, recompute the frontier, reattach remote work by PR and branch rather than helper 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. #### Escalation diff --git a/skills/pstack/playbooks/shipping.md b/skills/pstack/playbooks/shipping.md index 62c0b1c..a6f86e3 100644 --- a/skills/pstack/playbooks/shipping.md +++ b/skills/pstack/playbooks/shipping.md @@ -2,19 +2,20 @@ **You own what lands. Verify each PR independently, land only the verified run from the root, then keep your hands off the queue.** For "land the stack", "ship it", "enable merge when ready", or the second half of a stack that **Babysit** already drove to green. -This is the half after `playbooks/babysit.md`. Babysit makes a stack mergeable. Shipping decides what is actually safe to merge and lets Graphite drain it. Green is not safe, and the gap between those two words is where this playbook lives. +This is the half after `playbooks/babysit.md`. Babysit makes a stack mergeable. Shipping decides what is actually safe to merge and lets the stack tool drain it. Green is not safe, and the gap between those two words is where this playbook lives. -1. **Verify every PR independently before arming anything.** One subagent per PR, not batched, each a Cursor cloud agent, each exercising the real surface (`control-ui` or `control-cli` if available in this environment as the change demands) against parent versus head. Each returns `PASS`, `PASS+NOTES` or `FAIL` and posts that verdict on its own PR so the record outlives the chat. Safe means a verdict from an agent that did not write the code. CI green is not a verdict, and an approving bot review is not a verdict. +1. **Verify every PR independently before arming anything.** One helper per PR, not batched. Prefer an isolated or cloud worker when the active adapter supports it so the verifier did not write the code. Each helper uses `verify` on the real surface the change touches (CLI, TUI, browser, API, or other runtime the adapter can drive) against parent versus head. Each returns `PASS`, `PASS+NOTES`, or `FAIL` and posts that verdict on its own PR so the record outlives the chat. Safe means a verdict from an agent that did not write the code. CI green is not a verdict, and an approving bot review is not a verdict. When isolated helpers are unavailable, run verifiers sequentially on the lead with disjoint evidence packages and state the degraded path. 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 a passing verdict, where both `PASS` and `PASS+NOTES` pass. A verified PR sitting above an unverified one is not landable, because merging it would pull the gap in underneath it. Report the ceiling as a PR number and say what breaks the chain. 3. **Re-check that the verdicts still describe the code.** A restack rewrites every SHA above it and silently invalidates every verdict without touching a single check. Compare `git patch-id` at the verdict SHA against the current head before trusting an older verdict, and re-verify anything that actually drifted. Twenty-one verdicts went stale this way in one run with no signal at all. -4. **Arm merge-when-ready through Graphite, and pass `--always`.** A no-op submit skips the Graphite update and silently arms nothing, which reads exactly like success. +4. **Arm merge-when-ready through the stack tool the repo already uses, and force a real update.** On Graphite-managed stacks: ```bash gt submit --merge-when-ready --always --update-only --no-interactive ``` -5. **Never enable GitHub auto-merge on a stack.** Only the root targets protected trunk. Every child targets its unprotected parent branch and already reads `CLEAN`, so GitHub would merge children into parents immediately and collapse the stack into itself. Graphite is what makes the merges sequential. If a previous agent armed it, disarm with `gh pr merge --disable-auto` and confirm the field is back off. -6. **Do not read `autoMergeRequest` as proof that MWR is armed.** It stays off until Graphite reaches that PR at the queue front, so an unarmed reading is meaningless and acting on it leads to re-submitting branches that were already fine. Confirm arming from Graphite's own state, and if you cannot, say so rather than inferring it. -7. **Once the queue is draining, stop touching the stack.** No `gt sync`, no restack, no speculative pushes, and no `gt submit --stack`, which reaches downstack into PRs that are mid-merge. Even a plain `gt submit` can retarget a base if local Graphite tracking has diverged, so never run `gt` from a worktree whose parentage you have not just checked. Independent work gets re-parented onto trunk and shipped on its own. -8. **Watch the drain, do not drive it.** Arm the watcher in queued mode over the verified run and hold it under `long-runlong-run/loop` in dynamic mode, re-armed after any verdict you act on, until COMPLETE at the ceiling. ADVANCE is progress, not termination. Bases retarget and `graphite-base/*` refs get cut as each PR merges; that is Graphite working, not damage. Report each merge and the new ceiling. If the queue stalls, diagnose before mutating, because a stalled queue and a broken stack look identical from the outside. + A no-op submit skips the stack update and silently arms nothing, which reads exactly like success. On repos without Graphite, use the forge's sequential merge-queue or merge-when-ready equivalent and confirm the arming from that tool's own state. +5. **Never enable forge auto-merge on a mid-stack child.** Only the root targets protected trunk. Every child targets its unprotected parent branch and already reads mergeable, so forge auto-merge would merge children into parents immediately and collapse the stack into itself. The stack tool is what makes the merges sequential. If a previous agent armed forge auto-merge, disarm it and confirm the field is back off. +6. **Do not read a forge auto-merge field as proof that merge-when-ready is armed.** It often stays off until the queue reaches that PR, so an unarmed reading is meaningless and acting on it leads to re-submitting branches that were already fine. Confirm arming from the stack tool's own state, and if you cannot, say so rather than inferring it. +7. **Once the queue is draining, stop touching the stack.** No speculative sync, restack, or stack-wide submit that reaches downstack into PRs that are mid-merge. Even a plain stack submit can retarget a base if local tracking has diverged, so never run stack mutations from a worktree whose parentage you have not just checked. Independent work gets re-parented onto trunk and shipped on its own. +8. **Watch the drain, do not drive it.** Arm a watcher over the verified run through the host's long-running or loop mechanism when available; otherwise poll with a bounded cadence. Re-arm after any verdict you act on until COMPLETE at the ceiling. ADVANCE is progress, not termination. Bases retarget and temporary stack refs get cut as each PR merges; that is the stack tool working, not damage. Report each merge and the new ceiling. If the queue stalls, diagnose before mutating, because a stalled queue and a broken stack look identical from the outside. 9. **Stop at the ceiling.** When the verified run is merged, report what landed, what the next unverified PR is, and what verifying it would take. Extending the run is a new pass through step 1, not a judgment call you make at 3am. **Reply:** the verified run and its ceiling, each PR's verdict and who produced it, what you armed and how you confirmed it, what landed, and what the next gap needs. From 67ce7d8d5492002c29b34952df3371c457873c9e Mon Sep 17 00:00:00 2001 From: Go7hic Date: Sat, 8 Aug 2026 12:37:49 +0800 Subject: [PATCH 3/4] Make arena and interrogate capability-first. Rewrite the multi-candidate and adversarial-review skills around portable verbs, model roles, and explicit host fallbacks so they match the hardened how/swarm baseline. Co-authored-by: Cursor --- skills/arena/SKILL.md | 68 ++++++++-------- skills/interrogate/SKILL.md | 150 +++++++++++++++++------------------- 2 files changed, 109 insertions(+), 109 deletions(-) diff --git a/skills/arena/SKILL.md b/skills/arena/SKILL.md index 6c31e12..76d1d27 100644 --- a/skills/arena/SKILL.md +++ b/skills/arena/SKILL.md @@ -9,21 +9,20 @@ compatibility: Works with Agent Skills-compatible coding agents. Multi-agent opt ## Portability (required) -This skill is part of the portable **pstack** pack for multiple coding agents. +This skill is part of the portable **pstack** pack. -1. Read `pstack` skill `references/capability-contract.md` (or this skill's `references/capability-contract.md` if present). -2. Detect the runtime and read one adapter before any delegation: - - Cursor → `references/adapters/cursor.md` (under the `pstack` or `poteto-mode` skill) - - Codex → `references/adapters/codex.md` - - Anything else / unsure → `references/adapters/generic.md` -3. Translate upstream Cursor mechanics through the adapter. Do **not** invent Cursor `Task` / `poteto-agent` / model slugs on runtimes that lack them. -4. If multi-agent tools are unavailable, collapse parallel work onto the main agent and say so briefly. - -Capability verbs: `explore`, `implement`, `review`, `parallel`, `ask_user`, `verify`, `model_role`. +1. Read the `pstack` capability contract and the adapter for the active coding agent before delegation. +2. Use `parallel` with `implement` helpers for writable candidates, `review` for the cross-judge, and `verify` for the synthesized result. +3. Keep candidate write scopes disjoint (worktrees or separate output directories). Never let N candidates share one mutable path. +4. Resolve models through `model_role`; never require a vendor-specific model identifier or helper type. +5. When helper spawning is unavailable, run candidates sequentially on the lead agent, keep their outputs separated, and state that the arena collapsed. +## Purpose Fan out N parallel attempts at the same task. Read every candidate end to end. Pick the strongest as the base. Graft the best ideas from the others into it. Verify the synthesized result. +Use **swarm** when the goal is independent coverage or aggregation. Use **arena** when the goal is one synthesized artifact chosen from competing candidates. + ## Start Open a todolist with one entry per phase before launching anything. The arena runs autonomously and the list keeps phases from silently disappearing. @@ -37,16 +36,23 @@ Open a todolist with one entry per phase before launching anything. The arena ru ## Phase A: Frame -The N candidates will receive the same prompt, so the prompt is the contract. Get it right before spawning anything. +The N candidates receive the same prompt, so the prompt is the contract. Get it right before spawning anything. 1. State the artifact each candidate is producing. -2. Derive the rubric. State what success looks like for *this* task, then turn it into 3-6 concrete gradeable criteria. Concrete: `Adds a --dry-run flag that skips writes`. Vague: `code is correct`. The rubric is the picker's tool in Phase D; candidates only see the task. -3. Pick the runners. Use `arena runners` from the pstack model override file when present. Otherwise default to diverse `model_role:critic` / judgment runners across available model families. Spawn more when the arena covers multiple design directions. Same model N times when the work is generation-bound rather than judgment-sensitive. -4. Assign output paths. Each candidate writes to its own location (a git worktree where possible, otherwise `/tmp/arena-/candidate-/`). N candidates writing to the same path is shared mutable state and fails the the **separate-before-serializing-shared-state** principle skill test. +2. Derive the rubric. State what success looks like for *this* task, then turn it into 3–6 concrete gradeable criteria. Concrete: `Adds a --dry-run flag that skips writes`. Vague: `code is correct`. The rubric is the picker's tool in Phase D; candidates only see the task. +3. Pick the runners. Prefer the `arena runners` list from the local pstack model override file when present. Otherwise use diverse `model_role:critic` and `model_role:judgment` runners across available model families. Spawn more candidates when the arena covers multiple design directions. Use the same role N times only when the work is generation-bound rather than judgment-sensitive. +4. Assign output paths. Each candidate writes to its own location (a git worktree when the adapter supports isolation, otherwise a dedicated directory such as `/tmp/arena-/candidate-/`). Shared mutable output fails the **separate-before-serializing-shared-state** principle. ## Phase B: Fan out -Spawn all N subagents in one message with non-blocking delegation when supported, each with the task, the path to the shared grounding, its own output path, and instructions to produce both the artifact and a short rationale. +Use `parallel` to launch all N candidates in one turn when the host supports it. Each helper receives: + +- the shared task prompt; +- pointers to shared grounding evidence; +- its exclusive output path; +- instructions to produce both the artifact and a short rationale. + +Prefer `implement` for candidates that must write code or files. Prefer `explore` only when the artifact is a read-only design package that must not edit the repo. Pass non-blocking delegation only when the active adapter supports it and the lead continues non-overlapping work. The rationale is mandatory. Without it, the parent cannot tell whether a candidate's structure is principled or accidental, which makes Phase E grafting unreliable. Each rationale names the alternatives the candidate considered and what it rejected. @@ -54,7 +60,9 @@ If a candidate fails to produce output, proceed with N-1 and note the dropout in ## Phase C: Cross-judge -After all Phase B candidates complete, choose one model from the `arena cross-judge pool` in the pstack model override file when present. Otherwise use diverse available judgment/critic models via `model_role`. Prefer a different model family from the parent's. Spawn one readonly judge subagent on that model. It sees the rubric and the candidates by path label, scores each criterion, and recommends a base with rationale. It runs in parallel with the parent's reading in Phase D, not with the candidates themselves. Spawning while candidates are still writing means the judge sees partial or empty outputs and reports them as dropouts. +After all Phase B candidates complete, choose one model through the `arena cross-judge pool` in the override file when present; otherwise use `model_role:judgment` or `model_role:critic`, preferring a different model family from the lead when the adapter supports selection. + +Spawn one read-only `review` helper. It sees the rubric and the candidates by path label, scores each criterion, and recommends a base with rationale. Run it in parallel with the lead's own reading in Phase D, not while candidates are still writing. Judging partial outputs creates false dropouts. ## Phase D: Pick a base @@ -62,40 +70,38 @@ Read every candidate end to end before picking. Skimming N candidates surfaces o Score each candidate against the rubric criterion by criterion, not on holistic feel. Compare against the cross-judge. Agreement on the base confirms the pick. Disagreement means one of you is biased or the rubric was ambiguous. Read both rationales before deciding. -Pick the base on which candidate a future maintainer can extend most easily without breaking invariants. Prefer the cleaner boundary or smaller surface area when two feel tied, per the Laziness Protocol. +Pick the base on which a future maintainer can extend most easily without breaking invariants. Prefer the cleaner boundary or smaller surface area when two feel tied, per the Laziness Protocol. -Record the pick and the reason in a short synthesis note alongside the base artifact, including the cross-judge's verdict. +Record the pick and the reason in a short synthesis note alongside the base artifact, including the cross-judge's verdict. The lead owns the final pick. ## Phase E: Graft Walk each losing candidate once more and identify what is worth porting into the base. The signal is usually one or two things per candidate, not most of it. -Fold each graft in by hand, per the **redesign-from-first-principles** principle skill. Don't paste mechanically. The result has to remain coherent under one mental model. +Fold each graft in by hand, per the **redesign-from-first-principles** principle. Do not paste mechanically. The result has to remain coherent under one mental model. Record what was grafted, from which candidate, and what was rejected and why. The rejection notes are the highest-signal part of the record. Future readers learn from what you considered and dropped, not just what you kept. -When N candidates converge on the same shape, that is a strong agreement signal. Note the convergence in the record and ship the consensus shape. No graft is needed. When N candidates wildly diverge, Phase A was under-specified. Reframe and re-run rather than averaging the divergence. +When N candidates converge on the same shape, that is a strong agreement signal. Note the convergence and ship the consensus shape; no graft is needed. When N candidates wildly diverge, Phase A was under-specified. Reframe and re-run rather than averaging the divergence. ## Phase F: Verify -The synthesized artifact has to hold up under the same scrutiny as any other output, per the **prove-it-works** principle skill. The arena does not earn you a pass. +The synthesized artifact has to hold up under the same scrutiny as any other output, per the **prove-it-works** principle. The arena does not earn a pass. -If verification surfaces a problem the arena did not catch, either Phase A was wrong (re-frame and re-run) or one candidate caught it and you missed the graft (go back to Phase E). Don't paper over. +Use `verify` on the narrowest meaningful real surface. If verification surfaces a problem the arena did not catch, either Phase A was wrong (re-frame and re-run) or one candidate caught it and you missed the graft (return to Phase E). Do not paper over. ## Outputs -One synthesized artifact. One short synthesis note alongside, naming the base, the grafts (with source candidate), the rejections, the dropouts if any, and the verification result. +One synthesized artifact. One short synthesis note alongside it, naming the base, the grafts (with source candidate), the rejections, the dropouts if any, and the verification result. ## Model roles -Do not hard-require Cursor model slugs. Resolve models through `model_role` and the active adapter: - | Role | Use | | --- | --- | -| `fast_explore` | Broad read-only fan-out, mechanical edits | -| `feature_impl` | Spec-driven implementation / refactoring | -| `bug_impl` | High-stakes fixes after evidence | -| `judgment` | Architecture, synthesis, prose | -| `critic` | Adversarial / panel review | +| `fast_explore` | mechanical or generation-bound candidate work | +| `feature_impl` | spec-driven implementation candidates | +| `bug_impl` | evidence-backed fix candidates | +| `judgment` | synthesis, base selection support, prose artifacts | +| `critic` | diverse candidates and cross-judge pressure | -If a local override file exists, prefer it. If a slug is unavailable, fall back to the parent model and say so. +If no role override is available, inherit the parent session model and say so. diff --git a/skills/interrogate/SKILL.md b/skills/interrogate/SKILL.md index fa1334c..56c2074 100644 --- a/skills/interrogate/SKILL.md +++ b/skills/interrogate/SKILL.md @@ -9,135 +9,129 @@ compatibility: Works with Agent Skills-compatible coding agents. Multi-agent opt ## Portability (required) -This skill is part of the portable **pstack** pack for multiple coding agents. +This skill is part of the portable **pstack** pack. -1. Read `pstack` skill `references/capability-contract.md` (or this skill's `references/capability-contract.md` if present). -2. Detect the runtime and read one adapter before any delegation: - - Cursor → `references/adapters/cursor.md` (under the `pstack` or `poteto-mode` skill) - - Codex → `references/adapters/codex.md` - - Anything else / unsure → `references/adapters/generic.md` -3. Translate upstream Cursor mechanics through the adapter. Do **not** invent Cursor `Task` / `poteto-agent` / model slugs on runtimes that lack them. -4. If multi-agent tools are unavailable, collapse parallel work onto the main agent and say so briefly. +1. Read the `pstack` capability contract and the adapter for the active coding agent before delegation. +2. Use `parallel` with read-only `review` helpers for the reviewer panel. Keep synthesis and final categorization on the lead agent. +3. Resolve reviewer models through `model_role` or the host override file. Never require a vendor-specific model identifier. +4. Do not auto-apply reviewer suggestions. The deliverable is a synthesized verdict. +5. When helper spawning or model selection is unavailable, run the same rubric sequentially on the lead agent, keep notes separate until synthesis, and state the degraded path. -Capability verbs: `explore`, `implement`, `review`, `parallel`, `ask_user`, `verify`, `model_role`. +## Purpose +Spawn independent reviewers to adversarially review code changes. Each reviewer gets the same prompt and rubric. The adversarial signal comes from model diversity, not assigned personas. Models differ in blind spots, priors, and reasoning patterns. Agreement across models is high-confidence signal; lone-model findings are worth reading but lower confidence. -Spawn one reviewer per configured model to adversarially review code changes. Each model gets the same prompt and rubric. The adversarial signal comes from model diversity, not assigned personas. Models differ in blind spots, priors, and reasoning patterns. Agreement across models is high-confidence signal; lone-model findings are worth reading but lower confidence. - -The deliverable is a synthesized verdict. Do NOT auto-apply changes. - -## Step 1, Determine Scope +## Step 1: Decide scope Identify what to review from context: -- If the user points at specific files or a diff, use that -- If on a feature branch, run `git diff main...HEAD` (or the appropriate base branch) for the full changeset -- If the user's message references recent work, gather the relevant files +- If the user points at specific files or a diff, use that. +- If on a feature branch, run `git diff ...HEAD` for the full changeset. +- If the user's message references recent work, gather the relevant files. -Package the diff (or file contents) plus any surrounding context files the reviewers need to understand the code. +Package the diff or file contents plus any surrounding context the reviewers need. Prefer path pointers over dumping large files into every prompt when helpers can read the workspace. -## Step 2, State the Intent +## Step 2: State the intent Before spawning reviewers, state the intent explicitly. What is this code trying to accomplish? Derive this from: -- The user's message -- Commit messages -- PR description if one exists -- The code itself +- the user's message; +- commit messages; +- PR description if one exists; +- the code itself. -Write one clear paragraph. Reviewers challenge whether the work achieves the intent well, not whether the intent itself is correct. If you're unsure about the intent, ask the user before proceeding. +Write one clear paragraph. Reviewers challenge whether the work achieves the intent well, not whether the intent itself is correct. If the intent is ambiguous in a way that would change the review, use `ask_user` once; otherwise state the best current reading and proceed. -## Step 3, Spawn Reviewers +## Step 3: Spawn reviewers -Launch all reviewers in a single message via `parallel` + adapter helpers. Use the `interrogate reviewers` list from the pstack model override file when present, one reviewer per entry; otherwise use the table defaults. +Use `parallel` to launch the reviewer panel in one turn when the host supports it. Prefer the `interrogate reviewers` list from the local pstack model override file when present, one reviewer per entry. Otherwise use this default panel: -| Subagent | Default role | -|----------|---------------| -| Reviewer A | `judgment` | -| Reviewer B | `bug_impl` / strong reasoning | -| Reviewer C | `fast_explore` | -| Reviewer D | `critic` (different family when possible) | +| Reviewer | Model role | +| --- | --- | +| A | `judgment` | +| B | `bug_impl` | +| C | `fast_explore` | +| D | `critic` (different family when possible) | -For each reviewer: -- adapter `explore` / `review` helper -- `model` / `model_role`: the configured `interrogate reviewers` entry, or the table default -- read-only (`explore`) +Every helper is a read-only `review` worker. Instruct each helper not to edit files or post external comments. -If a model slug is rejected as unresolvable when you try to spawn the subagent, check the valid slugs in the delegation tool's error message, pick the closest equivalent (prefer the highest-reasoning tier of the same family), spawn with the valid slug, and open a separate PR to update the configured value or default table. Do not block the review on the slug issue. If the configured value is `inherit-parent` or `auto`, omit `model` instead; never treat those aliases as broken slugs or enter this fallback for them. +If a configured model cannot be resolved by the active adapter, pick the closest available equivalent (prefer the strongest reasoning tier in the same family), continue the review, and note the substitution. Open a separate follow-up to fix the override file. Values such as `inherit-parent` or `auto` mean omit an explicit model and inherit the parent session. -Read `references/reviewer-prompt.md` and fill in the template with: -1. The stated intent -2. The diff or file contents -3. The review rubric from `references/rubric.md` -4. The code-quality lens from `references/code-quality-review.md` +Read `references/reviewer-prompt.md` and fill the template with: -The same filled template goes to all reviewers, so every model applies the code-quality lens. +1. the stated intent; +2. the diff or file contents / path pointers; +3. the review rubric from `references/rubric.md`; +4. the code-quality lens from `references/code-quality-review.md`. -Each reviewer produces structured findings as described in the prompt template. +The same filled template goes to all reviewers. Each reviewer returns structured findings as described in the prompt template. -## Step 4, Synthesize +## Step 4: Synthesize As results come back, build a unified picture: -1. **Parse all findings** from the reviewers -2. **Identify consensus**. Findings raised by 2+ models independently are highest signal. -3. **Identify lone-model findings**. Still worth reading, but weight accordingly. -4. **Deduplicate**. Different models may describe the same issue differently. Merge these and note which models raised it. -5. **Note disagreements**. If one model flags something and another explicitly says the opposite, that's useful context for the verdict. +1. Parse all findings from the reviewers. +2. Identify consensus. Findings raised by 2+ reviewers independently are highest signal. +3. Identify lone-model findings. Still worth reading, but weight accordingly. +4. Deduplicate. Different models may describe the same issue differently. Merge these and note which reviewers raised it. +5. Note disagreements. If one reviewer flags something and another explicitly says the opposite, keep that tension in the verdict. -## Step 5, Lead Judgment +## Step 5: Lead judgment -You are the lead reviewer, a pragmatic senior engineer, not a neutral aggregator. +The lead is a pragmatic senior engineer, not a neutral aggregator. -Read `references/lead-judgment.md` for the full framework. Reviewers only see a slice of the codebase. You have the full context (the goal, the constraints, the timeline, which tradeoffs were already considered). Use that context aggressively. +Read `references/lead-judgment.md` for the full framework. Reviewers only see a slice of the codebase. The lead has the full context: goal, constraints, timeline, and tradeoffs already considered. Use that context aggressively. -Categorize every finding using these buckets: +Categorize every finding: -- **Act on**. Real issues affecting correctness, security, or maintainability given the actual goals. These would block a real PR. -- **Consider**. Legitimate points, but you're not sure they outweigh the cost of addressing them right now. Worth the user's attention. -- **Noted**. Technically valid but not actionable. Context-dependent, premature optimization, or low-impact given the current stage. -- **Dismissed**. Wrong, nitpicky, or missing context. Brief explanation why. +- **Act on.** Real issues affecting correctness, security, or maintainability given the actual goals. These would block a real PR. +- **Consider.** Legitimate points, but it is unclear they outweigh the cost of addressing them right now. Worth the user's attention. +- **Noted.** Technically valid but not actionable now. Context-dependent, premature, or low-impact. +- **Dismissed.** Wrong, nitpicky, or missing context. Brief explanation why. -For each finding, include: -- Which model(s) raised it -- The category (act on / consider / noted / dismissed) -- A one-line rationale for the categorization +For each finding include: -## Output Format +- which reviewer(s) raised it; +- the category; +- a one-line rationale for the categorization. -Present the verdict in this structure: +## Output format ### Intent + > [The stated intent paragraph from Step 2] ### Reviewers -- Reviewer [label]: [model name], [N findings] (one bullet per reviewer) + +- Reviewer [label]: [model role or resolved model], [N findings] ### Act On -[Findings that should be addressed. For each: description, which models raised it, why it matters.] + +Findings that should be addressed. For each: description, which reviewers raised it, why it matters. ### Consider -[Findings worth thinking about. For each: description, which models raised it, tradeoff involved.] + +Findings worth thinking about. For each: description, which reviewers raised it, tradeoff involved. ### Noted -[Valid but low-priority. Brief list.] + +Valid but low-priority. Brief list. ### Dismissed -[Rejected findings with brief rationale. This shows the user what was filtered out and why, so they can override your judgment if they disagree.] + +Rejected findings with brief rationale so the user can override the lead judgment. ### Agreement Map -[Where did models agree, where did they diverge, and what does the pattern of agreement/disagreement tell us?] -## Model roles +Where reviewers agreed, where they diverged, and what the pattern implies. -Do not hard-require Cursor model slugs. Resolve models through `model_role` and the active adapter: +## Model roles | Role | Use | | --- | --- | -| `fast_explore` | Broad read-only fan-out, mechanical edits | -| `feature_impl` | Spec-driven implementation / refactoring | -| `bug_impl` | High-stakes fixes after evidence | -| `judgment` | Architecture, synthesis, prose | -| `critic` | Adversarial / panel review | +| `fast_explore` | breadth and mechanical inconsistency hunting | +| `bug_impl` | correctness and failure-mode pressure | +| `judgment` | architecture and maintainability judgment | +| `critic` | adversarial / panel diversity | -If a local override file exists, prefer it. If a slug is unavailable, fall back to the parent model and say so. +If no role override is available, inherit the parent session model and say so. From 3a1cf57319670b4b292b82448d9efe823bf431ce Mon Sep 17 00:00:00 2001 From: Go7hic Date: Sat, 8 Aug 2026 12:54:45 +0800 Subject: [PATCH 4/4] Close remaining in-repo portable conformance debt from issue #2. Replace thin leaf portability blocks and runtime pointers, harden the import pipeline with idempotent reports, add upstream/mirror/contract/lifecycle scaffolding, and clear leftover playbook rewrite artifacts under one audit-clean pass. Co-authored-by: Cursor --- .gitignore | 3 + CONTRIBUTING.md | 47 ++- README.md | 5 +- UPSTREAM_MANIFEST.json | 29 ++ docs/guide/01-setup.md | 6 +- scripts/audit_portability.py | 20 + scripts/fixtures/conformance/HOST_MATRIX.md | 17 + scripts/fixtures/model-override/valid.json | 10 + .../portability/bad/cursor-app-support.md | 1 + .../fixtures/portability/bad/doubled-loop.md | 1 + .../portability/bad/doubled-surface.md | 1 + .../portability/bad/restart-cursor.md | 1 + .../portability/bad/thin-portability-block.md | 1 + scripts/fixtures/semantic/REVIEW_CHECKLIST.md | 20 + scripts/import_upstream.py | 103 +++++ scripts/port_to_portable.py | 395 ++++++++++-------- scripts/sync_mirrors.py | 38 ++ scripts/validate_model_override.py | 81 ++++ skills/architect/references/runtime.md | 13 +- skills/arena/references/runtime.md | 13 +- skills/automate-me/references/runtime.md | 13 +- skills/blast-radius/SKILL.md | 16 +- skills/blast-radius/references/runtime.md | 13 +- skills/bro/SKILL.md | 15 +- skills/bro/references/runtime.md | 13 +- skills/create-verification-skill/SKILL.md | 16 +- .../references/runtime.md | 13 +- skills/figure-it-out/SKILL.md | 16 +- skills/figure-it-out/references/runtime.md | 13 +- skills/how/references/runtime.md | 13 +- skills/interrogate/references/runtime.md | 13 +- skills/maintain-verification-skill/SKILL.md | 16 +- .../references/runtime.md | 13 +- skills/no-comments/SKILL.md | 16 +- skills/no-comments/references/runtime.md | 13 +- .../poteto-mode/playbooks/autonomous-run.md | 2 +- skills/poteto-mode/playbooks/bug-fix.md | 10 +- skills/poteto-mode/playbooks/feature.md | 4 +- skills/poteto-mode/playbooks/pause-safely.md | 4 +- skills/poteto-mode/playbooks/prototype.md | 2 +- skills/poteto-mode/playbooks/refactoring.md | 4 +- .../playbooks/runtime-forensics.md | 4 +- .../poteto-mode/playbooks/trace-forensics.md | 2 +- skills/poteto-mode/playbooks/visual-parity.md | 2 +- .../poteto-mode/playbooks/worktree-cleanup.md | 8 +- .../references/capability-contract.md | 39 +- skills/principle-boundary-discipline/SKILL.md | 16 +- .../references/runtime.md | 13 +- skills/principle-build-the-lever/SKILL.md | 16 +- .../references/runtime.md | 13 +- .../SKILL.md | 16 +- .../references/runtime.md | 13 +- .../SKILL.md | 16 +- .../references/runtime.md | 13 +- skills/principle-experience-first/SKILL.md | 16 +- .../references/runtime.md | 13 +- skills/principle-fix-root-causes/SKILL.md | 16 +- .../references/runtime.md | 13 +- .../principle-foundational-thinking/SKILL.md | 16 +- .../references/runtime.md | 13 +- .../SKILL.md | 16 +- .../references/runtime.md | 13 +- skills/principle-laziness-protocol/SKILL.md | 16 +- .../references/runtime.md | 13 +- .../SKILL.md | 16 +- .../references/runtime.md | 13 +- .../SKILL.md | 16 +- .../references/runtime.md | 13 +- .../principle-minimize-reader-load/SKILL.md | 16 +- .../references/runtime.md | 13 +- skills/principle-model-the-domain/SKILL.md | 16 +- .../references/runtime.md | 13 +- .../SKILL.md | 16 +- .../references/runtime.md | 13 +- .../SKILL.md | 16 +- .../references/runtime.md | 13 +- skills/principle-prove-it-works/SKILL.md | 16 +- .../references/runtime.md | 13 +- .../SKILL.md | 16 +- .../references/runtime.md | 13 +- .../SKILL.md | 16 +- .../references/runtime.md | 13 +- .../SKILL.md | 16 +- .../references/runtime.md | 13 +- .../SKILL.md | 16 +- .../references/runtime.md | 13 +- .../principle-type-system-discipline/SKILL.md | 16 +- .../references/runtime.md | 13 +- skills/pstack/SKILL.md | 4 +- skills/pstack/playbooks/autonomous-run.md | 2 +- skills/pstack/playbooks/bug-fix.md | 10 +- skills/pstack/playbooks/feature.md | 4 +- skills/pstack/playbooks/pause-safely.md | 4 +- skills/pstack/playbooks/prototype.md | 2 +- skills/pstack/playbooks/refactoring.md | 4 +- skills/pstack/playbooks/runtime-forensics.md | 4 +- skills/pstack/playbooks/trace-forensics.md | 2 +- skills/pstack/playbooks/visual-parity.md | 2 +- skills/pstack/playbooks/worktree-cleanup.md | 8 +- .../pstack/references/agents/comment-sicko.md | 40 -- .../pstack/references/agents/poteto-agent.md | 16 - .../pstack/references/capability-contract.md | 39 +- skills/pstack/references/host-lifecycle.md | 25 ++ .../references/model-override.schema.json | 44 ++ skills/pstack/references/workflow-quality.md | 32 ++ skills/recall/references/runtime.md | 13 +- skills/reflect/references/runtime.md | 13 +- skills/setup-pstack/references/runtime.md | 13 +- .../show-me-your-work/references/runtime.md | 13 +- skills/swarm/references/runtime.md | 13 +- skills/tdd/SKILL.md | 16 +- skills/tdd/references/runtime.md | 13 +- skills/teach/SKILL.md | 16 +- skills/teach/references/runtime.md | 13 +- skills/technical-writing/SKILL.md | 16 +- .../technical-writing/references/runtime.md | 13 +- skills/typescript-best-practices/SKILL.md | 16 +- .../references/runtime.md | 13 +- skills/unslop/SKILL.md | 16 +- skills/unslop/references/runtime.md | 13 +- skills/why/references/runtime.md | 13 +- 121 files changed, 1128 insertions(+), 1044 deletions(-) create mode 100644 UPSTREAM_MANIFEST.json create mode 100644 scripts/fixtures/conformance/HOST_MATRIX.md create mode 100644 scripts/fixtures/model-override/valid.json create mode 100644 scripts/fixtures/portability/bad/cursor-app-support.md create mode 100644 scripts/fixtures/portability/bad/doubled-loop.md create mode 100644 scripts/fixtures/portability/bad/doubled-surface.md create mode 100644 scripts/fixtures/portability/bad/restart-cursor.md create mode 100644 scripts/fixtures/portability/bad/thin-portability-block.md create mode 100644 scripts/fixtures/semantic/REVIEW_CHECKLIST.md create mode 100644 scripts/import_upstream.py create mode 100644 scripts/sync_mirrors.py create mode 100644 scripts/validate_model_override.py create mode 100644 skills/pstack/references/host-lifecycle.md create mode 100644 skills/pstack/references/model-override.schema.json create mode 100644 skills/pstack/references/workflow-quality.md diff --git a/.gitignore b/.gitignore index 5636e63..a498cd7 100644 --- a/.gitignore +++ b/.gitignore @@ -8,3 +8,6 @@ node_modules/ *~ .migration-backup/ + +__pycache__/ +*.pyc diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 7896b1b..bdac540 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -10,31 +10,32 @@ ## Layout and sources of truth - Installable skills live under `skills//SKILL.md` and follow the Agent Skills layout used by skills.sh. -- Shared runtime contracts live under `skills/pstack/references/{capability-contract.md,adapters/,agents/}`. -- `skills/poteto-mode/playbooks/` is the canonical playbook directory. Mirror it to `skills/pstack/playbooks/` after edits. -- `skills/pstack/references/adapters/` is the canonical adapter directory. Mirror it to `skills/poteto-mode/references/adapters/` after edits. -- `skills/pstack/references/capability-contract.md` is canonical. Keep the copy under `skills/poteto-mode/references/` byte-identical. -- Agent rubrics and `principles-summary.md` exist only under `skills/pstack/references/`; they are not mirrored into `poteto-mode`. +- Shared runtime contracts live under `skills/pstack/references/{capability-contract.md,adapters/,agents/,host-lifecycle.md,model-override.schema.json}`. +- `skills/poteto-mode/playbooks/` is the canonical playbook directory. +- `skills/pstack/references/adapters/` is the canonical adapter directory. +- `skills/pstack/references/capability-contract.md` is canonical. +- Agent rubrics, `principles-summary.md`, `host-lifecycle.md`, and the model-override schema exist only under `skills/pstack/references/`. Do not edit both sides of a mirror independently. The portable audit rejects drift. -## Re-port helpers - -After pulling newer upstream Cursor pstack sources: +## Import and mirrors ```bash -# Copy upstream skills, then run the mechanical passes. -python3 scripts/port_to_portable.py -python3 scripts/port_pass2.py - -# Refresh mirrors from their canonical directories. -rsync -a --delete skills/poteto-mode/playbooks/ skills/pstack/playbooks/ -rsync -a --delete skills/pstack/references/adapters/ skills/poteto-mode/references/adapters/ -cp skills/pstack/references/capability-contract.md \ - skills/poteto-mode/references/capability-contract.md +# Preferred: import an upstream checkout, run both passes, refresh mirrors. +python3 scripts/import_upstream.py --upstream-root /path/to/cursor/plugins/pstack \ + --upstream-commit + +# Or refresh mirrors only after local playbook/adapter edits. +python3 scripts/sync_mirrors.py + +# Mechanical first pass only (targeted phrases; no bare-word Task replace). +python3 scripts/port_to_portable.py --report /tmp/port-report.json +python3 scripts/port_to_portable.py --check-idempotent ``` -Adapters, `setup-pstack`, and portable entry skills are hand-maintained. Do not blindly overwrite them from upstream. +Hand-maintained entry skills and adapters are listed in `UPSTREAM_MANIFEST.json`. Do not overwrite them from upstream. + +After import, complete `scripts/fixtures/semantic/REVIEW_CHECKLIST.md` before merging. ## Required audit @@ -42,8 +43,10 @@ Run this before every pull request: ```bash python3 -m compileall -q scripts +python3 scripts/sync_mirrors.py python3 scripts/audit_portability.py python3 scripts/audit_portability.py --strict --changed-from origin/main +python3 scripts/validate_model_override.py scripts/fixtures/model-override/valid.json ``` The baseline audit checks: @@ -52,10 +55,10 @@ The baseline audit checks: - the complete playbook and adapter inventories; - byte-identical playbook, adapter, and capability-contract mirrors; - Cursor-only frontmatter keys; -- portability smells such as concrete Cursor model slugs, `subagent_type`, `AskQuestion`, Cursor filesystem assumptions, `control-cli` / `control-ui`, `agent-transcripts`, Cursor cloud/dashboard workflows, and ambiguous mechanical-rewrite wording; +- portability smells (vendor fields, Cursor paths/control surfaces, thin mechanical blocks, rewrite artifacts); - regression fixtures under `scripts/fixtures/portability/` for every portability pattern. -The non-strict repository-wide scan reports existing portability debt as warnings. Known remaining debt after the portable baseline includes long-running playbooks such as Orchestrate, Shipping, and Autopilot; treat new warnings as work for issue #2 rather than suppressing patterns. The strict changed-file scan prevents a pull request from adding or preserving those patterns in files it touches. +Repository-wide non-strict audit should stay at `0 error(s), 0 warning(s)` unless a finding is intentionally introduced and tracked. The strict changed-file scan rejects regressions in files a PR touches. ## Semantic review after mechanical porting @@ -70,6 +73,10 @@ Regex passes are only the first step. Review every changed skill for meaning: A mechanically valid sentence can still be semantically wrong. Phrases such as “`explore` / `implement` helper” are a sign that the port has not chosen the actual capability. +## Host conformance + +Live host results belong in `scripts/fixtures/conformance/HOST_MATRIX.md`. CI does not run remote agents; fill the matrix after smoke tests on each supported host. + ## skills.sh - The `description` frontmatter field is the trigger surface and must stay quoted for reliable parsing. diff --git a/README.md b/README.md index de8629b..3e93c04 100644 --- a/README.md +++ b/README.md @@ -49,11 +49,12 @@ The repository contains a structural and portability audit: ```bash python3 scripts/audit_portability.py python3 scripts/audit_portability.py --strict --changed-from origin/main +python3 scripts/sync_mirrors.py ``` -GitHub Actions runs the structural audit on `main` and on pull requests. It also rejects new vendor leakage in changed files, including concrete Cursor model slugs, Cursor-only tool fields, transcript paths, and drift between mirrored playbooks or adapters. +GitHub Actions runs the structural audit on `main` and on pull requests. It also rejects new vendor leakage in changed files, including concrete Cursor model slugs, Cursor-only tool fields, transcript paths, thin mechanical portability blocks, rewrite artifacts, and drift between mirrored playbooks or adapters. -See [CONTRIBUTING.md](./CONTRIBUTING.md) before syncing a newer upstream revision. Mechanical regex porting is followed by a semantic review; capability verbs must describe the actual job rather than merely replacing vendor vocabulary. +See [CONTRIBUTING.md](./CONTRIBUTING.md) and [UPSTREAM_MANIFEST.json](./UPSTREAM_MANIFEST.json) before syncing a newer upstream revision. Mechanical regex porting is followed by a semantic review; capability verbs must describe the actual job rather than merely replacing vendor vocabulary. ## Not bundled diff --git a/UPSTREAM_MANIFEST.json b/UPSTREAM_MANIFEST.json new file mode 100644 index 0000000..0772a32 --- /dev/null +++ b/UPSTREAM_MANIFEST.json @@ -0,0 +1,29 @@ +{ + "schema_version": 1, + "upstream": { + "repository": "https://github.com/cursor/plugins", + "path": "pstack", + "commit": "UNPINNED", + "synced_at": null, + "notes": "Pin commit SHA on each upstream import. Do not auto-merge sync PRs." + }, + "portable": { + "patch_version": "0.2.0", + "capability_contract_version": "1.0.0", + "hand_maintained_skills": [ + "pstack", + "poteto-mode", + "how", + "why", + "architect", + "arena", + "swarm", + "interrogate", + "reflect", + "recall", + "automate-me", + "show-me-your-work", + "setup-pstack" + ] + } +} diff --git a/docs/guide/01-setup.md b/docs/guide/01-setup.md index 42abc37..8ec32e9 100644 --- a/docs/guide/01-setup.md +++ b/docs/guide/01-setup.md @@ -19,7 +19,7 @@ The official plugin has native mode metadata and Cursor-specific integrations th Install the portable pack globally: ```bash -npx skills add https://skills.sh/p/3EVEFJjSrRBr1mI4 -g -s '*' -y +npx skills add Go7hic/pstack -g -s '*' -y ``` To install only for selected agents, add one or more `-a` flags as described in [INSTALL.md](../../INSTALL.md). Restart or reload the coding agent after installation so it rescans its skill directories. @@ -80,10 +80,10 @@ On a broad subsystem, confirm the adapter fans out several read-only explorers. ## Understand mode lifetime -Cursor's official plugin can provide native sticky-mode behavior. Other coding agents vary: +See `skills/pstack/references/host-lifecycle.md` for the host-by-host matrix. - When the host preserves skill state, `/poteto-mode` can remain active across turns in the current conversation. - When the host does not provide persistent mode state, invoke `/pstack` or `/poteto-mode` again after a new session, context reset, or compaction. -- The playbooks and engineering principles remain the same; only the lifecycle mechanism changes. +- Never claim sticky mode on a host that cannot enforce it. Next: [Route work through `/poteto-mode`](./02-poteto-mode.md). diff --git a/scripts/audit_portability.py b/scripts/audit_portability.py index e337dbd..b9fb05c 100644 --- a/scripts/audit_portability.py +++ b/scripts/audit_portability.py @@ -101,6 +101,26 @@ "ambiguous generated model role", re.compile(r"model_role:fast_explore\s*/\s*feature_impl", re.I), ), + ( + "thin mechanical portability block", + re.compile(r"Translate upstream Cursor mechanics through the adapter"), + ), + ( + "doubled loop rewrite artifact", + re.compile(r"long-runlong-run"), + ), + ( + "doubled matching-surface rewrite artifact", + re.compile(r"matching surface on the matching"), + ), + ( + "Cursor app support path", + re.compile(r"Application Support/Cursor"), + ), + ( + "Cursor restart trigger wording", + re.compile(r"restart Cursor", re.I), + ), ) SCAN_EXCLUDES = ( diff --git a/scripts/fixtures/conformance/HOST_MATRIX.md b/scripts/fixtures/conformance/HOST_MATRIX.md new file mode 100644 index 0000000..1e7f2d2 --- /dev/null +++ b/scripts/fixtures/conformance/HOST_MATRIX.md @@ -0,0 +1,17 @@ +# Host conformance matrix + +These are smoke expectations for portable pstack. Mark results only after a live host run. In-repo CI does not execute remote agents. + +| Case | Claude Code | Codex | OpenCode | Droid | Generic + spawn | Generic no spawn | +| --- | --- | --- | --- | --- | --- | --- | +| `/how` simple: no unnecessary fan-out | | | | | | | +| `/how` complex: 2–4 explorers | | | | | | | +| `/arena`: isolated candidates, cross-judge, graft, verify | | | | | | | +| `/interrogate`: independent reviewers + lead judgment | | | | | | | +| Feature: disjoint worker scope + lead diff review | | | | | | | +| Bug fix: reproduce, root cause, fix, same-surface verify | | | | | | | +| Denied model selection degrades to parent model | | | | | | | +| Denied spawn collapses to lead and is stated | | | | | | | +| No invented tool params from another host | | | | | | | + +Fill cells with `pass`, `pass-degraded:`, or `fail:`. diff --git a/scripts/fixtures/model-override/valid.json b/scripts/fixtures/model-override/valid.json new file mode 100644 index 0000000..673462a --- /dev/null +++ b/scripts/fixtures/model-override/valid.json @@ -0,0 +1,10 @@ +{ + "schema_version": 1, + "roles": { + "fast_explore": "inherit-parent", + "feature_impl": "auto", + "bug_impl": "inherit-parent", + "judgment": "inherit-parent", + "critic": "inherit-parent" + } +} diff --git a/scripts/fixtures/portability/bad/cursor-app-support.md b/scripts/fixtures/portability/bad/cursor-app-support.md new file mode 100644 index 0000000..bb17d58 --- /dev/null +++ b/scripts/fixtures/portability/bad/cursor-app-support.md @@ -0,0 +1 @@ +Clear `~/Library/Application Support/Cursor` caches. diff --git a/scripts/fixtures/portability/bad/doubled-loop.md b/scripts/fixtures/portability/bad/doubled-loop.md new file mode 100644 index 0000000..4a3509c --- /dev/null +++ b/scripts/fixtures/portability/bad/doubled-loop.md @@ -0,0 +1 @@ +Use `long-runlong-run/loop` until done. diff --git a/scripts/fixtures/portability/bad/doubled-surface.md b/scripts/fixtures/portability/bad/doubled-surface.md new file mode 100644 index 0000000..07124f9 --- /dev/null +++ b/scripts/fixtures/portability/bad/doubled-surface.md @@ -0,0 +1 @@ +Verify on the matching surface on the matching real surface. diff --git a/scripts/fixtures/portability/bad/restart-cursor.md b/scripts/fixtures/portability/bad/restart-cursor.md new file mode 100644 index 0000000..253fd2a --- /dev/null +++ b/scripts/fixtures/portability/bad/restart-cursor.md @@ -0,0 +1 @@ +Pause when asked to restart Cursor. diff --git a/scripts/fixtures/portability/bad/thin-portability-block.md b/scripts/fixtures/portability/bad/thin-portability-block.md new file mode 100644 index 0000000..b5b1d75 --- /dev/null +++ b/scripts/fixtures/portability/bad/thin-portability-block.md @@ -0,0 +1 @@ +3. Translate upstream Cursor mechanics through the adapter. Do not invent Cursor Task. diff --git a/scripts/fixtures/semantic/REVIEW_CHECKLIST.md b/scripts/fixtures/semantic/REVIEW_CHECKLIST.md new file mode 100644 index 0000000..8bd7d06 --- /dev/null +++ b/scripts/fixtures/semantic/REVIEW_CHECKLIST.md @@ -0,0 +1,20 @@ +# Semantic review checklist + +After an upstream import, review these skills by hand before merging: + +- [ ] `how` +- [ ] `why` +- [ ] `architect` +- [ ] `arena` +- [ ] `swarm` +- [ ] `interrogate` +- [ ] `reflect` +- [ ] `poteto-mode` + +For each skill, confirm: + +1. Capability verbs name the actual job (`explore` vs `implement` vs `review`). +2. No vendor tool fields remain outside adapters. +3. Model selection goes through `model_role` or the override file. +4. Missing spawn / model selection / verify surfaces degrade explicitly. +5. Prompt templates under `references/` match the skill body. diff --git a/scripts/import_upstream.py b/scripts/import_upstream.py new file mode 100644 index 0000000..570b0dd --- /dev/null +++ b/scripts/import_upstream.py @@ -0,0 +1,103 @@ +#!/usr/bin/env python3 +"""Import an upstream Cursor pstack checkout into this portable pack. + +Usage: + python3 scripts/import_upstream.py --upstream-root /path/to/cursor/plugins/pstack + +The importer copies skill markdown, runs both portable passes, refreshes mirrors, +writes a transform report, and prints a semantic-review checklist. It never +auto-commits and never overwrites hand-maintained entry skills or adapters. +""" + +from __future__ import annotations + +import argparse +import json +import shutil +import subprocess +import sys +from datetime import datetime, timezone +from pathlib import Path + +ROOT = Path(__file__).resolve().parents[1] +MANIFEST = ROOT / "UPSTREAM_MANIFEST.json" + +HAND_MAINTAINED = set( + json.loads(MANIFEST.read_text(encoding="utf-8"))["portable"]["hand_maintained_skills"] +) + + +def copy_upstream_skills(upstream_root: Path) -> list[str]: + src_skills = upstream_root / "skills" + if not src_skills.is_dir(): + # Cursor plugin layout may keep skills at repo root of the pstack plugin. + candidates = [upstream_root] + else: + candidates = [src_skills] + + copied: list[str] = [] + for base in candidates: + for skill_md in sorted(base.glob("*/SKILL.md")): + name = skill_md.parent.name + if name in HAND_MAINTAINED: + continue + dest = ROOT / "skills" / name + if dest.exists(): + shutil.rmtree(dest) + shutil.copytree(skill_md.parent, dest) + copied.append(name) + return copied + + +def run(cmd: list[str]) -> None: + completed = subprocess.run(cmd, cwd=ROOT, check=False) + if completed.returncode != 0: + raise SystemExit(completed.returncode) + + +def update_manifest(commit: str | None) -> None: + data = json.loads(MANIFEST.read_text(encoding="utf-8")) + data["upstream"]["synced_at"] = datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ") + if commit: + data["upstream"]["commit"] = commit + MANIFEST.write_text(json.dumps(data, indent=2) + "\n", encoding="utf-8") + + +def main() -> int: + parser = argparse.ArgumentParser(description=__doc__) + parser.add_argument("--upstream-root", type=Path, required=True) + parser.add_argument("--upstream-commit", default=None) + parser.add_argument( + "--report", + type=Path, + default=ROOT / "scripts" / "fixtures" / "last-import-report.json", + ) + args = parser.parse_args() + upstream_root = args.upstream_root.expanduser().resolve() + if not upstream_root.exists(): + print(f"ERROR: upstream root missing: {upstream_root}", file=sys.stderr) + return 2 + + copied = copy_upstream_skills(upstream_root) + print(f"copied {len(copied)} upstream skill directories (hand-maintained skipped)") + run( + [ + sys.executable, + str(ROOT / "scripts" / "port_to_portable.py"), + "--report", + str(args.report), + ] + ) + run([sys.executable, str(ROOT / "scripts" / "sync_mirrors.py")]) + update_manifest(args.upstream_commit) + + checklist = ROOT / "scripts" / "fixtures" / "semantic" / "REVIEW_CHECKLIST.md" + print("\nSemantic review checklist:") + print(checklist.read_text(encoding="utf-8")) + print(f"\nTransform report: {args.report}") + print("Do not auto-merge. Open a draft PR after human review.") + return 0 + + +if __name__ == "__main__": + raise SystemExit(main()) diff --git a/scripts/port_to_portable.py b/scripts/port_to_portable.py index 2dca584..c2b40ef 100644 --- a/scripts/port_to_portable.py +++ b/scripts/port_to_portable.py @@ -1,10 +1,21 @@ #!/usr/bin/env python3 -"""Port Cursor pstack markdown to runtime-agnostic Agent Skills.""" +"""Import upstream Cursor pstack markdown into portable Agent Skills form. + +This pass is intentionally conservative. It never performs a bare-word ``Task`` +replacement. Hand-maintained entry skills and adapters are skipped. Run +``scripts/port_pass2.py`` afterward, then ``scripts/audit_portability.py``. +""" from __future__ import annotations +import argparse +import json import re +import subprocess +import sys +from dataclasses import asdict, dataclass from pathlib import Path +from typing import Iterable ROOT = Path(__file__).resolve().parents[1] SKILLS = ROOT / "skills" @@ -12,17 +23,12 @@ PORTABILITY_BLOCK = """ ## Portability (required) -This skill is part of the portable **pstack** pack for multiple coding agents. - -1. Read `pstack` skill `references/capability-contract.md` (or this skill's `references/capability-contract.md` if present). -2. Detect the runtime and read one adapter before any delegation: - - Cursor → `references/adapters/cursor.md` (under the `pstack` or `poteto-mode` skill) - - Codex → `references/adapters/codex.md` - - Anything else / unsure → `references/adapters/generic.md` -3. Translate upstream Cursor mechanics through the adapter. Do **not** invent Cursor `Task` / `poteto-agent` / model slugs on runtimes that lack them. -4. If multi-agent tools are unavailable, collapse parallel work onto the main agent and say so briefly. +This skill is part of the portable **pstack** pack. -Capability verbs: `explore`, `implement`, `review`, `parallel`, `ask_user`, `verify`, `model_role`. +1. Read the `pstack` capability contract and the adapter for the active coding agent before any helper delegation. +2. Prefer capability verbs (`explore`, `implement`, `review`, `parallel`, `ask_user`, `verify`, `model_role`) over vendor tool names. +3. Resolve models through `model_role`. Never require a vendor-specific model identifier. +4. When helper spawning is unavailable, run the work on the lead agent and state that fan-out was collapsed. """.strip() CURSOR_ONLY_FRONTMATTER = { @@ -34,121 +40,110 @@ "is_background", } -# Order matters: longer / more specific first. -REPLACEMENTS: list[tuple[str, str]] = [ +# Hand-maintained portable sources. Never overwrite these from upstream import. +HAND_MAINTAINED_SKILLS = { + "pstack", + "poteto-mode", + "how", + "why", + "architect", + "arena", + "swarm", + "interrogate", + "reflect", + "recall", + "automate-me", + "show-me-your-work", + "setup-pstack", +} + +HAND_MAINTAINED_PATH_PREFIXES = ( + "skills/pstack/references/adapters/", + "skills/poteto-mode/references/adapters/", + "skills/pstack/references/capability-contract.md", + "skills/poteto-mode/references/capability-contract.md", + "skills/pstack/references/agents/", + "skills/pstack/references/model-override.schema.json", + "skills/pstack/references/host-lifecycle.md", +) + +# Targeted phrase transforms only. Order: longer / more specific first. +REPLACEMENTS: tuple[tuple[str, str, str], ...] = ( ( + "poteto-agent-subagent", r"`subagent_type:\s*\"?poteto-agent\"?`", - "`implement` / `explore` helper via the active adapter (poteto-style worker if available)", - ), - ( - r"subagent_type:\s*[\"']poteto-agent[\"']", - "adapter worker / explore helper (poteto-style if available)", + "an `implement` helper using the Poteto worker rubric", ), ( + "comment-sicko-subagent", r"`subagent_type:\s*\"?Comment Sicko\"?`", - "`review` helper with the Comment Sicko rubric (`pstack` → `references/agents/comment-sicko.md`)", - ), - ( - r"subagent_type:\s*[\"']Comment Sicko[\"']", - "Comment Sicko review helper via adapter", + "a `review` helper using the Comment Sicko rubric", ), ( - r"`subagent_type`:\s*`generalPurpose`", - "adapter `explore` / `implement` helper", + "generalPurpose-subagent", + r"`?subagent_type`?\s*:\s*[\"']?generalPurpose[\"']?", + "a helper selected by the active adapter", ), ( - r"subagent_type:\s*[\"']generalPurpose[\"']", - "adapter explore/implement helper", + "explore-subagent", + r"`?subagent_type`?\s*:\s*[\"']?explore[\"']?", + "an `explore` helper selected by the active adapter", ), ( - r"subagent_type:\s*[\"']explore[\"']", - "adapter `explore` helper", + "readonly-true", + r"`?readonly`?\s*:\s*`?true`?", + "read-only intent enforced by the adapter and prompt", ), ( - r"`readonly`:\s*`true`", - "read-only (`explore`)", + "run-in-background-true", + r"`?run_in_background`?\s*:\s*`?true`?", + "non-blocking delegation when the active adapter supports it", ), + ("ask-question", r"\bAskQuestion\b", "`ask_user`"), ( - r"readonly:\s*`?true`?", - "read-only (`explore`)", - ), - ( - r"`run_in_background`:\s*`true`", - "non-blocking delegation when the adapter supports it", - ), - ( - r"run_in_background:\s*`?true`?", - "non-blocking delegation when supported", - ), - ( - r"\bAskQuestion\b", - "`ask_user`", + "cursor-loop", + r"Cursor's `/loop` command", + "the host's long-running or loop mechanism when available", ), ( - r"Cursor's `/loop` command", - "the agent's long-running / loop mechanism if available, otherwise continue autonomously", + "slash-loop", + r"`/loop`", + "the host's long-running or loop mechanism", ), ( + "cursor-skill-authoring", r"Cursor's built-in for authoring SKILL\.md files", - "your agent's skill-authoring guidance", + "the active coding agent's skill-authoring workflow", ), ( + "deslop-plugin", r"the `deslop` skill from the `cursor-team-kit` plugin \(`/deslop`\)", - "a local deslop / cleanup pass if available; otherwise apply `unslop` + simplicity review before commit", - ), - ( - r"`cursor-team-kit` publishes `control-cli` \(for CLIs and TUIs\) and `control-ui` \(for browser / Electron / web UIs\)", - "use the best available control surface for CLI/TUI or browser/UI verification in this runtime", - ), - ( - r"Shipping UI / IDE / CLI → the matching control skill\. `cursor-team-kit` publishes `control-cli` \(for CLIs and TUIs\) and `control-ui` \(for browser, Electron, web UIs\)\. ", - "Shipping UI / IDE / CLI → verify on the real control surface available in this runtime. ", - ), - ( - r"Spawn all explorers in a single message:", - "Spawn explorers via `parallel` + `explore` (one message if the adapter supports fan-out):", - ), - ( - r"spawn a single Task subagent", - "spawn a single `explore`/`implement` helper via the adapter", - ), - ( - r"Spawn a single Task subagent", - "Spawn a single `explore`/`implement` helper via the adapter", - ), - ( - r"\bTask subagent\b", - "adapter helper", - ), - ( - r"\bTask call\b", - "adapter delegation call", - ), - ( - r"every `Task` call", - "every adapter delegation call", - ), - ( - r"\bTask` call", - "adapter` delegation call", - ), - ( - r"via `Task`", - "via the adapter", - ), - ( - r"using `Task`", - "using the adapter", - ), - ( - r"\bTask tool\b", - "delegation tool", + "a local simplicity and cleanup pass, followed by `unslop` for prose", ), ( - r"(? str: + return path.relative_to(ROOT).as_posix() + + +def is_hand_maintained(path: Path) -> bool: + rel = relative(path) + if path.name == "SKILL.md" and path.parent.name in HAND_MAINTAINED_SKILLS: + return True + return any(rel.startswith(prefix) or rel == prefix.rstrip("/") for prefix in HAND_MAINTAINED_PATH_PREFIXES) def split_frontmatter(text: str) -> tuple[str | None, str]: @@ -171,8 +166,7 @@ def clean_frontmatter(fm: str, skill_dir_name: str) -> str: i += 1 continue if line.startswith(" ") or line.startswith("\t"): - # continuation of previous kept key — only keep if last kept was not skipped - if out and not out[-1].startswith("#SKIP#"): + if out: out.append(line) i += 1 continue @@ -183,16 +177,12 @@ def clean_frontmatter(fm: str, skill_dir_name: str) -> str: i += 1 continue if key == "name": - # Normalize name to directory name (agentskills: lowercase hyphen) - value = line.split(":", 1)[1].strip().strip("\"'") - # Keep directory name as canonical package name out.append(f"name: {skill_dir_name}") i += 1 continue out.append(line) i += 1 - # Ensure license/compatibility hints blob = "\n".join(out) if "license:" not in blob: out.append("license: MIT") @@ -203,90 +193,169 @@ def clean_frontmatter(fm: str, skill_dir_name: str) -> str: return "\n".join(out).strip() + "\n" -def apply_replacements(body: str) -> str: - for pattern, repl in REPLACEMENTS: - body = re.sub(pattern, repl, body) +def apply_replacements(body: str, path: Path, report: list[Transform]) -> str: + for rule, pattern, repl in REPLACEMENTS: + new_body, count = re.subn(pattern, repl, body) + if count: + report.append(Transform(relative(path), rule, count)) + body = new_body return body def ensure_portability(body: str) -> str: if "## Portability (required)" in body: return body - # Insert after first H1 if present, else at top - m = re.search(r"^# .+$", body, re.M) - if m: - insert_at = m.end() + match = re.search(r"^# .+$", body, re.M) + if match: + insert_at = match.end() return body[:insert_at] + "\n\n" + PORTABILITY_BLOCK + "\n" + body[insert_at:] return PORTABILITY_BLOCK + "\n\n" + body -def port_skill_md(path: Path) -> bool: +def port_skill_md(path: Path, report: list[Transform], write: bool) -> bool: + if is_hand_maintained(path): + return False original = path.read_text(encoding="utf-8") fm, body = split_frontmatter(original) skill_dir_name = path.parent.name - if fm is None: - body = apply_replacements(original) + body = apply_replacements(original, path, report) body = ensure_portability(body) new = body else: new_fm = clean_frontmatter(fm, skill_dir_name) - body = apply_replacements(body) + body = apply_replacements(body, path, report) body = ensure_portability(body.lstrip("\n")) new = f"---\n{new_fm}---\n\n{body.lstrip()}" - - if new != original: + if new == original: + return False + if write: path.write_text(new, encoding="utf-8") - return True - return False + return True -def port_plain_md(path: Path) -> bool: +def port_plain_md(path: Path, report: list[Transform], write: bool) -> bool: + if is_hand_maintained(path): + return False + if path.name in {"capability-contract.md", "host-lifecycle.md"}: + return False + if "references/adapters/" in relative(path): + return False original = path.read_text(encoding="utf-8") - # Skip our adapter/contract files from destructive Task word replaces if already portable - if path.name in {"capability-contract.md", "generic.md", "cursor.md", "codex.md"}: + new = apply_replacements(original, path, report) + if new == original: return False - if "Portability (required)" in original and path.name == "SKILL.md": - pass - new = apply_replacements(original) - if new != original: + if write: path.write_text(new, encoding="utf-8") - return True - return False - - -def main() -> None: - skill_changed = 0 - md_changed = 0 - for skill_md in sorted(SKILLS.glob("*/SKILL.md")): - if port_skill_md(skill_md): - skill_changed += 1 - print(f"ported skill: {skill_md.parent.name}") - for md in sorted(SKILLS.rglob("*.md")): - if md.name == "SKILL.md": - continue - if port_plain_md(md): - md_changed += 1 - print(f"ported md: {md.relative_to(ROOT)}") - # Agent reference prompts - agents = ROOT / "skills" / "pstack" / "references" / "agents" - if agents.exists(): - for md in agents.glob("*.md"): - if port_plain_md(md) or True: - text = md.read_text(encoding="utf-8") - fm, body = split_frontmatter(text) - if fm is not None: - new_fm = clean_frontmatter(fm, md.stem) - body = apply_replacements(body) - body = ( - body - if "## Portability" in body - else ensure_portability(body.lstrip("\n")) + return True + + +def collect_targets() -> list[Path]: + skills = sorted(SKILLS.glob("*/SKILL.md")) + others = sorted( + path + for path in SKILLS.rglob("*.md") + if path.name != "SKILL.md" and path.is_file() + ) + return skills + others + + +def run_port(write: bool) -> tuple[list[str], list[Transform]]: + changed: list[str] = [] + report: list[Transform] = [] + for path in collect_targets(): + if path.name == "SKILL.md": + did = port_skill_md(path, report, write=write) + else: + did = port_plain_md(path, report, write=write) + if did: + changed.append(relative(path)) + return changed, report + + +def run_audit() -> int: + completed = subprocess.run( + [sys.executable, str(ROOT / "scripts" / "audit_portability.py"), "--strict"], + cwd=ROOT, + check=False, + ) + return completed.returncode + + +def parse_args(argv: Iterable[str]) -> argparse.Namespace: + parser = argparse.ArgumentParser(description=__doc__) + parser.add_argument( + "--dry-run", + action="store_true", + help="report transforms without writing files", + ) + parser.add_argument( + "--check-idempotent", + action="store_true", + help="fail if a second dry-run pass would still change files", + ) + parser.add_argument( + "--report", + type=Path, + help="write a machine-readable JSON transform report", + ) + parser.add_argument( + "--skip-audit", + action="store_true", + help="do not run the strict portability audit after writing", + ) + return parser.parse_args(list(argv)) + + +def main(argv: Iterable[str] = sys.argv[1:]) -> int: + args = parse_args(argv) + write = not args.dry_run and not args.check_idempotent + changed, report = run_port(write=write) + + if args.check_idempotent: + # First apply for real, then dry-run must be empty. + changed, report = run_port(write=True) + second, second_report = run_port(write=False) + if second: + print("ERROR: import pipeline is not idempotent", file=sys.stderr) + for path in second: + print(f" would change again: {path}", file=sys.stderr) + if args.report: + args.report.write_text( + json.dumps( + { + "changed": second, + "transforms": [asdict(item) for item in second_report], + }, + indent=2, ) - md.write_text(f"---\n{new_fm}---\n\n{body.lstrip()}", encoding="utf-8") - print(f"ported agent ref: {md.name}") - print(f"done. skills={skill_changed} other_md={md_changed}") + + "\n", + encoding="utf-8", + ) + return 1 + print("idempotent: second pass would change 0 files") + + payload = { + "changed": changed, + "transforms": [asdict(item) for item in report], + } + if args.report: + args.report.write_text(json.dumps(payload, indent=2) + "\n", encoding="utf-8") + + print(f"port_to_portable: {len(changed)} file(s) changed, {len(report)} transform(s)") + for path in changed: + print(f" {path}") + + if write and not args.skip_audit: + pass2 = ROOT / "scripts" / "port_pass2.py" + if pass2.is_file(): + subprocess.run([sys.executable, str(pass2)], cwd=ROOT, check=False) + code = run_audit() + if code != 0: + print("ERROR: strict audit failed after import", file=sys.stderr) + return code + return 0 if __name__ == "__main__": - main() + raise SystemExit(main()) diff --git a/scripts/sync_mirrors.py b/scripts/sync_mirrors.py new file mode 100644 index 0000000..a75f639 --- /dev/null +++ b/scripts/sync_mirrors.py @@ -0,0 +1,38 @@ +#!/usr/bin/env python3 +"""Refresh byte-identical mirrors from their canonical directories.""" + +from __future__ import annotations + +import shutil +import sys +from pathlib import Path + +ROOT = Path(__file__).resolve().parents[1] + + +def sync_dir(src: Path, dest: Path) -> None: + if not src.is_dir(): + raise SystemExit(f"missing source directory: {src}") + if dest.exists(): + shutil.rmtree(dest) + shutil.copytree(src, dest) + + +def main() -> int: + sync_dir( + ROOT / "skills" / "poteto-mode" / "playbooks", + ROOT / "skills" / "pstack" / "playbooks", + ) + sync_dir( + ROOT / "skills" / "pstack" / "references" / "adapters", + ROOT / "skills" / "poteto-mode" / "references" / "adapters", + ) + contract_src = ROOT / "skills" / "pstack" / "references" / "capability-contract.md" + contract_dest = ROOT / "skills" / "poteto-mode" / "references" / "capability-contract.md" + shutil.copy2(contract_src, contract_dest) + print("synced playbooks, adapters, and capability-contract mirrors") + return 0 + + +if __name__ == "__main__": + raise SystemExit(main()) diff --git a/scripts/validate_model_override.py b/scripts/validate_model_override.py new file mode 100644 index 0000000..88e6b67 --- /dev/null +++ b/scripts/validate_model_override.py @@ -0,0 +1,81 @@ +#!/usr/bin/env python3 +"""Validate a pstack model override document against the portable schema.""" + +from __future__ import annotations + +import argparse +import json +import re +import sys +from pathlib import Path + +ROOT = Path(__file__).resolve().parents[1] +SCHEMA_PATH = ROOT / "skills" / "pstack" / "references" / "model-override.schema.json" +KNOWN_ROLES = {"fast_explore", "feature_impl", "bug_impl", "judgment", "critic"} +ALIAS = {"inherit-parent", "auto"} + + +def load_override(path: Path) -> dict: + text = path.read_text(encoding="utf-8") + if path.suffix in {".json"}: + return json.loads(text) + # Markdown override files: extract fenced JSON or simple `role: value` lines. + fence = re.search(r"```json\n(.*?)\n```", text, re.S) + if fence: + return json.loads(fence.group(1)) + roles: dict[str, str] = {} + for line in text.splitlines(): + match = re.match(r"`?([a-z_]+)`?\s*:\s*`?([^`]+)`?\s*$", line.strip()) + if match and match.group(1) in KNOWN_ROLES: + roles[match.group(1)] = match.group(2).strip() + return {"schema_version": 1, "roles": roles} + + +def validate(data: dict) -> list[str]: + errors: list[str] = [] + schema = json.loads(SCHEMA_PATH.read_text(encoding="utf-8")) + if data.get("schema_version") != schema["properties"]["schema_version"]["const"]: + errors.append("schema_version must be 1") + roles = data.get("roles", {}) + if not isinstance(roles, dict): + errors.append("roles must be an object") + return errors + for key, value in roles.items(): + if key not in KNOWN_ROLES: + errors.append(f"unknown role {key!r}") + if not isinstance(value, str) or not value.strip(): + errors.append(f"role {key!r} needs a non-empty string") + elif value.strip() in ALIAS: + continue + for key in ("arena_runners", "arena_cross_judge_pool", "interrogate_reviewers"): + value = data.get(key) + if value is None: + continue + if not isinstance(value, list) or not all(isinstance(item, str) and item.strip() for item in value): + errors.append(f"{key} must be a list of non-empty strings") + unknown = set(data) - {"schema_version", "roles", "arena_runners", "arena_cross_judge_pool", "interrogate_reviewers"} + for key in sorted(unknown): + errors.append(f"unknown top-level key {key!r}") + return errors + + +def main() -> int: + parser = argparse.ArgumentParser(description=__doc__) + parser.add_argument("path", type=Path, help="override file (.json or markdown with role lines)") + args = parser.parse_args() + try: + data = load_override(args.path.expanduser()) + except Exception as exc: # noqa: BLE001 - CLI surface + print(f"ERROR: {exc}", file=sys.stderr) + return 2 + errors = validate(data) + if errors: + for error in errors: + print(f"ERROR: {error}") + return 1 + print(f"ok: {args.path}") + return 0 + + +if __name__ == "__main__": + raise SystemExit(main()) diff --git a/skills/architect/references/runtime.md b/skills/architect/references/runtime.md index df0e238..d9172df 100644 --- a/skills/architect/references/runtime.md +++ b/skills/architect/references/runtime.md @@ -3,12 +3,7 @@ Before any multi-agent step, read the sibling **pstack** skill: 1. `pstack/references/capability-contract.md` -2. Matching adapter under `pstack/references/adapters/`: - - `claude-code.md` — Claude Code (`Agent` / `Task`) - - `droid.md` — Factory Droid (`Task`) - - `opencode.md` — OpenCode (`task` → explore/general/…) - - `codex.md` (+ `codex-models.md`) — OpenAI Codex / replaces codex-pstack - - `cursor.md` — Cursor (prefer official pstack plugin there) - - `generic.md` — unknown host (still parallelize if a spawn tool exists) - -If the `pstack` skill is missing, use whatever `Agent`/`Task`/`task` tool the host exposes with disjoint scopes; otherwise execute locally. +2. The matching adapter under `pstack/references/adapters/` for the active host (`claude-code`, `codex`, `droid`, `opencode`, `cursor`, or `generic`). + +Map capability verbs through that adapter. Do not invent tool parameters from another host. If spawning is unavailable, execute on the lead agent and say so. + diff --git a/skills/arena/references/runtime.md b/skills/arena/references/runtime.md index df0e238..d9172df 100644 --- a/skills/arena/references/runtime.md +++ b/skills/arena/references/runtime.md @@ -3,12 +3,7 @@ Before any multi-agent step, read the sibling **pstack** skill: 1. `pstack/references/capability-contract.md` -2. Matching adapter under `pstack/references/adapters/`: - - `claude-code.md` — Claude Code (`Agent` / `Task`) - - `droid.md` — Factory Droid (`Task`) - - `opencode.md` — OpenCode (`task` → explore/general/…) - - `codex.md` (+ `codex-models.md`) — OpenAI Codex / replaces codex-pstack - - `cursor.md` — Cursor (prefer official pstack plugin there) - - `generic.md` — unknown host (still parallelize if a spawn tool exists) - -If the `pstack` skill is missing, use whatever `Agent`/`Task`/`task` tool the host exposes with disjoint scopes; otherwise execute locally. +2. The matching adapter under `pstack/references/adapters/` for the active host (`claude-code`, `codex`, `droid`, `opencode`, `cursor`, or `generic`). + +Map capability verbs through that adapter. Do not invent tool parameters from another host. If spawning is unavailable, execute on the lead agent and say so. + diff --git a/skills/automate-me/references/runtime.md b/skills/automate-me/references/runtime.md index df0e238..d9172df 100644 --- a/skills/automate-me/references/runtime.md +++ b/skills/automate-me/references/runtime.md @@ -3,12 +3,7 @@ Before any multi-agent step, read the sibling **pstack** skill: 1. `pstack/references/capability-contract.md` -2. Matching adapter under `pstack/references/adapters/`: - - `claude-code.md` — Claude Code (`Agent` / `Task`) - - `droid.md` — Factory Droid (`Task`) - - `opencode.md` — OpenCode (`task` → explore/general/…) - - `codex.md` (+ `codex-models.md`) — OpenAI Codex / replaces codex-pstack - - `cursor.md` — Cursor (prefer official pstack plugin there) - - `generic.md` — unknown host (still parallelize if a spawn tool exists) - -If the `pstack` skill is missing, use whatever `Agent`/`Task`/`task` tool the host exposes with disjoint scopes; otherwise execute locally. +2. The matching adapter under `pstack/references/adapters/` for the active host (`claude-code`, `codex`, `droid`, `opencode`, `cursor`, or `generic`). + +Map capability verbs through that adapter. Do not invent tool parameters from another host. If spawning is unavailable, execute on the lead agent and say so. + diff --git a/skills/blast-radius/SKILL.md b/skills/blast-radius/SKILL.md index 8d4f4ac..152b538 100644 --- a/skills/blast-radius/SKILL.md +++ b/skills/blast-radius/SKILL.md @@ -9,18 +9,12 @@ compatibility: Works with Agent Skills-compatible coding agents. Multi-agent opt ## Portability (required) -This skill is part of the portable **pstack** pack for multiple coding agents. - -1. Read `pstack` skill `references/capability-contract.md` (or this skill's `references/capability-contract.md` if present). -2. Detect the runtime and read one adapter before any delegation: - - Cursor → `references/adapters/cursor.md` (under the `pstack` or `poteto-mode` skill) - - Codex → `references/adapters/codex.md` - - Anything else / unsure → `references/adapters/generic.md` -3. Translate upstream Cursor mechanics through the adapter. Do **not** invent Cursor `Task` / `poteto-agent` / model slugs on runtimes that lack them. -4. If multi-agent tools are unavailable, collapse parallel work onto the main agent and say so briefly. - -Capability verbs: `explore`, `implement`, `review`, `parallel`, `ask_user`, `verify`, `model_role`. +This skill is part of the portable **pstack** pack. +1. Read the `pstack` capability contract and the adapter for the active coding agent before any helper delegation. +2. Prefer capability verbs (`explore`, `implement`, `review`, `parallel`, `ask_user`, `verify`, `model_role`) over vendor tool names. +3. Resolve models through `model_role`. Never require a vendor-specific model identifier. +4. When helper spawning is unavailable, run the work on the lead agent and state that fan-out was collapsed. Find what a change breaks somewhere else, before it ships. Use for "blast radius of X", "what could this break", or reviewing a small diff you don't trust yet. diff --git a/skills/blast-radius/references/runtime.md b/skills/blast-radius/references/runtime.md index df0e238..d9172df 100644 --- a/skills/blast-radius/references/runtime.md +++ b/skills/blast-radius/references/runtime.md @@ -3,12 +3,7 @@ Before any multi-agent step, read the sibling **pstack** skill: 1. `pstack/references/capability-contract.md` -2. Matching adapter under `pstack/references/adapters/`: - - `claude-code.md` — Claude Code (`Agent` / `Task`) - - `droid.md` — Factory Droid (`Task`) - - `opencode.md` — OpenCode (`task` → explore/general/…) - - `codex.md` (+ `codex-models.md`) — OpenAI Codex / replaces codex-pstack - - `cursor.md` — Cursor (prefer official pstack plugin there) - - `generic.md` — unknown host (still parallelize if a spawn tool exists) - -If the `pstack` skill is missing, use whatever `Agent`/`Task`/`task` tool the host exposes with disjoint scopes; otherwise execute locally. +2. The matching adapter under `pstack/references/adapters/` for the active host (`claude-code`, `codex`, `droid`, `opencode`, `cursor`, or `generic`). + +Map capability verbs through that adapter. Do not invent tool parameters from another host. If spawning is unavailable, execute on the lead agent and say so. + diff --git a/skills/bro/SKILL.md b/skills/bro/SKILL.md index 0775dce..901e025 100644 --- a/skills/bro/SKILL.md +++ b/skills/bro/SKILL.md @@ -7,16 +7,11 @@ compatibility: Works with Agent Skills-compatible coding agents. Multi-agent opt ## Portability (required) -This skill is part of the portable **pstack** pack for multiple coding agents. +This skill is part of the portable **pstack** pack. -1. Read `pstack` skill `references/capability-contract.md` (or this skill's `references/capability-contract.md` if present). -2. Detect the runtime and read one adapter before any delegation: - - Cursor → `references/adapters/cursor.md` (under the `pstack` or `poteto-mode` skill) - - Codex → `references/adapters/codex.md` - - Anything else / unsure → `references/adapters/generic.md` -3. Translate upstream Cursor mechanics through the adapter. Do **not** invent Cursor `Task` / `poteto-agent` / model slugs on runtimes that lack them. -4. If multi-agent tools are unavailable, collapse parallel work onto the main agent and say so briefly. - -Capability verbs: `explore`, `implement`, `review`, `parallel`, `ask_user`, `verify`, `model_role`. +1. Read the `pstack` capability contract and the adapter for the active coding agent before any helper delegation. +2. Prefer capability verbs (`explore`, `implement`, `review`, `parallel`, `ask_user`, `verify`, `model_role`) over vendor tool names. +3. Resolve models through `model_role`. Never require a vendor-specific model identifier. +4. When helper spawning is unavailable, run the work on the lead agent and state that fan-out was collapsed. Restate your last message. Stop using jargon and speak coherently. State it more simply and concisely, like one human talking to another. diff --git a/skills/bro/references/runtime.md b/skills/bro/references/runtime.md index df0e238..d9172df 100644 --- a/skills/bro/references/runtime.md +++ b/skills/bro/references/runtime.md @@ -3,12 +3,7 @@ Before any multi-agent step, read the sibling **pstack** skill: 1. `pstack/references/capability-contract.md` -2. Matching adapter under `pstack/references/adapters/`: - - `claude-code.md` — Claude Code (`Agent` / `Task`) - - `droid.md` — Factory Droid (`Task`) - - `opencode.md` — OpenCode (`task` → explore/general/…) - - `codex.md` (+ `codex-models.md`) — OpenAI Codex / replaces codex-pstack - - `cursor.md` — Cursor (prefer official pstack plugin there) - - `generic.md` — unknown host (still parallelize if a spawn tool exists) - -If the `pstack` skill is missing, use whatever `Agent`/`Task`/`task` tool the host exposes with disjoint scopes; otherwise execute locally. +2. The matching adapter under `pstack/references/adapters/` for the active host (`claude-code`, `codex`, `droid`, `opencode`, `cursor`, or `generic`). + +Map capability verbs through that adapter. Do not invent tool parameters from another host. If spawning is unavailable, execute on the lead agent and say so. + diff --git a/skills/create-verification-skill/SKILL.md b/skills/create-verification-skill/SKILL.md index fa5dfcc..e2b24b5 100644 --- a/skills/create-verification-skill/SKILL.md +++ b/skills/create-verification-skill/SKILL.md @@ -9,18 +9,12 @@ compatibility: Works with Agent Skills-compatible coding agents. Multi-agent opt ## Portability (required) -This skill is part of the portable **pstack** pack for multiple coding agents. - -1. Read `pstack` skill `references/capability-contract.md` (or this skill's `references/capability-contract.md` if present). -2. Detect the runtime and read one adapter before any delegation: - - Cursor → `references/adapters/cursor.md` (under the `pstack` or `poteto-mode` skill) - - Codex → `references/adapters/codex.md` - - Anything else / unsure → `references/adapters/generic.md` -3. Translate upstream Cursor mechanics through the adapter. Do **not** invent Cursor `Task` / `poteto-agent` / model slugs on runtimes that lack them. -4. If multi-agent tools are unavailable, collapse parallel work onto the main agent and say so briefly. - -Capability verbs: `explore`, `implement`, `review`, `parallel`, `ask_user`, `verify`, `model_role`. +This skill is part of the portable **pstack** pack. +1. Read the `pstack` capability contract and the adapter for the active coding agent before any helper delegation. +2. Prefer capability verbs (`explore`, `implement`, `review`, `parallel`, `ask_user`, `verify`, `model_role`) over vendor tool names. +3. Resolve models through `model_role`. Never require a vendor-specific model identifier. +4. When helper spawning is unavailable, run the work on the lead agent and state that fan-out was collapsed. Every serious project needs a scripted way to drive the real app and prove behavior: launch it, exercise a feature the way a user would, and capture evidence. This skill generates that as a project-local skill (`.cursor/skills/verify-/`) tailored to the repo. You write the generator's output for the next agent, not for a human: it will be read cold, mid-task, by an agent that has never seen the app. diff --git a/skills/create-verification-skill/references/runtime.md b/skills/create-verification-skill/references/runtime.md index df0e238..d9172df 100644 --- a/skills/create-verification-skill/references/runtime.md +++ b/skills/create-verification-skill/references/runtime.md @@ -3,12 +3,7 @@ Before any multi-agent step, read the sibling **pstack** skill: 1. `pstack/references/capability-contract.md` -2. Matching adapter under `pstack/references/adapters/`: - - `claude-code.md` — Claude Code (`Agent` / `Task`) - - `droid.md` — Factory Droid (`Task`) - - `opencode.md` — OpenCode (`task` → explore/general/…) - - `codex.md` (+ `codex-models.md`) — OpenAI Codex / replaces codex-pstack - - `cursor.md` — Cursor (prefer official pstack plugin there) - - `generic.md` — unknown host (still parallelize if a spawn tool exists) - -If the `pstack` skill is missing, use whatever `Agent`/`Task`/`task` tool the host exposes with disjoint scopes; otherwise execute locally. +2. The matching adapter under `pstack/references/adapters/` for the active host (`claude-code`, `codex`, `droid`, `opencode`, `cursor`, or `generic`). + +Map capability verbs through that adapter. Do not invent tool parameters from another host. If spawning is unavailable, execute on the lead agent and say so. + diff --git a/skills/figure-it-out/SKILL.md b/skills/figure-it-out/SKILL.md index f4328ef..9bc89b2 100644 --- a/skills/figure-it-out/SKILL.md +++ b/skills/figure-it-out/SKILL.md @@ -9,18 +9,12 @@ compatibility: Works with Agent Skills-compatible coding agents. Multi-agent opt ## Portability (required) -This skill is part of the portable **pstack** pack for multiple coding agents. - -1. Read `pstack` skill `references/capability-contract.md` (or this skill's `references/capability-contract.md` if present). -2. Detect the runtime and read one adapter before any delegation: - - Cursor → `references/adapters/cursor.md` (under the `pstack` or `poteto-mode` skill) - - Codex → `references/adapters/codex.md` - - Anything else / unsure → `references/adapters/generic.md` -3. Translate upstream Cursor mechanics through the adapter. Do **not** invent Cursor `Task` / `poteto-agent` / model slugs on runtimes that lack them. -4. If multi-agent tools are unavailable, collapse parallel work onto the main agent and say so briefly. - -Capability verbs: `explore`, `implement`, `review`, `parallel`, `ask_user`, `verify`, `model_role`. +This skill is part of the portable **pstack** pack. +1. Read the `pstack` capability contract and the adapter for the active coding agent before any helper delegation. +2. Prefer capability verbs (`explore`, `implement`, `review`, `parallel`, `ask_user`, `verify`, `model_role`) over vendor tool names. +3. Resolve models through `model_role`. Never require a vendor-specific model identifier. +4. When helper spawning is unavailable, run the work on the lead agent and state that fan-out was collapsed. When the task matches no playbook, design one. The deliverable before any code is the workflow itself: a sequence of phases that scales rigor to the task, runs the scientific method, and leaves a decision trail a human can audit after stepping away. Bias toward more rigor. The cost of building the wrong thing dwarfs the cost of being careful. diff --git a/skills/figure-it-out/references/runtime.md b/skills/figure-it-out/references/runtime.md index df0e238..d9172df 100644 --- a/skills/figure-it-out/references/runtime.md +++ b/skills/figure-it-out/references/runtime.md @@ -3,12 +3,7 @@ Before any multi-agent step, read the sibling **pstack** skill: 1. `pstack/references/capability-contract.md` -2. Matching adapter under `pstack/references/adapters/`: - - `claude-code.md` — Claude Code (`Agent` / `Task`) - - `droid.md` — Factory Droid (`Task`) - - `opencode.md` — OpenCode (`task` → explore/general/…) - - `codex.md` (+ `codex-models.md`) — OpenAI Codex / replaces codex-pstack - - `cursor.md` — Cursor (prefer official pstack plugin there) - - `generic.md` — unknown host (still parallelize if a spawn tool exists) - -If the `pstack` skill is missing, use whatever `Agent`/`Task`/`task` tool the host exposes with disjoint scopes; otherwise execute locally. +2. The matching adapter under `pstack/references/adapters/` for the active host (`claude-code`, `codex`, `droid`, `opencode`, `cursor`, or `generic`). + +Map capability verbs through that adapter. Do not invent tool parameters from another host. If spawning is unavailable, execute on the lead agent and say so. + diff --git a/skills/how/references/runtime.md b/skills/how/references/runtime.md index df0e238..d9172df 100644 --- a/skills/how/references/runtime.md +++ b/skills/how/references/runtime.md @@ -3,12 +3,7 @@ Before any multi-agent step, read the sibling **pstack** skill: 1. `pstack/references/capability-contract.md` -2. Matching adapter under `pstack/references/adapters/`: - - `claude-code.md` — Claude Code (`Agent` / `Task`) - - `droid.md` — Factory Droid (`Task`) - - `opencode.md` — OpenCode (`task` → explore/general/…) - - `codex.md` (+ `codex-models.md`) — OpenAI Codex / replaces codex-pstack - - `cursor.md` — Cursor (prefer official pstack plugin there) - - `generic.md` — unknown host (still parallelize if a spawn tool exists) - -If the `pstack` skill is missing, use whatever `Agent`/`Task`/`task` tool the host exposes with disjoint scopes; otherwise execute locally. +2. The matching adapter under `pstack/references/adapters/` for the active host (`claude-code`, `codex`, `droid`, `opencode`, `cursor`, or `generic`). + +Map capability verbs through that adapter. Do not invent tool parameters from another host. If spawning is unavailable, execute on the lead agent and say so. + diff --git a/skills/interrogate/references/runtime.md b/skills/interrogate/references/runtime.md index df0e238..d9172df 100644 --- a/skills/interrogate/references/runtime.md +++ b/skills/interrogate/references/runtime.md @@ -3,12 +3,7 @@ Before any multi-agent step, read the sibling **pstack** skill: 1. `pstack/references/capability-contract.md` -2. Matching adapter under `pstack/references/adapters/`: - - `claude-code.md` — Claude Code (`Agent` / `Task`) - - `droid.md` — Factory Droid (`Task`) - - `opencode.md` — OpenCode (`task` → explore/general/…) - - `codex.md` (+ `codex-models.md`) — OpenAI Codex / replaces codex-pstack - - `cursor.md` — Cursor (prefer official pstack plugin there) - - `generic.md` — unknown host (still parallelize if a spawn tool exists) - -If the `pstack` skill is missing, use whatever `Agent`/`Task`/`task` tool the host exposes with disjoint scopes; otherwise execute locally. +2. The matching adapter under `pstack/references/adapters/` for the active host (`claude-code`, `codex`, `droid`, `opencode`, `cursor`, or `generic`). + +Map capability verbs through that adapter. Do not invent tool parameters from another host. If spawning is unavailable, execute on the lead agent and say so. + diff --git a/skills/maintain-verification-skill/SKILL.md b/skills/maintain-verification-skill/SKILL.md index fa4e0eb..cad69ca 100644 --- a/skills/maintain-verification-skill/SKILL.md +++ b/skills/maintain-verification-skill/SKILL.md @@ -9,18 +9,12 @@ compatibility: Works with Agent Skills-compatible coding agents. Multi-agent opt ## Portability (required) -This skill is part of the portable **pstack** pack for multiple coding agents. - -1. Read `pstack` skill `references/capability-contract.md` (or this skill's `references/capability-contract.md` if present). -2. Detect the runtime and read one adapter before any delegation: - - Cursor → `references/adapters/cursor.md` (under the `pstack` or `poteto-mode` skill) - - Codex → `references/adapters/codex.md` - - Anything else / unsure → `references/adapters/generic.md` -3. Translate upstream Cursor mechanics through the adapter. Do **not** invent Cursor `Task` / `poteto-agent` / model slugs on runtimes that lack them. -4. If multi-agent tools are unavailable, collapse parallel work onto the main agent and say so briefly. - -Capability verbs: `explore`, `implement`, `review`, `parallel`, `ask_user`, `verify`, `model_role`. +This skill is part of the portable **pstack** pack. +1. Read the `pstack` capability contract and the adapter for the active coding agent before any helper delegation. +2. Prefer capability verbs (`explore`, `implement`, `review`, `parallel`, `ask_user`, `verify`, `model_role`) over vendor tool names. +3. Resolve models through `model_role`. Never require a vendor-specific model identifier. +4. When helper spawning is unavailable, run the work on the lead agent and state that fan-out was collapsed. 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. diff --git a/skills/maintain-verification-skill/references/runtime.md b/skills/maintain-verification-skill/references/runtime.md index df0e238..d9172df 100644 --- a/skills/maintain-verification-skill/references/runtime.md +++ b/skills/maintain-verification-skill/references/runtime.md @@ -3,12 +3,7 @@ Before any multi-agent step, read the sibling **pstack** skill: 1. `pstack/references/capability-contract.md` -2. Matching adapter under `pstack/references/adapters/`: - - `claude-code.md` — Claude Code (`Agent` / `Task`) - - `droid.md` — Factory Droid (`Task`) - - `opencode.md` — OpenCode (`task` → explore/general/…) - - `codex.md` (+ `codex-models.md`) — OpenAI Codex / replaces codex-pstack - - `cursor.md` — Cursor (prefer official pstack plugin there) - - `generic.md` — unknown host (still parallelize if a spawn tool exists) - -If the `pstack` skill is missing, use whatever `Agent`/`Task`/`task` tool the host exposes with disjoint scopes; otherwise execute locally. +2. The matching adapter under `pstack/references/adapters/` for the active host (`claude-code`, `codex`, `droid`, `opencode`, `cursor`, or `generic`). + +Map capability verbs through that adapter. Do not invent tool parameters from another host. If spawning is unavailable, execute on the lead agent and say so. + diff --git a/skills/no-comments/SKILL.md b/skills/no-comments/SKILL.md index 3552419..ac2f541 100644 --- a/skills/no-comments/SKILL.md +++ b/skills/no-comments/SKILL.md @@ -9,18 +9,12 @@ compatibility: Works with Agent Skills-compatible coding agents. Multi-agent opt ## Portability (required) -This skill is part of the portable **pstack** pack for multiple coding agents. - -1. Read `pstack` skill `references/capability-contract.md` (or this skill's `references/capability-contract.md` if present). -2. Detect the runtime and read one adapter before any delegation: - - Cursor → `references/adapters/cursor.md` (under the `pstack` or `poteto-mode` skill) - - Codex → `references/adapters/codex.md` - - Anything else / unsure → `references/adapters/generic.md` -3. Translate upstream Cursor mechanics through the adapter. Do **not** invent Cursor `Task` / `poteto-agent` / model slugs on runtimes that lack them. -4. If multi-agent tools are unavailable, collapse parallel work onto the main agent and say so briefly. - -Capability verbs: `explore`, `implement`, `review`, `parallel`, `ask_user`, `verify`, `model_role`. +This skill is part of the portable **pstack** pack. +1. Read the `pstack` capability contract and the adapter for the active coding agent before any helper delegation. +2. Prefer capability verbs (`explore`, `implement`, `review`, `parallel`, `ask_user`, `verify`, `model_role`) over vendor tool names. +3. Resolve models through `model_role`. Never require a vendor-specific model identifier. +4. When helper spawning is unavailable, run the work on the lead agent and state that fan-out was collapsed. Spawn Comment Sicko. Act on accepted findings. diff --git a/skills/no-comments/references/runtime.md b/skills/no-comments/references/runtime.md index df0e238..d9172df 100644 --- a/skills/no-comments/references/runtime.md +++ b/skills/no-comments/references/runtime.md @@ -3,12 +3,7 @@ Before any multi-agent step, read the sibling **pstack** skill: 1. `pstack/references/capability-contract.md` -2. Matching adapter under `pstack/references/adapters/`: - - `claude-code.md` — Claude Code (`Agent` / `Task`) - - `droid.md` — Factory Droid (`Task`) - - `opencode.md` — OpenCode (`task` → explore/general/…) - - `codex.md` (+ `codex-models.md`) — OpenAI Codex / replaces codex-pstack - - `cursor.md` — Cursor (prefer official pstack plugin there) - - `generic.md` — unknown host (still parallelize if a spawn tool exists) - -If the `pstack` skill is missing, use whatever `Agent`/`Task`/`task` tool the host exposes with disjoint scopes; otherwise execute locally. +2. The matching adapter under `pstack/references/adapters/` for the active host (`claude-code`, `codex`, `droid`, `opencode`, `cursor`, or `generic`). + +Map capability verbs through that adapter. Do not invent tool parameters from another host. If spawning is unavailable, execute on the lead agent and say so. + diff --git a/skills/poteto-mode/playbooks/autonomous-run.md b/skills/poteto-mode/playbooks/autonomous-run.md index c2c99ee..8c6eebd 100644 --- a/skills/poteto-mode/playbooks/autonomous-run.md +++ b/skills/poteto-mode/playbooks/autonomous-run.md @@ -3,7 +3,7 @@ **You own the exit condition. Define done, then drive to it without stopping.** For "going to bed" / "run until done" / "long-run/loop until X". 1. State the exit condition as a checkable predicate before the first iteration (tests green, repro fixed, all N PRs merged, pixel-diff zero). A vague goal stalls; a predicate lets you stop. -2. Pick the wake mechanism using the agent's long-running / loop mechanism if available, otherwise continue autonomously (a built-in, not a pstack skill). 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. +2. Pick the wake mechanism using the agent's long-running / loop mechanism if available, otherwise continue autonomously (a host built-in, not a pstack skill). An event to watch (CI, a merge, a ref advancing) gets a watcher helper 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. 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. Sequence the work via the **sequence-verifiable-units** principle skill, verifying each unit before the next instead of batching checks at the end. 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`. 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. diff --git a/skills/poteto-mode/playbooks/bug-fix.md b/skills/poteto-mode/playbooks/bug-fix.md index 094b8be..35eb26b 100644 --- a/skills/poteto-mode/playbooks/bug-fix.md +++ b/skills/poteto-mode/playbooks/bug-fix.md @@ -1,17 +1,17 @@ ### Bug fix -**You own this task. Plan, review, verify.** Delegate investigation and the fix to subagents, stay in the lead. +**You own this task. Plan, review, verify.** Delegate investigation and the fix to helpers, stay in the lead. Be scientific. Every shipped line traces to runtime evidence. Belt-and-suspenders that "might help" is a hypothesis, not a fix; it does not ship. When evidence refutes a hypothesis, revert what it motivated. The smallest change the evidence justifies ships, nothing more. Same discipline for Perf, where the evidence is the trace. -1. Reproduce it yourself on the matching surface on the matching real surface (Non-negotiables). Don't hand the repro to the user. A debug or instrumentation protocol that says to ask the user does not override this; you drive the instrumented runtime. Ask the user only with a stated, specific reason the control surface cannot reach the target, and only after driving it as far as it goes. Won't reproduce directly, force it: synthesize the trigger, tighten conditions, or instrument until it fires. A bug you can't reproduce, you can't prove fixed. +1. Reproduce it yourself with `verify` on the real surface the bug touches (Non-negotiables). Don't hand the repro to the user. A debug or instrumentation protocol that says to ask the user does not override this; you drive the instrumented runtime. Ask the user only with a stated, specific reason the runtime surface cannot reach the target, and only after driving it as far as it goes. Won't reproduce directly, force it: synthesize the trigger, tighten conditions, or instrument until it fires. A bug you can't reproduce, you can't prove fixed. 2. Binary-search the cause. Form the candidate hypotheses, then rule them out until one survives. Seed them with `how` over the affected subsystem and the **why** skill for regression history. Each pass, take the split that cuts the most remaining problem space, get runtime evidence, eliminate. When program state is unclear, add instrumentation or logging and read it as the code runs. Don't guess. Drive a long or stubborn hunt with the agent's long-running / loop mechanism if available, otherwise continue autonomously. Confirm the surviving *mechanism* with runtime evidence before the step-3 architect/interrogate fan-out; a design grounded on a plausible-but-unconfirmed cause can be unanimously wrong while the real cause sits one subsystem over. -3. Plan the fix. If it crosses a function boundary, `architect` first. Delegate implementation to a subagent using your configured bug-fix model (`model_role:bug_impl`) with a specific scope; review the diff. -4. Verify on the same surface; the original repro now passes. "Inconclusive" or wrong-surface is not a pass; flag it. Unit tests show branch behavior, not bug absence. +3. Plan the fix. If it crosses a function boundary, `architect` first. Use `implement` with `model_role:bug_impl` for a scoped helper; review the diff. +4. Use `verify` on the same surface; the original repro now passes. "Inconclusive" or wrong-surface is not a pass; flag it. Unit tests show branch behavior, not bug absence. 5. Stage the commits so the failing repro lands before the fix in git history; the diff tells the story. See the **tdd** skill for the failing-test-first cadence when the bug has a cheap local test path; skip it when the test would be expensive, integration-heavy, or unclear. This is the canonical **sequence-verifiable-units** principle skill, the failing test first and the fix on top. 6. Run **Opening a PR**. -Investigation fans out `how` + `why` as parallel subagents. +Investigation fans out `how` + `why` via `parallel` helpers. **Reply:** what was broken, root cause, fix, how you verified. Paste failing-then-passing repro output verbatim. diff --git a/skills/poteto-mode/playbooks/feature.md b/skills/poteto-mode/playbooks/feature.md index 1d0ea95..3c62ece 100644 --- a/skills/poteto-mode/playbooks/feature.md +++ b/skills/poteto-mode/playbooks/feature.md @@ -9,8 +9,8 @@ - **Independent workstreams.** Disjoint files, services, or layers parallelize. Shared writes serialize. - **Shared mutable state.** Default to splitting the target (the **separate-before-serializing-shared-state** principle skill). Serialize only for real invariants. - **Smallest safe decomposition.** If one worker is best, name why. -4. Delegate code-writing to a subagent using your configured feature model (`model_role:feature_impl`) with a specific scope (file paths, named data shape and its organizing structure per **principle-model-the-domain** — a state machine over scattered booleans, a table/registry over branching, a typed model over repeated shape assumptions, chosen before the delegate writes logic — and success criteria); review its diff yourself. When the implementation admits multiple valid shapes (error handling, abstraction layer, test structure), delegate via the **arena** skill instead so the runners surface the alternatives and the cross-judge guards the pick. Mandatory: no skip-with-reason escape, and Laziness Protocol does not override it (the gain is review separation, not lines saved). You can spawn a subagent even though you are one; "the app is small" and "a subagent cannot spawn one" are both wrong. A subagent forbidden to spawn satisfies this by owning the diff directly with the same review separation; no "standing by" reply that waits on a nested agent. Comments per **Comments**. Surgical edits, re-ground against the source for upstream-derived files. Port shared-primitive improvements to all consumers and verify each. Commit liberally. -5. Verify on the matching surface. "Inconclusive" or wrong-surface is not a pass; flag it. +4. Use `implement` with `model_role:feature_impl` for a scoped helper (file paths, named data shape and its organizing structure per **principle-model-the-domain** — a state machine over scattered booleans, a table/registry over branching, a typed model over repeated shape assumptions, chosen before the helper writes logic — and success criteria); review its diff yourself. When the implementation admits multiple valid shapes (error handling, abstraction layer, test structure), route through the **arena** skill instead so runners surface alternatives and the cross-judge guards the pick. Mandatory: no skip-with-reason escape, and Laziness Protocol does not override it (the gain is review separation, not lines saved). Nested helpers are allowed when the adapter supports them; "the app is small" is not a reason to skip. When spawning is forbidden or unavailable, the lead owns the diff directly with the same review separation rather than waiting on a nested agent. Comments per **Comments**. Surgical edits, re-ground against the source for upstream-derived files. Port shared-primitive improvements to all consumers and verify each. Commit liberally. +5. Use `verify` on the real surface the change touches. "Inconclusive" or wrong-surface is not a pass; flag it. 6. Rebase into small, ordered commits; stack follow-ups. Use the **sequence-verifiable-units** principle skill, building, verifying, and committing each small unit before the next. 7. If the design is contested, `interrogate` before shipping. diff --git a/skills/poteto-mode/playbooks/pause-safely.md b/skills/poteto-mode/playbooks/pause-safely.md index b125efb..180a350 100644 --- a/skills/poteto-mode/playbooks/pause-safely.md +++ b/skills/poteto-mode/playbooks/pause-safely.md @@ -1,8 +1,8 @@ ### Pause safely -**You own a clean stop. Leave a checkpoint a cold-start agent can resume from.** For "pause safely", "I need to go offline", "restart Cursor", or "board my flight", and when context is about to compact or summarize. This is explicit only. On "keep going", "going to bed, keep going", or "don't stop", do not pause. Those mean continue, and Autonomous run already checkpoints per iteration. +**You own a clean stop. Leave a checkpoint a cold-start agent can resume from.** For "pause safely", "I need to go offline", "restart the agent/IDE", or "board my flight", and when context is about to compact or summarize. This is explicit only. On "keep going", "going to bed, keep going", or "don't stop", do not pause. Those mean continue, and Autonomous run already checkpoints per iteration. -1. Stop at a safe boundary. Finish the current atomic step or back out of it. Never stop mid-edit in a known-broken state. Start nothing new, and cancel any nested subagents. +1. Stop at a safe boundary. Finish the current atomic step or back out of it. Never stop mid-edit in a known-broken state. Start nothing new, and cancel any nested helpers. 2. Don't cross an irreversible line to pause. No PR and no push unless you already had one out. 3. Make the work durable. Commit uncommitted edits as one clear `wip:` commit on the current branch so nothing is lost. If the tree is broken, say so in the commit body in one line. 4. Write the resume note off-context. Capture intent, what you were doing, progress and what's verified, current state, next steps, key files, and gotchas. For the compaction trigger write it to a file like `/tmp/-resume.md`, because the in-context plan won't survive summarization. If a show-me-your-work trail exists, point at it instead of duplicating it. diff --git a/skills/poteto-mode/playbooks/prototype.md b/skills/poteto-mode/playbooks/prototype.md index 9ac02e6..fa29884 100644 --- a/skills/poteto-mode/playbooks/prototype.md +++ b/skills/poteto-mode/playbooks/prototype.md @@ -8,7 +8,7 @@ The one playbook where the Laziness Protocol's "smallest change" and the verific 2. Gather references when the design space is open. Search for prior art, summarize a moodboard of themes, palettes, and layouts, let the user pick directions before building. Skip when the direction is set. 3. Build throwaway in an isolated scratch dir, separate from production source. For a visual decision, vanilla HTML/CSS/JS or the lightest stack that renders the idea, CDN deps, a dev server with hot reload. For a behavioral or timing decision, the smallest script that exercises the question. No production framework, no tests, no abstractions. 4. When comparing alternatives, build them behind one switcher (buttons or a keypress), each variant labeled so the user can name it. This is the **exhaust-the-design-space** principle skill made cheap. -5. Verify on the matching surface. For a visual decision, screenshot each variant on the matching real surface and drive the interaction; the eye is the test. For a behavioral or timing decision, observe the thing you are deciding by logging the timing, printing the output, or watching the render. The observation is the test here, not an assertion. +5. Use `verify` on the real surface. For a visual decision, screenshot each variant and drive the interaction; the eye is the test. For a behavioral or timing decision, observe the thing you are deciding by logging the timing, printing the output, or watching the render. The observation is the test here, not an assertion. 6. Present alternatives, tradeoffs, and a recommendation. The output is the decision plus the throwaway artifact, not shippable code. Hand the chosen direction to **Feature** (or `architect` for the shape) for the real build. **Reply:** the variants explored, the evidence (screenshots for a visual decision, the observed output or timing for a behavioral one), tradeoffs, your recommendation, and the scratch path. Say plainly that the prototype is throwaway. diff --git a/skills/poteto-mode/playbooks/refactoring.md b/skills/poteto-mode/playbooks/refactoring.md index d600382..73bf113 100644 --- a/skills/poteto-mode/playbooks/refactoring.md +++ b/skills/poteto-mode/playbooks/refactoring.md @@ -8,8 +8,8 @@ A refactor that smuggles in a behavior change loses its safety net. If the clean 2. Name the structure the code is missing per **principle-model-the-domain**: a state machine over scattered booleans, a table or registry over spread-out branching, a typed model over repeated shape assumptions, a reducer over ad hoc mutations. Boring code stays when the shape is already clear and local; the reshape must delete branches or invalid states, not add indirection. 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. 4. Subtract before you add. Delete dead weight, 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, not left to ride. -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 (`model_role:feature_impl`) with a specific scope (file paths, the names being moved, the behavior to hold); review the diff yourself. -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 control skill. Own the verification yourself; do not trust a delegate's "looks good" summary. +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. Use `implement` with `model_role:feature_impl` for the mechanical edits with a specific scope (file paths, the names being moved, the behavior to hold); review the diff yourself. +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 with `verify` on the real surface the change touches. Own the verification yourself; do not trust a delegate's "looks good" summary. 7. Confirm the change earns its place. The success measure is reduced reader load (**principle-minimize-reader-load**): fewer layers between question and answer, less hidden state, fewer indirections without a second consumer. If the diff does not lower reader load somewhere, revert it. 8. Rebase into small ordered commits that tell the story. A subtraction commit, then the reshape, then any follow-on cleanup, so a single revert undoes one slice. Shape them with the **sequence-verifiable-units** principle skill, so each behavior-preserving slice stays green before the next. Run **Opening a PR**. diff --git a/skills/poteto-mode/playbooks/runtime-forensics.md b/skills/poteto-mode/playbooks/runtime-forensics.md index 89264cf..2d10b27 100644 --- a/skills/poteto-mode/playbooks/runtime-forensics.md +++ b/skills/poteto-mode/playbooks/runtime-forensics.md @@ -2,8 +2,8 @@ **You own the diagnosis. Instrument the live process, don't theorize from source.** For "why is X leaking / spinning / slow at runtime", heap snapshots, idle-but-busy processes, intermittent glitches. The deliverable is a cited diagnosis, not a fix. -1. Capture the live signal on the matching surface on the matching real surface: a CPU profile for a spinning process, a heap snapshot for a leak, a CDP trace for a visual glitch. A real artifact, not a guess. -2. Reduce the artifact to the smoking gun: the function on the hot path, the retainer chain from the leaked object to a GC root, the loop firing without input. Parse large artifacts in a subagent (the **guard-the-context-window** principle skill), keep the reduced finding in the main thread. +1. Capture the live signal with `verify` on the real runtime surface: a CPU profile for a spinning process, a heap snapshot for a leak, a CDP or equivalent trace for a visual glitch. A real artifact, not a guess. +2. Reduce the artifact to the smoking gun: the function on the hot path, the retainer chain from the leaked object to a GC root, the loop firing without input. Parse large artifacts with a read-only `explore` helper (the **guard-the-context-window** principle skill), keep the reduced finding in the main thread. 3. Prove the mechanism before believing it. Inject instrumentation via CDP eval on the running process, or hotfix the live code without reloading, to confirm the hypothesis cheaply. A plausible-but-unconfirmed cause can be wrong while the real one sits one layer over. 4. Map the finding back to source: file, symbol, the line that allocates or schedules. 5. Throughput checkpoint stays one line: `throughput checkpoint: n/a, read-only forensics`. diff --git a/skills/poteto-mode/playbooks/trace-forensics.md b/skills/poteto-mode/playbooks/trace-forensics.md index 10f8209..11341d7 100644 --- a/skills/poteto-mode/playbooks/trace-forensics.md +++ b/skills/poteto-mode/playbooks/trace-forensics.md @@ -4,7 +4,7 @@ Distinct from **Runtime forensics**, which instruments the live process. Here the capture already exists; the artifact is a fixed dataset, read it, don't re-run it. Keep tooling generic so the playbook stays portable: a DevTools or trace parser for cpuprofile and `.json.gz`, a text editor for a spindump, your heap tooling for a heapsnapshot. -1. Identify the format and load it with the right tool. Parse large artifacts in a subagent (the **principle-guard-the-context-window** skill) and keep the reduced finding in the main thread. +1. Identify the format and load it with the right tool. Parse large artifacts with a read-only `explore` helper (the **principle-guard-the-context-window** skill) and keep the reduced finding in the main thread. 2. Transform the raw artifact into a form you can query. Dump the trace or heap snapshot into sqlite, one row per sample, frame, or node. Reach the queryable shape before you read. 3. Narrow to the cause. Query for the frames that hold the most time and walk the call tree to the hot path. For a leak, follow the retainer chain from the leaked object to a GC root. For a spindump, find the thread stuck on-CPU or blocked and its wait reason. 4. Attribute to source. Map the hot frame to file, symbol, and line via the artifact's own symbols. A frame with no source mapping is not yet a diagnosis; resolve the symbols, or say plainly the artifact does not carry them. diff --git a/skills/poteto-mode/playbooks/visual-parity.md b/skills/poteto-mode/playbooks/visual-parity.md index 3b30df4..f486950 100644 --- a/skills/poteto-mode/playbooks/visual-parity.md +++ b/skills/poteto-mode/playbooks/visual-parity.md @@ -5,7 +5,7 @@ 1. Establish the baseline first, before any migration: a visual regression harness that screenshots the current component across its states, plus the target when matching two implementations. No baseline, no parity claim. A blocking prerequisite, not a follow-up. 2. Anti-shortcut clauses, stated and held: no harness modifications, no baseline tampering, no component restructuring to make a diff pass. If the baseline looks wrong, stop and ask, don't edit it. 3. Migrate one component at a time. Each is an independent artifact, so parallelize across worktrees, one owner per component (the **separate-before-serializing-shared-state** principle skill). Shared primitives migrate first as a blocking phase. -4. Verify each component against its baseline via image diff on the matching surface on the matching real surface. A nonzero diff is a fail; investigate the pixel delta, don't wave it through. `long-runlong-run/loop` per component until the diff is zero. +4. Verify each component against its baseline via image diff on the real UI surface available through `verify`. A nonzero diff is a fail; investigate the pixel delta, don't wave it through. Use the host's long-running or loop mechanism per component until the diff is zero. 5. Run **Opening a PR** per component or per safe batch. **Reply:** components migrated, the diff result for each, the baseline harness location, what's left. diff --git a/skills/poteto-mode/playbooks/worktree-cleanup.md b/skills/poteto-mode/playbooks/worktree-cleanup.md index 9f6be47..3760577 100644 --- a/skills/poteto-mode/playbooks/worktree-cleanup.md +++ b/skills/poteto-mode/playbooks/worktree-cleanup.md @@ -2,12 +2,12 @@ **You own the disk and the safety gate.** Prune merged or abandoned git worktrees and stale iOS simulators to reclaim space. Deletion is irreversible, so every step guards against deleting something in use or holding uncommitted work. -1. Snapshot and audit. Record `df -h /`, then run `scripts/worktree-audit.sh` (principle-build-the-lever). It reads paths from `git worktree list`, never hand-typed, since a hand-typed `myrepo-worktrees/x` misses one that lives at `.cursor/worktrees/myrepo/x` (principle-encode-lessons-in-structure). It classifies each worktree by size, age, merge state, uncommitted work, PR state, and the newest chat that touched it, then suggests a bucket. The transcript scan is slow, so background it. -2. The bucket is advice, not permission. The pinned and active chats are the real artifact (principle-prove-it-works). Get that set from the user or sidebar and cross-check every candidate. The lever has marked `safe` a worktree the user had pinned, so the pinned set wins. -3. Verify usage before deleting. For every `verify-recent-chat` row, or anything you doubt, fan subagents out to read the transcripts and report whether the chat is pinned or ongoing and which worktrees it touches (principle-guard-the-context-window, transcripts are bulk). A pinned chat spawns arena and repro trees into sibling worktrees via background subagents, and those are in use even when their names never hit the sidebar. +1. Snapshot and audit. Record `df -h /`, then run `scripts/worktree-audit.sh` when present (principle-build-the-lever). It reads paths from `git worktree list`, never hand-typed, since a hand-typed path can miss host-managed worktree roots (principle-encode-lessons-in-structure). It classifies each worktree by size, age, merge state, uncommitted work, PR state, and the newest session that touched it, then suggests a bucket. Session scanning is slow, so run it non-blocking when the adapter supports it. +2. The bucket is advice, not permission. Active or pinned sessions are the real artifact (principle-prove-it-works). Get that set from the user or the host UI and cross-check every candidate. The lever has marked `safe` a worktree the user still needs, so the active set wins. +3. Verify usage before deleting. For every doubtful row, use `parallel` with read-only `explore` helpers to inspect session evidence and report whether the session is active and which worktrees it touches (principle-guard-the-context-window). An active session can own sibling arena or repro worktrees even when those names never appear in the sidebar. 4. Pause on irreversible loss. `wip:N` is N tracked uncommitted edits. Show the diff and get a decision first, since removing a clean worktree is recoverable from its branch but uncommitted work is gone. `scratch:N` is untracked throwaway, safe to drop, but name the files. Per Autonomy, clean and merged and not-in-use proceeds; `wip` and in-use pause. 5. Prune the confirmed set. Per path, `git worktree remove --force `; if the dir survives on ignored build artifacts, `rm -rf` it, then `git worktree prune`. Branch refs survive, so no commits are lost. Confirm with `df -h /` and re-list. -6. Simulators and other reclaimers. Simulators are usually the next-biggest win. `xcrun simctl --set testing delete all` (XCTestDevices clones), `xcrun simctl delete unavailable`, and `xcrun simctl runtime list` then `runtime delete ` for old runtimes. More when needed: Xcode `DerivedData` and `iOS DeviceSupport`; `~/Library/Application Support/Cursor` (`state.vscdb.backup`, and `snapshots/roots/` where a `` named for a folder you opened as a workspace balloons); package caches (pnpm, uv, brew, yarn). Clear only caches the user has not said to keep. +6. Simulators and other reclaimers. Simulators are usually the next-biggest win. `xcrun simctl --set testing delete all` (XCTestDevices clones), `xcrun simctl delete unavailable`, and `xcrun simctl runtime list` then `runtime delete ` for old runtimes. More when needed: Xcode `DerivedData` and `iOS DeviceSupport`; host-local IDE state caches only when the user names them; package caches (pnpm, uv, brew, yarn). Clear only caches the user has not said to keep. This is the one playbook that deletes user state with no code review to catch a slip, so the gates above are the review. diff --git a/skills/poteto-mode/references/capability-contract.md b/skills/poteto-mode/references/capability-contract.md index 6188d8f..5b8fa3a 100644 --- a/skills/poteto-mode/references/capability-contract.md +++ b/skills/poteto-mode/references/capability-contract.md @@ -1,18 +1,20 @@ # Capability contract +Version: `1.0.0` + Playbooks speak in these capabilities. Adapters map them to a concrete runtime. Never call a tool that the active adapter does not define. ## Capabilities -| Capability | Intent | Fallback when unavailable | -| --- | --- | --- | -| `explore` | Read-only codebase search and tracing | Main agent uses local search/read tools | -| `implement` | Bounded code edits with disjoint write scope | Main agent edits directly | -| `review` | Independent critique of a design or diff | Main agent reviews; optionally second pass with a different rubric | -| `parallel` | Fan out independent slices at once | Run slices sequentially | -| `ask_user` | Product or preference decision only | Ask in plain text; never for facts you can observe | -| `verify` | Run the narrowest meaningful check on the real surface | State what you could not run and why | -| `model_role` | Prefer a role-appropriate model when overrides exist | Use the parent session model | +| Capability | Intent | Required? | Fallback when unavailable | +| --- | --- | --- | --- | +| `explore` | Read-only codebase search and tracing | required | Main agent uses local search/read tools | +| `implement` | Bounded code edits with disjoint write scope | required | Main agent edits directly | +| `review` | Independent critique of a design or diff | required | Main agent reviews; optionally second pass with a different rubric | +| `parallel` | Fan out independent slices at once | optional / degradable | Run slices sequentially and state the collapse | +| `ask_user` | Product or preference decision only | required | Ask in plain text; never for facts you can observe | +| `verify` | Run the narrowest meaningful check on the real surface | required | State what you could not run and why | +| `model_role` | Prefer a role-appropriate model when overrides exist | optional / degradable | Use the parent session model | ## Role hints (optional) @@ -26,9 +28,28 @@ Adapters may map these roles to models. If unset, inherit the parent model. | `bug_impl` | High-stakes fix after evidence | | `critic` | Adversarial review panel member | +## Adapter self-check + +Before the first helper spawn, the lead should know for the active host: + +1. which helper types exist; +2. whether true `parallel` fan-out works; +3. concurrency or queue limits; +4. whether `model_role` can select a concrete model; +5. which external connectors are available for evidence (`why`, tickets, logs); +6. whether browser/CLI/runtime control exists for `verify`; +7. what mode or skill persistence the host actually enforces. + +Document host-specific answers only under `references/adapters/`. + +## Read-only intent vs tool access + +Read-only intent forbids writes to the repository and external mutating actions. It must not strip connected evidence tools (ticket readers, log queries, docs fetchers) that the investigation needs. Separate "may write" from "may read connected systems". + ## Rules for authors 1. Playbooks must not name Cursor `Task`, Codex `spawn_agent`, Claude `Agent`, OpenCode `task`, Droid tool JSON, or vendor model slugs. 2. Write steps as: "Using `explore`, …" / "Using `implement`, …" / "Using `parallel`, …". 3. Every playbook must remain correct when spawn tools are missing (collapse via `generic`), but authors should assume modern hosts **do** support `parallel`. 4. Runtime-specific notes belong only under `references/adapters/`. +5. Bump this contract version when capability meanings or required/optional classifications change. diff --git a/skills/principle-boundary-discipline/SKILL.md b/skills/principle-boundary-discipline/SKILL.md index 279aedc..8ba17ed 100644 --- a/skills/principle-boundary-discipline/SKILL.md +++ b/skills/principle-boundary-discipline/SKILL.md @@ -9,18 +9,12 @@ compatibility: Works with Agent Skills-compatible coding agents. Multi-agent opt ## Portability (required) -This skill is part of the portable **pstack** pack for multiple coding agents. - -1. Read `pstack` skill `references/capability-contract.md` (or this skill's `references/capability-contract.md` if present). -2. Detect the runtime and read one adapter before any delegation: - - Cursor → `references/adapters/cursor.md` (under the `pstack` or `poteto-mode` skill) - - Codex → `references/adapters/codex.md` - - Anything else / unsure → `references/adapters/generic.md` -3. Translate upstream Cursor mechanics through the adapter. Do **not** invent Cursor `Task` / `poteto-agent` / model slugs on runtimes that lack them. -4. If multi-agent tools are unavailable, collapse parallel work onto the main agent and say so briefly. - -Capability verbs: `explore`, `implement`, `review`, `parallel`, `ask_user`, `verify`, `model_role`. +This skill is part of the portable **pstack** pack. +1. Read the `pstack` capability contract and the adapter for the active coding agent before any helper delegation. +2. Prefer capability verbs (`explore`, `implement`, `review`, `parallel`, `ask_user`, `verify`, `model_role`) over vendor tool names. +3. Resolve models through `model_role`. Never require a vendor-specific model identifier. +4. When helper spawning is unavailable, run the work on the lead agent and state that fan-out was collapsed. Place validation, type narrowing, and error handling at system boundaries. Trust internal code unconditionally. Business logic lives in pure functions; the shell is thin and mechanical. diff --git a/skills/principle-boundary-discipline/references/runtime.md b/skills/principle-boundary-discipline/references/runtime.md index df0e238..d9172df 100644 --- a/skills/principle-boundary-discipline/references/runtime.md +++ b/skills/principle-boundary-discipline/references/runtime.md @@ -3,12 +3,7 @@ Before any multi-agent step, read the sibling **pstack** skill: 1. `pstack/references/capability-contract.md` -2. Matching adapter under `pstack/references/adapters/`: - - `claude-code.md` — Claude Code (`Agent` / `Task`) - - `droid.md` — Factory Droid (`Task`) - - `opencode.md` — OpenCode (`task` → explore/general/…) - - `codex.md` (+ `codex-models.md`) — OpenAI Codex / replaces codex-pstack - - `cursor.md` — Cursor (prefer official pstack plugin there) - - `generic.md` — unknown host (still parallelize if a spawn tool exists) - -If the `pstack` skill is missing, use whatever `Agent`/`Task`/`task` tool the host exposes with disjoint scopes; otherwise execute locally. +2. The matching adapter under `pstack/references/adapters/` for the active host (`claude-code`, `codex`, `droid`, `opencode`, `cursor`, or `generic`). + +Map capability verbs through that adapter. Do not invent tool parameters from another host. If spawning is unavailable, execute on the lead agent and say so. + diff --git a/skills/principle-build-the-lever/SKILL.md b/skills/principle-build-the-lever/SKILL.md index 6e68237..432a8f7 100644 --- a/skills/principle-build-the-lever/SKILL.md +++ b/skills/principle-build-the-lever/SKILL.md @@ -9,18 +9,12 @@ compatibility: Works with Agent Skills-compatible coding agents. Multi-agent opt ## Portability (required) -This skill is part of the portable **pstack** pack for multiple coding agents. - -1. Read `pstack` skill `references/capability-contract.md` (or this skill's `references/capability-contract.md` if present). -2. Detect the runtime and read one adapter before any delegation: - - Cursor → `references/adapters/cursor.md` (under the `pstack` or `poteto-mode` skill) - - Codex → `references/adapters/codex.md` - - Anything else / unsure → `references/adapters/generic.md` -3. Translate upstream Cursor mechanics through the adapter. Do **not** invent Cursor `Task` / `poteto-agent` / model slugs on runtimes that lack them. -4. If multi-agent tools are unavailable, collapse parallel work onto the main agent and say so briefly. - -Capability verbs: `explore`, `implement`, `review`, `parallel`, `ask_user`, `verify`, `model_role`. +This skill is part of the portable **pstack** pack. +1. Read the `pstack` capability contract and the adapter for the active coding agent before any helper delegation. +2. Prefer capability verbs (`explore`, `implement`, `review`, `parallel`, `ask_user`, `verify`, `model_role`) over vendor tool names. +3. Resolve models through `model_role`. Never require a vendor-specific model identifier. +4. When helper spawning is unavailable, run the work on the lead agent and state that fan-out was collapsed. When the work isn't trivial, build the tool that does it instead of doing it by hand. diff --git a/skills/principle-build-the-lever/references/runtime.md b/skills/principle-build-the-lever/references/runtime.md index df0e238..d9172df 100644 --- a/skills/principle-build-the-lever/references/runtime.md +++ b/skills/principle-build-the-lever/references/runtime.md @@ -3,12 +3,7 @@ Before any multi-agent step, read the sibling **pstack** skill: 1. `pstack/references/capability-contract.md` -2. Matching adapter under `pstack/references/adapters/`: - - `claude-code.md` — Claude Code (`Agent` / `Task`) - - `droid.md` — Factory Droid (`Task`) - - `opencode.md` — OpenCode (`task` → explore/general/…) - - `codex.md` (+ `codex-models.md`) — OpenAI Codex / replaces codex-pstack - - `cursor.md` — Cursor (prefer official pstack plugin there) - - `generic.md` — unknown host (still parallelize if a spawn tool exists) - -If the `pstack` skill is missing, use whatever `Agent`/`Task`/`task` tool the host exposes with disjoint scopes; otherwise execute locally. +2. The matching adapter under `pstack/references/adapters/` for the active host (`claude-code`, `codex`, `droid`, `opencode`, `cursor`, or `generic`). + +Map capability verbs through that adapter. Do not invent tool parameters from another host. If spawning is unavailable, execute on the lead agent and say so. + diff --git a/skills/principle-encode-lessons-in-structure/SKILL.md b/skills/principle-encode-lessons-in-structure/SKILL.md index a3fe627..207205d 100644 --- a/skills/principle-encode-lessons-in-structure/SKILL.md +++ b/skills/principle-encode-lessons-in-structure/SKILL.md @@ -9,18 +9,12 @@ compatibility: Works with Agent Skills-compatible coding agents. Multi-agent opt ## Portability (required) -This skill is part of the portable **pstack** pack for multiple coding agents. - -1. Read `pstack` skill `references/capability-contract.md` (or this skill's `references/capability-contract.md` if present). -2. Detect the runtime and read one adapter before any delegation: - - Cursor → `references/adapters/cursor.md` (under the `pstack` or `poteto-mode` skill) - - Codex → `references/adapters/codex.md` - - Anything else / unsure → `references/adapters/generic.md` -3. Translate upstream Cursor mechanics through the adapter. Do **not** invent Cursor `Task` / `poteto-agent` / model slugs on runtimes that lack them. -4. If multi-agent tools are unavailable, collapse parallel work onto the main agent and say so briefly. - -Capability verbs: `explore`, `implement`, `review`, `parallel`, `ask_user`, `verify`, `model_role`. +This skill is part of the portable **pstack** pack. +1. Read the `pstack` capability contract and the adapter for the active coding agent before any helper delegation. +2. Prefer capability verbs (`explore`, `implement`, `review`, `parallel`, `ask_user`, `verify`, `model_role`) over vendor tool names. +3. Resolve models through `model_role`. Never require a vendor-specific model identifier. +4. When helper spawning is unavailable, run the work on the lead agent and state that fan-out was collapsed. Encode recurring fixes in mechanisms (tools, code, metadata, automation) instead of textual instructions. Every error, human correction, and unexpected outcome is a learning signal. Capture it, route it, and close the loop. diff --git a/skills/principle-encode-lessons-in-structure/references/runtime.md b/skills/principle-encode-lessons-in-structure/references/runtime.md index df0e238..d9172df 100644 --- a/skills/principle-encode-lessons-in-structure/references/runtime.md +++ b/skills/principle-encode-lessons-in-structure/references/runtime.md @@ -3,12 +3,7 @@ Before any multi-agent step, read the sibling **pstack** skill: 1. `pstack/references/capability-contract.md` -2. Matching adapter under `pstack/references/adapters/`: - - `claude-code.md` — Claude Code (`Agent` / `Task`) - - `droid.md` — Factory Droid (`Task`) - - `opencode.md` — OpenCode (`task` → explore/general/…) - - `codex.md` (+ `codex-models.md`) — OpenAI Codex / replaces codex-pstack - - `cursor.md` — Cursor (prefer official pstack plugin there) - - `generic.md` — unknown host (still parallelize if a spawn tool exists) - -If the `pstack` skill is missing, use whatever `Agent`/`Task`/`task` tool the host exposes with disjoint scopes; otherwise execute locally. +2. The matching adapter under `pstack/references/adapters/` for the active host (`claude-code`, `codex`, `droid`, `opencode`, `cursor`, or `generic`). + +Map capability verbs through that adapter. Do not invent tool parameters from another host. If spawning is unavailable, execute on the lead agent and say so. + diff --git a/skills/principle-exhaust-the-design-space/SKILL.md b/skills/principle-exhaust-the-design-space/SKILL.md index 685e8a7..a44b97b 100644 --- a/skills/principle-exhaust-the-design-space/SKILL.md +++ b/skills/principle-exhaust-the-design-space/SKILL.md @@ -9,18 +9,12 @@ compatibility: Works with Agent Skills-compatible coding agents. Multi-agent opt ## Portability (required) -This skill is part of the portable **pstack** pack for multiple coding agents. - -1. Read `pstack` skill `references/capability-contract.md` (or this skill's `references/capability-contract.md` if present). -2. Detect the runtime and read one adapter before any delegation: - - Cursor → `references/adapters/cursor.md` (under the `pstack` or `poteto-mode` skill) - - Codex → `references/adapters/codex.md` - - Anything else / unsure → `references/adapters/generic.md` -3. Translate upstream Cursor mechanics through the adapter. Do **not** invent Cursor `Task` / `poteto-agent` / model slugs on runtimes that lack them. -4. If multi-agent tools are unavailable, collapse parallel work onto the main agent and say so briefly. - -Capability verbs: `explore`, `implement`, `review`, `parallel`, `ask_user`, `verify`, `model_role`. +This skill is part of the portable **pstack** pack. +1. Read the `pstack` capability contract and the adapter for the active coding agent before any helper delegation. +2. Prefer capability verbs (`explore`, `implement`, `review`, `parallel`, `ask_user`, `verify`, `model_role`) over vendor tool names. +3. Resolve models through `model_role`. Never require a vendor-specific model identifier. +4. When helper spawning is unavailable, run the work on the lead agent and state that fan-out was collapsed. When a novel interaction or architectural decision has no established precedent, explore several concrete alternatives before implementation. Building the wrong thing costs more than exploring three options. diff --git a/skills/principle-exhaust-the-design-space/references/runtime.md b/skills/principle-exhaust-the-design-space/references/runtime.md index df0e238..d9172df 100644 --- a/skills/principle-exhaust-the-design-space/references/runtime.md +++ b/skills/principle-exhaust-the-design-space/references/runtime.md @@ -3,12 +3,7 @@ Before any multi-agent step, read the sibling **pstack** skill: 1. `pstack/references/capability-contract.md` -2. Matching adapter under `pstack/references/adapters/`: - - `claude-code.md` — Claude Code (`Agent` / `Task`) - - `droid.md` — Factory Droid (`Task`) - - `opencode.md` — OpenCode (`task` → explore/general/…) - - `codex.md` (+ `codex-models.md`) — OpenAI Codex / replaces codex-pstack - - `cursor.md` — Cursor (prefer official pstack plugin there) - - `generic.md` — unknown host (still parallelize if a spawn tool exists) - -If the `pstack` skill is missing, use whatever `Agent`/`Task`/`task` tool the host exposes with disjoint scopes; otherwise execute locally. +2. The matching adapter under `pstack/references/adapters/` for the active host (`claude-code`, `codex`, `droid`, `opencode`, `cursor`, or `generic`). + +Map capability verbs through that adapter. Do not invent tool parameters from another host. If spawning is unavailable, execute on the lead agent and say so. + diff --git a/skills/principle-experience-first/SKILL.md b/skills/principle-experience-first/SKILL.md index d5a04c8..06cc110 100644 --- a/skills/principle-experience-first/SKILL.md +++ b/skills/principle-experience-first/SKILL.md @@ -9,18 +9,12 @@ compatibility: Works with Agent Skills-compatible coding agents. Multi-agent opt ## Portability (required) -This skill is part of the portable **pstack** pack for multiple coding agents. - -1. Read `pstack` skill `references/capability-contract.md` (or this skill's `references/capability-contract.md` if present). -2. Detect the runtime and read one adapter before any delegation: - - Cursor → `references/adapters/cursor.md` (under the `pstack` or `poteto-mode` skill) - - Codex → `references/adapters/codex.md` - - Anything else / unsure → `references/adapters/generic.md` -3. Translate upstream Cursor mechanics through the adapter. Do **not** invent Cursor `Task` / `poteto-agent` / model slugs on runtimes that lack them. -4. If multi-agent tools are unavailable, collapse parallel work onto the main agent and say so briefly. - -Capability verbs: `explore`, `implement`, `review`, `parallel`, `ask_user`, `verify`, `model_role`. +This skill is part of the portable **pstack** pack. +1. Read the `pstack` capability contract and the adapter for the active coding agent before any helper delegation. +2. Prefer capability verbs (`explore`, `implement`, `review`, `parallel`, `ask_user`, `verify`, `model_role`) over vendor tool names. +3. Resolve models through `model_role`. Never require a vendor-specific model identifier. +4. When helper spawning is unavailable, run the work on the lead agent and state that fan-out was collapsed. The product is the experience. Every technical decision either helps or hurts it. When implementation convenience conflicts with user delight, choose delight. diff --git a/skills/principle-experience-first/references/runtime.md b/skills/principle-experience-first/references/runtime.md index df0e238..d9172df 100644 --- a/skills/principle-experience-first/references/runtime.md +++ b/skills/principle-experience-first/references/runtime.md @@ -3,12 +3,7 @@ Before any multi-agent step, read the sibling **pstack** skill: 1. `pstack/references/capability-contract.md` -2. Matching adapter under `pstack/references/adapters/`: - - `claude-code.md` — Claude Code (`Agent` / `Task`) - - `droid.md` — Factory Droid (`Task`) - - `opencode.md` — OpenCode (`task` → explore/general/…) - - `codex.md` (+ `codex-models.md`) — OpenAI Codex / replaces codex-pstack - - `cursor.md` — Cursor (prefer official pstack plugin there) - - `generic.md` — unknown host (still parallelize if a spawn tool exists) - -If the `pstack` skill is missing, use whatever `Agent`/`Task`/`task` tool the host exposes with disjoint scopes; otherwise execute locally. +2. The matching adapter under `pstack/references/adapters/` for the active host (`claude-code`, `codex`, `droid`, `opencode`, `cursor`, or `generic`). + +Map capability verbs through that adapter. Do not invent tool parameters from another host. If spawning is unavailable, execute on the lead agent and say so. + diff --git a/skills/principle-fix-root-causes/SKILL.md b/skills/principle-fix-root-causes/SKILL.md index fe03177..7c668a9 100644 --- a/skills/principle-fix-root-causes/SKILL.md +++ b/skills/principle-fix-root-causes/SKILL.md @@ -9,18 +9,12 @@ compatibility: Works with Agent Skills-compatible coding agents. Multi-agent opt ## Portability (required) -This skill is part of the portable **pstack** pack for multiple coding agents. - -1. Read `pstack` skill `references/capability-contract.md` (or this skill's `references/capability-contract.md` if present). -2. Detect the runtime and read one adapter before any delegation: - - Cursor → `references/adapters/cursor.md` (under the `pstack` or `poteto-mode` skill) - - Codex → `references/adapters/codex.md` - - Anything else / unsure → `references/adapters/generic.md` -3. Translate upstream Cursor mechanics through the adapter. Do **not** invent Cursor `Task` / `poteto-agent` / model slugs on runtimes that lack them. -4. If multi-agent tools are unavailable, collapse parallel work onto the main agent and say so briefly. - -Capability verbs: `explore`, `implement`, `review`, `parallel`, `ask_user`, `verify`, `model_role`. +This skill is part of the portable **pstack** pack. +1. Read the `pstack` capability contract and the adapter for the active coding agent before any helper delegation. +2. Prefer capability verbs (`explore`, `implement`, `review`, `parallel`, `ask_user`, `verify`, `model_role`) over vendor tool names. +3. Resolve models through `model_role`. Never require a vendor-specific model identifier. +4. When helper spawning is unavailable, run the work on the lead agent and state that fan-out was collapsed. When debugging, do not paper over symptoms. Trace every problem to its root cause and fix it there. diff --git a/skills/principle-fix-root-causes/references/runtime.md b/skills/principle-fix-root-causes/references/runtime.md index df0e238..d9172df 100644 --- a/skills/principle-fix-root-causes/references/runtime.md +++ b/skills/principle-fix-root-causes/references/runtime.md @@ -3,12 +3,7 @@ Before any multi-agent step, read the sibling **pstack** skill: 1. `pstack/references/capability-contract.md` -2. Matching adapter under `pstack/references/adapters/`: - - `claude-code.md` — Claude Code (`Agent` / `Task`) - - `droid.md` — Factory Droid (`Task`) - - `opencode.md` — OpenCode (`task` → explore/general/…) - - `codex.md` (+ `codex-models.md`) — OpenAI Codex / replaces codex-pstack - - `cursor.md` — Cursor (prefer official pstack plugin there) - - `generic.md` — unknown host (still parallelize if a spawn tool exists) - -If the `pstack` skill is missing, use whatever `Agent`/`Task`/`task` tool the host exposes with disjoint scopes; otherwise execute locally. +2. The matching adapter under `pstack/references/adapters/` for the active host (`claude-code`, `codex`, `droid`, `opencode`, `cursor`, or `generic`). + +Map capability verbs through that adapter. Do not invent tool parameters from another host. If spawning is unavailable, execute on the lead agent and say so. + diff --git a/skills/principle-foundational-thinking/SKILL.md b/skills/principle-foundational-thinking/SKILL.md index cf762c7..65ee577 100644 --- a/skills/principle-foundational-thinking/SKILL.md +++ b/skills/principle-foundational-thinking/SKILL.md @@ -9,18 +9,12 @@ compatibility: Works with Agent Skills-compatible coding agents. Multi-agent opt ## Portability (required) -This skill is part of the portable **pstack** pack for multiple coding agents. - -1. Read `pstack` skill `references/capability-contract.md` (or this skill's `references/capability-contract.md` if present). -2. Detect the runtime and read one adapter before any delegation: - - Cursor → `references/adapters/cursor.md` (under the `pstack` or `poteto-mode` skill) - - Codex → `references/adapters/codex.md` - - Anything else / unsure → `references/adapters/generic.md` -3. Translate upstream Cursor mechanics through the adapter. Do **not** invent Cursor `Task` / `poteto-agent` / model slugs on runtimes that lack them. -4. If multi-agent tools are unavailable, collapse parallel work onto the main agent and say so briefly. - -Capability verbs: `explore`, `implement`, `review`, `parallel`, `ask_user`, `verify`, `model_role`. +This skill is part of the portable **pstack** pack. +1. Read the `pstack` capability contract and the adapter for the active coding agent before any helper delegation. +2. Prefer capability verbs (`explore`, `implement`, `review`, `parallel`, `ask_user`, `verify`, `model_role`) over vendor tool names. +3. Resolve models through `model_role`. Never require a vendor-specific model identifier. +4. When helper spawning is unavailable, run the work on the lead agent and state that fan-out was collapsed. **Structural decisions** protect option value. **Code-level decisions** protect simplicity. Over-engineering is often a premature decision that closes doors. The right foundational data structure keeps doors open. diff --git a/skills/principle-foundational-thinking/references/runtime.md b/skills/principle-foundational-thinking/references/runtime.md index df0e238..d9172df 100644 --- a/skills/principle-foundational-thinking/references/runtime.md +++ b/skills/principle-foundational-thinking/references/runtime.md @@ -3,12 +3,7 @@ Before any multi-agent step, read the sibling **pstack** skill: 1. `pstack/references/capability-contract.md` -2. Matching adapter under `pstack/references/adapters/`: - - `claude-code.md` — Claude Code (`Agent` / `Task`) - - `droid.md` — Factory Droid (`Task`) - - `opencode.md` — OpenCode (`task` → explore/general/…) - - `codex.md` (+ `codex-models.md`) — OpenAI Codex / replaces codex-pstack - - `cursor.md` — Cursor (prefer official pstack plugin there) - - `generic.md` — unknown host (still parallelize if a spawn tool exists) - -If the `pstack` skill is missing, use whatever `Agent`/`Task`/`task` tool the host exposes with disjoint scopes; otherwise execute locally. +2. The matching adapter under `pstack/references/adapters/` for the active host (`claude-code`, `codex`, `droid`, `opencode`, `cursor`, or `generic`). + +Map capability verbs through that adapter. Do not invent tool parameters from another host. If spawning is unavailable, execute on the lead agent and say so. + diff --git a/skills/principle-guard-the-context-window/SKILL.md b/skills/principle-guard-the-context-window/SKILL.md index 042dff9..6445571 100644 --- a/skills/principle-guard-the-context-window/SKILL.md +++ b/skills/principle-guard-the-context-window/SKILL.md @@ -9,18 +9,12 @@ compatibility: Works with Agent Skills-compatible coding agents. Multi-agent opt ## Portability (required) -This skill is part of the portable **pstack** pack for multiple coding agents. - -1. Read `pstack` skill `references/capability-contract.md` (or this skill's `references/capability-contract.md` if present). -2. Detect the runtime and read one adapter before any delegation: - - Cursor → `references/adapters/cursor.md` (under the `pstack` or `poteto-mode` skill) - - Codex → `references/adapters/codex.md` - - Anything else / unsure → `references/adapters/generic.md` -3. Translate upstream Cursor mechanics through the adapter. Do **not** invent Cursor `Task` / `poteto-agent` / model slugs on runtimes that lack them. -4. If multi-agent tools are unavailable, collapse parallel work onto the main agent and say so briefly. - -Capability verbs: `explore`, `implement`, `review`, `parallel`, `ask_user`, `verify`, `model_role`. +This skill is part of the portable **pstack** pack. +1. Read the `pstack` capability contract and the adapter for the active coding agent before any helper delegation. +2. Prefer capability verbs (`explore`, `implement`, `review`, `parallel`, `ask_user`, `verify`, `model_role`) over vendor tool names. +3. Resolve models through `model_role`. Never require a vendor-specific model identifier. +4. When helper spawning is unavailable, run the work on the lead agent and state that fan-out was collapsed. The context window is finite and non-renewable within a session. Every token that enters should earn its place. diff --git a/skills/principle-guard-the-context-window/references/runtime.md b/skills/principle-guard-the-context-window/references/runtime.md index df0e238..d9172df 100644 --- a/skills/principle-guard-the-context-window/references/runtime.md +++ b/skills/principle-guard-the-context-window/references/runtime.md @@ -3,12 +3,7 @@ Before any multi-agent step, read the sibling **pstack** skill: 1. `pstack/references/capability-contract.md` -2. Matching adapter under `pstack/references/adapters/`: - - `claude-code.md` — Claude Code (`Agent` / `Task`) - - `droid.md` — Factory Droid (`Task`) - - `opencode.md` — OpenCode (`task` → explore/general/…) - - `codex.md` (+ `codex-models.md`) — OpenAI Codex / replaces codex-pstack - - `cursor.md` — Cursor (prefer official pstack plugin there) - - `generic.md` — unknown host (still parallelize if a spawn tool exists) - -If the `pstack` skill is missing, use whatever `Agent`/`Task`/`task` tool the host exposes with disjoint scopes; otherwise execute locally. +2. The matching adapter under `pstack/references/adapters/` for the active host (`claude-code`, `codex`, `droid`, `opencode`, `cursor`, or `generic`). + +Map capability verbs through that adapter. Do not invent tool parameters from another host. If spawning is unavailable, execute on the lead agent and say so. + diff --git a/skills/principle-laziness-protocol/SKILL.md b/skills/principle-laziness-protocol/SKILL.md index 19cbb55..9dfa969 100644 --- a/skills/principle-laziness-protocol/SKILL.md +++ b/skills/principle-laziness-protocol/SKILL.md @@ -9,18 +9,12 @@ compatibility: Works with Agent Skills-compatible coding agents. Multi-agent opt ## Portability (required) -This skill is part of the portable **pstack** pack for multiple coding agents. - -1. Read `pstack` skill `references/capability-contract.md` (or this skill's `references/capability-contract.md` if present). -2. Detect the runtime and read one adapter before any delegation: - - Cursor → `references/adapters/cursor.md` (under the `pstack` or `poteto-mode` skill) - - Codex → `references/adapters/codex.md` - - Anything else / unsure → `references/adapters/generic.md` -3. Translate upstream Cursor mechanics through the adapter. Do **not** invent Cursor `Task` / `poteto-agent` / model slugs on runtimes that lack them. -4. If multi-agent tools are unavailable, collapse parallel work onto the main agent and say so briefly. - -Capability verbs: `explore`, `implement`, `review`, `parallel`, `ask_user`, `verify`, `model_role`. +This skill is part of the portable **pstack** pack. +1. Read the `pstack` capability contract and the adapter for the active coding agent before any helper delegation. +2. Prefer capability verbs (`explore`, `implement`, `review`, `parallel`, `ask_user`, `verify`, `model_role`) over vendor tool names. +3. Resolve models through `model_role`. Never require a vendor-specific model identifier. +4. When helper spawning is unavailable, run the work on the lead agent and state that fan-out was collapsed. Writing code is cheap for you, which makes over-engineering easy. Counter it by borrowing a human maintainer's fatigue. Aim for the most result with the least code and complexity. diff --git a/skills/principle-laziness-protocol/references/runtime.md b/skills/principle-laziness-protocol/references/runtime.md index df0e238..d9172df 100644 --- a/skills/principle-laziness-protocol/references/runtime.md +++ b/skills/principle-laziness-protocol/references/runtime.md @@ -3,12 +3,7 @@ Before any multi-agent step, read the sibling **pstack** skill: 1. `pstack/references/capability-contract.md` -2. Matching adapter under `pstack/references/adapters/`: - - `claude-code.md` — Claude Code (`Agent` / `Task`) - - `droid.md` — Factory Droid (`Task`) - - `opencode.md` — OpenCode (`task` → explore/general/…) - - `codex.md` (+ `codex-models.md`) — OpenAI Codex / replaces codex-pstack - - `cursor.md` — Cursor (prefer official pstack plugin there) - - `generic.md` — unknown host (still parallelize if a spawn tool exists) - -If the `pstack` skill is missing, use whatever `Agent`/`Task`/`task` tool the host exposes with disjoint scopes; otherwise execute locally. +2. The matching adapter under `pstack/references/adapters/` for the active host (`claude-code`, `codex`, `droid`, `opencode`, `cursor`, or `generic`). + +Map capability verbs through that adapter. Do not invent tool parameters from another host. If spawning is unavailable, execute on the lead agent and say so. + diff --git a/skills/principle-make-operations-idempotent/SKILL.md b/skills/principle-make-operations-idempotent/SKILL.md index 5b74eba..914364a 100644 --- a/skills/principle-make-operations-idempotent/SKILL.md +++ b/skills/principle-make-operations-idempotent/SKILL.md @@ -9,18 +9,12 @@ compatibility: Works with Agent Skills-compatible coding agents. Multi-agent opt ## Portability (required) -This skill is part of the portable **pstack** pack for multiple coding agents. - -1. Read `pstack` skill `references/capability-contract.md` (or this skill's `references/capability-contract.md` if present). -2. Detect the runtime and read one adapter before any delegation: - - Cursor → `references/adapters/cursor.md` (under the `pstack` or `poteto-mode` skill) - - Codex → `references/adapters/codex.md` - - Anything else / unsure → `references/adapters/generic.md` -3. Translate upstream Cursor mechanics through the adapter. Do **not** invent Cursor `Task` / `poteto-agent` / model slugs on runtimes that lack them. -4. If multi-agent tools are unavailable, collapse parallel work onto the main agent and say so briefly. - -Capability verbs: `explore`, `implement`, `review`, `parallel`, `ask_user`, `verify`, `model_role`. +This skill is part of the portable **pstack** pack. +1. Read the `pstack` capability contract and the adapter for the active coding agent before any helper delegation. +2. Prefer capability verbs (`explore`, `implement`, `review`, `parallel`, `ask_user`, `verify`, `model_role`) over vendor tool names. +3. Resolve models through `model_role`. Never require a vendor-specific model identifier. +4. When helper spawning is unavailable, run the work on the lead agent and state that fan-out was collapsed. Design operations so they converge to the correct state regardless of how many times they run or where they start from. Every state-mutating operation should answer: "What happens if this runs twice? What happens if the previous run crashed halfway?" diff --git a/skills/principle-make-operations-idempotent/references/runtime.md b/skills/principle-make-operations-idempotent/references/runtime.md index df0e238..d9172df 100644 --- a/skills/principle-make-operations-idempotent/references/runtime.md +++ b/skills/principle-make-operations-idempotent/references/runtime.md @@ -3,12 +3,7 @@ Before any multi-agent step, read the sibling **pstack** skill: 1. `pstack/references/capability-contract.md` -2. Matching adapter under `pstack/references/adapters/`: - - `claude-code.md` — Claude Code (`Agent` / `Task`) - - `droid.md` — Factory Droid (`Task`) - - `opencode.md` — OpenCode (`task` → explore/general/…) - - `codex.md` (+ `codex-models.md`) — OpenAI Codex / replaces codex-pstack - - `cursor.md` — Cursor (prefer official pstack plugin there) - - `generic.md` — unknown host (still parallelize if a spawn tool exists) - -If the `pstack` skill is missing, use whatever `Agent`/`Task`/`task` tool the host exposes with disjoint scopes; otherwise execute locally. +2. The matching adapter under `pstack/references/adapters/` for the active host (`claude-code`, `codex`, `droid`, `opencode`, `cursor`, or `generic`). + +Map capability verbs through that adapter. Do not invent tool parameters from another host. If spawning is unavailable, execute on the lead agent and say so. + diff --git a/skills/principle-migrate-callers-then-delete-legacy-apis/SKILL.md b/skills/principle-migrate-callers-then-delete-legacy-apis/SKILL.md index b6c517d..02b80a1 100644 --- a/skills/principle-migrate-callers-then-delete-legacy-apis/SKILL.md +++ b/skills/principle-migrate-callers-then-delete-legacy-apis/SKILL.md @@ -9,18 +9,12 @@ compatibility: Works with Agent Skills-compatible coding agents. Multi-agent opt ## Portability (required) -This skill is part of the portable **pstack** pack for multiple coding agents. - -1. Read `pstack` skill `references/capability-contract.md` (or this skill's `references/capability-contract.md` if present). -2. Detect the runtime and read one adapter before any delegation: - - Cursor → `references/adapters/cursor.md` (under the `pstack` or `poteto-mode` skill) - - Codex → `references/adapters/codex.md` - - Anything else / unsure → `references/adapters/generic.md` -3. Translate upstream Cursor mechanics through the adapter. Do **not** invent Cursor `Task` / `poteto-agent` / model slugs on runtimes that lack them. -4. If multi-agent tools are unavailable, collapse parallel work onto the main agent and say so briefly. - -Capability verbs: `explore`, `implement`, `review`, `parallel`, `ask_user`, `verify`, `model_role`. +This skill is part of the portable **pstack** pack. +1. Read the `pstack` capability contract and the adapter for the active coding agent before any helper delegation. +2. Prefer capability verbs (`explore`, `implement`, `review`, `parallel`, `ask_user`, `verify`, `model_role`) over vendor tool names. +3. Resolve models through `model_role`. Never require a vendor-specific model identifier. +4. When helper spawning is unavailable, run the work on the lead agent and state that fan-out was collapsed. When we decide a new API is the right design, migrate callers and remove the old API in the same refactor wave instead of preserving compatibility layers. diff --git a/skills/principle-migrate-callers-then-delete-legacy-apis/references/runtime.md b/skills/principle-migrate-callers-then-delete-legacy-apis/references/runtime.md index df0e238..d9172df 100644 --- a/skills/principle-migrate-callers-then-delete-legacy-apis/references/runtime.md +++ b/skills/principle-migrate-callers-then-delete-legacy-apis/references/runtime.md @@ -3,12 +3,7 @@ Before any multi-agent step, read the sibling **pstack** skill: 1. `pstack/references/capability-contract.md` -2. Matching adapter under `pstack/references/adapters/`: - - `claude-code.md` — Claude Code (`Agent` / `Task`) - - `droid.md` — Factory Droid (`Task`) - - `opencode.md` — OpenCode (`task` → explore/general/…) - - `codex.md` (+ `codex-models.md`) — OpenAI Codex / replaces codex-pstack - - `cursor.md` — Cursor (prefer official pstack plugin there) - - `generic.md` — unknown host (still parallelize if a spawn tool exists) - -If the `pstack` skill is missing, use whatever `Agent`/`Task`/`task` tool the host exposes with disjoint scopes; otherwise execute locally. +2. The matching adapter under `pstack/references/adapters/` for the active host (`claude-code`, `codex`, `droid`, `opencode`, `cursor`, or `generic`). + +Map capability verbs through that adapter. Do not invent tool parameters from another host. If spawning is unavailable, execute on the lead agent and say so. + diff --git a/skills/principle-minimize-reader-load/SKILL.md b/skills/principle-minimize-reader-load/SKILL.md index f145bf9..db187e0 100644 --- a/skills/principle-minimize-reader-load/SKILL.md +++ b/skills/principle-minimize-reader-load/SKILL.md @@ -9,18 +9,12 @@ compatibility: Works with Agent Skills-compatible coding agents. Multi-agent opt ## Portability (required) -This skill is part of the portable **pstack** pack for multiple coding agents. - -1. Read `pstack` skill `references/capability-contract.md` (or this skill's `references/capability-contract.md` if present). -2. Detect the runtime and read one adapter before any delegation: - - Cursor → `references/adapters/cursor.md` (under the `pstack` or `poteto-mode` skill) - - Codex → `references/adapters/codex.md` - - Anything else / unsure → `references/adapters/generic.md` -3. Translate upstream Cursor mechanics through the adapter. Do **not** invent Cursor `Task` / `poteto-agent` / model slugs on runtimes that lack them. -4. If multi-agent tools are unavailable, collapse parallel work onto the main agent and say so briefly. - -Capability verbs: `explore`, `implement`, `review`, `parallel`, `ask_user`, `verify`, `model_role`. +This skill is part of the portable **pstack** pack. +1. Read the `pstack` capability contract and the adapter for the active coding agent before any helper delegation. +2. Prefer capability verbs (`explore`, `implement`, `review`, `parallel`, `ask_user`, `verify`, `model_role`) over vendor tool names. +3. Resolve models through `model_role`. Never require a vendor-specific model identifier. +4. When helper spawning is unavailable, run the work on the lead agent and state that fan-out was collapsed. Maintainability is the work a reader must do to understand code. Track two axes: 1. **Layers to trace.** How many indirections sit between the question and the answer. diff --git a/skills/principle-minimize-reader-load/references/runtime.md b/skills/principle-minimize-reader-load/references/runtime.md index df0e238..d9172df 100644 --- a/skills/principle-minimize-reader-load/references/runtime.md +++ b/skills/principle-minimize-reader-load/references/runtime.md @@ -3,12 +3,7 @@ Before any multi-agent step, read the sibling **pstack** skill: 1. `pstack/references/capability-contract.md` -2. Matching adapter under `pstack/references/adapters/`: - - `claude-code.md` — Claude Code (`Agent` / `Task`) - - `droid.md` — Factory Droid (`Task`) - - `opencode.md` — OpenCode (`task` → explore/general/…) - - `codex.md` (+ `codex-models.md`) — OpenAI Codex / replaces codex-pstack - - `cursor.md` — Cursor (prefer official pstack plugin there) - - `generic.md` — unknown host (still parallelize if a spawn tool exists) - -If the `pstack` skill is missing, use whatever `Agent`/`Task`/`task` tool the host exposes with disjoint scopes; otherwise execute locally. +2. The matching adapter under `pstack/references/adapters/` for the active host (`claude-code`, `codex`, `droid`, `opencode`, `cursor`, or `generic`). + +Map capability verbs through that adapter. Do not invent tool parameters from another host. If spawning is unavailable, execute on the lead agent and say so. + diff --git a/skills/principle-model-the-domain/SKILL.md b/skills/principle-model-the-domain/SKILL.md index aefd5a1..90a99e7 100644 --- a/skills/principle-model-the-domain/SKILL.md +++ b/skills/principle-model-the-domain/SKILL.md @@ -9,18 +9,12 @@ compatibility: Works with Agent Skills-compatible coding agents. Multi-agent opt ## Portability (required) -This skill is part of the portable **pstack** pack for multiple coding agents. - -1. Read `pstack` skill `references/capability-contract.md` (or this skill's `references/capability-contract.md` if present). -2. Detect the runtime and read one adapter before any delegation: - - Cursor → `references/adapters/cursor.md` (under the `pstack` or `poteto-mode` skill) - - Codex → `references/adapters/codex.md` - - Anything else / unsure → `references/adapters/generic.md` -3. Translate upstream Cursor mechanics through the adapter. Do **not** invent Cursor `Task` / `poteto-agent` / model slugs on runtimes that lack them. -4. If multi-agent tools are unavailable, collapse parallel work onto the main agent and say so briefly. - -Capability verbs: `explore`, `implement`, `review`, `parallel`, `ask_user`, `verify`, `model_role`. +This skill is part of the portable **pstack** pack. +1. Read the `pstack` capability contract and the adapter for the active coding agent before any helper delegation. +2. Prefer capability verbs (`explore`, `implement`, `review`, `parallel`, `ask_user`, `verify`, `model_role`) over vendor tool names. +3. Resolve models through `model_role`. Never require a vendor-specific model identifier. +4. When helper spawning is unavailable, run the work on the lead agent and state that fan-out was collapsed. Encode the real domain in a data structure instead of scattering it across conditionals. diff --git a/skills/principle-model-the-domain/references/runtime.md b/skills/principle-model-the-domain/references/runtime.md index df0e238..d9172df 100644 --- a/skills/principle-model-the-domain/references/runtime.md +++ b/skills/principle-model-the-domain/references/runtime.md @@ -3,12 +3,7 @@ Before any multi-agent step, read the sibling **pstack** skill: 1. `pstack/references/capability-contract.md` -2. Matching adapter under `pstack/references/adapters/`: - - `claude-code.md` — Claude Code (`Agent` / `Task`) - - `droid.md` — Factory Droid (`Task`) - - `opencode.md` — OpenCode (`task` → explore/general/…) - - `codex.md` (+ `codex-models.md`) — OpenAI Codex / replaces codex-pstack - - `cursor.md` — Cursor (prefer official pstack plugin there) - - `generic.md` — unknown host (still parallelize if a spawn tool exists) - -If the `pstack` skill is missing, use whatever `Agent`/`Task`/`task` tool the host exposes with disjoint scopes; otherwise execute locally. +2. The matching adapter under `pstack/references/adapters/` for the active host (`claude-code`, `codex`, `droid`, `opencode`, `cursor`, or `generic`). + +Map capability verbs through that adapter. Do not invent tool parameters from another host. If spawning is unavailable, execute on the lead agent and say so. + diff --git a/skills/principle-never-block-on-the-human/SKILL.md b/skills/principle-never-block-on-the-human/SKILL.md index 3cc858a..cf88c46 100644 --- a/skills/principle-never-block-on-the-human/SKILL.md +++ b/skills/principle-never-block-on-the-human/SKILL.md @@ -9,18 +9,12 @@ compatibility: Works with Agent Skills-compatible coding agents. Multi-agent opt ## Portability (required) -This skill is part of the portable **pstack** pack for multiple coding agents. - -1. Read `pstack` skill `references/capability-contract.md` (or this skill's `references/capability-contract.md` if present). -2. Detect the runtime and read one adapter before any delegation: - - Cursor → `references/adapters/cursor.md` (under the `pstack` or `poteto-mode` skill) - - Codex → `references/adapters/codex.md` - - Anything else / unsure → `references/adapters/generic.md` -3. Translate upstream Cursor mechanics through the adapter. Do **not** invent Cursor `Task` / `poteto-agent` / model slugs on runtimes that lack them. -4. If multi-agent tools are unavailable, collapse parallel work onto the main agent and say so briefly. - -Capability verbs: `explore`, `implement`, `review`, `parallel`, `ask_user`, `verify`, `model_role`. +This skill is part of the portable **pstack** pack. +1. Read the `pstack` capability contract and the adapter for the active coding agent before any helper delegation. +2. Prefer capability verbs (`explore`, `implement`, `review`, `parallel`, `ask_user`, `verify`, `model_role`) over vendor tool names. +3. Resolve models through `model_role`. Never require a vendor-specific model identifier. +4. When helper spawning is unavailable, run the work on the lead agent and state that fan-out was collapsed. The human supervises asynchronously. Agents must stay unblocked: make reasonable decisions, proceed, and let the human course-correct after the fact. Code is cheap. Waiting is expensive. diff --git a/skills/principle-never-block-on-the-human/references/runtime.md b/skills/principle-never-block-on-the-human/references/runtime.md index df0e238..d9172df 100644 --- a/skills/principle-never-block-on-the-human/references/runtime.md +++ b/skills/principle-never-block-on-the-human/references/runtime.md @@ -3,12 +3,7 @@ Before any multi-agent step, read the sibling **pstack** skill: 1. `pstack/references/capability-contract.md` -2. Matching adapter under `pstack/references/adapters/`: - - `claude-code.md` — Claude Code (`Agent` / `Task`) - - `droid.md` — Factory Droid (`Task`) - - `opencode.md` — OpenCode (`task` → explore/general/…) - - `codex.md` (+ `codex-models.md`) — OpenAI Codex / replaces codex-pstack - - `cursor.md` — Cursor (prefer official pstack plugin there) - - `generic.md` — unknown host (still parallelize if a spawn tool exists) - -If the `pstack` skill is missing, use whatever `Agent`/`Task`/`task` tool the host exposes with disjoint scopes; otherwise execute locally. +2. The matching adapter under `pstack/references/adapters/` for the active host (`claude-code`, `codex`, `droid`, `opencode`, `cursor`, or `generic`). + +Map capability verbs through that adapter. Do not invent tool parameters from another host. If spawning is unavailable, execute on the lead agent and say so. + diff --git a/skills/principle-outcome-oriented-execution/SKILL.md b/skills/principle-outcome-oriented-execution/SKILL.md index ce035d1..0a5be70 100644 --- a/skills/principle-outcome-oriented-execution/SKILL.md +++ b/skills/principle-outcome-oriented-execution/SKILL.md @@ -9,18 +9,12 @@ compatibility: Works with Agent Skills-compatible coding agents. Multi-agent opt ## Portability (required) -This skill is part of the portable **pstack** pack for multiple coding agents. - -1. Read `pstack` skill `references/capability-contract.md` (or this skill's `references/capability-contract.md` if present). -2. Detect the runtime and read one adapter before any delegation: - - Cursor → `references/adapters/cursor.md` (under the `pstack` or `poteto-mode` skill) - - Codex → `references/adapters/codex.md` - - Anything else / unsure → `references/adapters/generic.md` -3. Translate upstream Cursor mechanics through the adapter. Do **not** invent Cursor `Task` / `poteto-agent` / model slugs on runtimes that lack them. -4. If multi-agent tools are unavailable, collapse parallel work onto the main agent and say so briefly. - -Capability verbs: `explore`, `implement`, `review`, `parallel`, `ask_user`, `verify`, `model_role`. +This skill is part of the portable **pstack** pack. +1. Read the `pstack` capability contract and the adapter for the active coding agent before any helper delegation. +2. Prefer capability verbs (`explore`, `implement`, `review`, `parallel`, `ask_user`, `verify`, `model_role`) over vendor tool names. +3. Resolve models through `model_role`. Never require a vendor-specific model identifier. +4. When helper spawning is unavailable, run the work on the lead agent and state that fan-out was collapsed. Optimize for the intended, verifiable end state rather than preserving smooth intermediate states. diff --git a/skills/principle-outcome-oriented-execution/references/runtime.md b/skills/principle-outcome-oriented-execution/references/runtime.md index df0e238..d9172df 100644 --- a/skills/principle-outcome-oriented-execution/references/runtime.md +++ b/skills/principle-outcome-oriented-execution/references/runtime.md @@ -3,12 +3,7 @@ Before any multi-agent step, read the sibling **pstack** skill: 1. `pstack/references/capability-contract.md` -2. Matching adapter under `pstack/references/adapters/`: - - `claude-code.md` — Claude Code (`Agent` / `Task`) - - `droid.md` — Factory Droid (`Task`) - - `opencode.md` — OpenCode (`task` → explore/general/…) - - `codex.md` (+ `codex-models.md`) — OpenAI Codex / replaces codex-pstack - - `cursor.md` — Cursor (prefer official pstack plugin there) - - `generic.md` — unknown host (still parallelize if a spawn tool exists) - -If the `pstack` skill is missing, use whatever `Agent`/`Task`/`task` tool the host exposes with disjoint scopes; otherwise execute locally. +2. The matching adapter under `pstack/references/adapters/` for the active host (`claude-code`, `codex`, `droid`, `opencode`, `cursor`, or `generic`). + +Map capability verbs through that adapter. Do not invent tool parameters from another host. If spawning is unavailable, execute on the lead agent and say so. + diff --git a/skills/principle-prove-it-works/SKILL.md b/skills/principle-prove-it-works/SKILL.md index 6b4d0be..85a9366 100644 --- a/skills/principle-prove-it-works/SKILL.md +++ b/skills/principle-prove-it-works/SKILL.md @@ -9,18 +9,12 @@ compatibility: Works with Agent Skills-compatible coding agents. Multi-agent opt ## Portability (required) -This skill is part of the portable **pstack** pack for multiple coding agents. - -1. Read `pstack` skill `references/capability-contract.md` (or this skill's `references/capability-contract.md` if present). -2. Detect the runtime and read one adapter before any delegation: - - Cursor → `references/adapters/cursor.md` (under the `pstack` or `poteto-mode` skill) - - Codex → `references/adapters/codex.md` - - Anything else / unsure → `references/adapters/generic.md` -3. Translate upstream Cursor mechanics through the adapter. Do **not** invent Cursor `Task` / `poteto-agent` / model slugs on runtimes that lack them. -4. If multi-agent tools are unavailable, collapse parallel work onto the main agent and say so briefly. - -Capability verbs: `explore`, `implement`, `review`, `parallel`, `ask_user`, `verify`, `model_role`. +This skill is part of the portable **pstack** pack. +1. Read the `pstack` capability contract and the adapter for the active coding agent before any helper delegation. +2. Prefer capability verbs (`explore`, `implement`, `review`, `parallel`, `ask_user`, `verify`, `model_role`) over vendor tool names. +3. Resolve models through `model_role`. Never require a vendor-specific model identifier. +4. When helper spawning is unavailable, run the work on the lead agent and state that fan-out was collapsed. Verify every task output by checking the real thing directly. Do not infer from proxies, self-reports, or "it compiles." diff --git a/skills/principle-prove-it-works/references/runtime.md b/skills/principle-prove-it-works/references/runtime.md index df0e238..d9172df 100644 --- a/skills/principle-prove-it-works/references/runtime.md +++ b/skills/principle-prove-it-works/references/runtime.md @@ -3,12 +3,7 @@ Before any multi-agent step, read the sibling **pstack** skill: 1. `pstack/references/capability-contract.md` -2. Matching adapter under `pstack/references/adapters/`: - - `claude-code.md` — Claude Code (`Agent` / `Task`) - - `droid.md` — Factory Droid (`Task`) - - `opencode.md` — OpenCode (`task` → explore/general/…) - - `codex.md` (+ `codex-models.md`) — OpenAI Codex / replaces codex-pstack - - `cursor.md` — Cursor (prefer official pstack plugin there) - - `generic.md` — unknown host (still parallelize if a spawn tool exists) - -If the `pstack` skill is missing, use whatever `Agent`/`Task`/`task` tool the host exposes with disjoint scopes; otherwise execute locally. +2. The matching adapter under `pstack/references/adapters/` for the active host (`claude-code`, `codex`, `droid`, `opencode`, `cursor`, or `generic`). + +Map capability verbs through that adapter. Do not invent tool parameters from another host. If spawning is unavailable, execute on the lead agent and say so. + diff --git a/skills/principle-redesign-from-first-principles/SKILL.md b/skills/principle-redesign-from-first-principles/SKILL.md index f36b7d3..33f7d28 100644 --- a/skills/principle-redesign-from-first-principles/SKILL.md +++ b/skills/principle-redesign-from-first-principles/SKILL.md @@ -9,18 +9,12 @@ compatibility: Works with Agent Skills-compatible coding agents. Multi-agent opt ## Portability (required) -This skill is part of the portable **pstack** pack for multiple coding agents. - -1. Read `pstack` skill `references/capability-contract.md` (or this skill's `references/capability-contract.md` if present). -2. Detect the runtime and read one adapter before any delegation: - - Cursor → `references/adapters/cursor.md` (under the `pstack` or `poteto-mode` skill) - - Codex → `references/adapters/codex.md` - - Anything else / unsure → `references/adapters/generic.md` -3. Translate upstream Cursor mechanics through the adapter. Do **not** invent Cursor `Task` / `poteto-agent` / model slugs on runtimes that lack them. -4. If multi-agent tools are unavailable, collapse parallel work onto the main agent and say so briefly. - -Capability verbs: `explore`, `implement`, `review`, `parallel`, `ask_user`, `verify`, `model_role`. +This skill is part of the portable **pstack** pack. +1. Read the `pstack` capability contract and the adapter for the active coding agent before any helper delegation. +2. Prefer capability verbs (`explore`, `implement`, `review`, `parallel`, `ask_user`, `verify`, `model_role`) over vendor tool names. +3. Resolve models through `model_role`. Never require a vendor-specific model identifier. +4. When helper spawning is unavailable, run the work on the lead agent and state that fan-out was collapsed. When integrating a change, don't bolt it onto the existing design. Redesign as if the requirement had been there from the start. The result should look like what we would have built if we'd known on day one. diff --git a/skills/principle-redesign-from-first-principles/references/runtime.md b/skills/principle-redesign-from-first-principles/references/runtime.md index df0e238..d9172df 100644 --- a/skills/principle-redesign-from-first-principles/references/runtime.md +++ b/skills/principle-redesign-from-first-principles/references/runtime.md @@ -3,12 +3,7 @@ Before any multi-agent step, read the sibling **pstack** skill: 1. `pstack/references/capability-contract.md` -2. Matching adapter under `pstack/references/adapters/`: - - `claude-code.md` — Claude Code (`Agent` / `Task`) - - `droid.md` — Factory Droid (`Task`) - - `opencode.md` — OpenCode (`task` → explore/general/…) - - `codex.md` (+ `codex-models.md`) — OpenAI Codex / replaces codex-pstack - - `cursor.md` — Cursor (prefer official pstack plugin there) - - `generic.md` — unknown host (still parallelize if a spawn tool exists) - -If the `pstack` skill is missing, use whatever `Agent`/`Task`/`task` tool the host exposes with disjoint scopes; otherwise execute locally. +2. The matching adapter under `pstack/references/adapters/` for the active host (`claude-code`, `codex`, `droid`, `opencode`, `cursor`, or `generic`). + +Map capability verbs through that adapter. Do not invent tool parameters from another host. If spawning is unavailable, execute on the lead agent and say so. + diff --git a/skills/principle-separate-before-serializing-shared-state/SKILL.md b/skills/principle-separate-before-serializing-shared-state/SKILL.md index 6d44f21..9288057 100644 --- a/skills/principle-separate-before-serializing-shared-state/SKILL.md +++ b/skills/principle-separate-before-serializing-shared-state/SKILL.md @@ -9,18 +9,12 @@ compatibility: Works with Agent Skills-compatible coding agents. Multi-agent opt ## Portability (required) -This skill is part of the portable **pstack** pack for multiple coding agents. - -1. Read `pstack` skill `references/capability-contract.md` (or this skill's `references/capability-contract.md` if present). -2. Detect the runtime and read one adapter before any delegation: - - Cursor → `references/adapters/cursor.md` (under the `pstack` or `poteto-mode` skill) - - Codex → `references/adapters/codex.md` - - Anything else / unsure → `references/adapters/generic.md` -3. Translate upstream Cursor mechanics through the adapter. Do **not** invent Cursor `Task` / `poteto-agent` / model slugs on runtimes that lack them. -4. If multi-agent tools are unavailable, collapse parallel work onto the main agent and say so briefly. - -Capability verbs: `explore`, `implement`, `review`, `parallel`, `ask_user`, `verify`, `model_role`. +This skill is part of the portable **pstack** pack. +1. Read the `pstack` capability contract and the adapter for the active coding agent before any helper delegation. +2. Prefer capability verbs (`explore`, `implement`, `review`, `parallel`, `ask_user`, `verify`, `model_role`) over vendor tool names. +3. Resolve models through `model_role`. Never require a vendor-specific model identifier. +4. When helper spawning is unavailable, run the work on the lead agent and state that fan-out was collapsed. When concurrent actors might share mutable state, first ask whether they truly need the same mutable object. If not, eliminate the sharing. When sharing is real, enforce serialization structurally: lockfiles, sequential phases, exclusive ownership. Instructions and conventions are not concurrency control. diff --git a/skills/principle-separate-before-serializing-shared-state/references/runtime.md b/skills/principle-separate-before-serializing-shared-state/references/runtime.md index df0e238..d9172df 100644 --- a/skills/principle-separate-before-serializing-shared-state/references/runtime.md +++ b/skills/principle-separate-before-serializing-shared-state/references/runtime.md @@ -3,12 +3,7 @@ Before any multi-agent step, read the sibling **pstack** skill: 1. `pstack/references/capability-contract.md` -2. Matching adapter under `pstack/references/adapters/`: - - `claude-code.md` — Claude Code (`Agent` / `Task`) - - `droid.md` — Factory Droid (`Task`) - - `opencode.md` — OpenCode (`task` → explore/general/…) - - `codex.md` (+ `codex-models.md`) — OpenAI Codex / replaces codex-pstack - - `cursor.md` — Cursor (prefer official pstack plugin there) - - `generic.md` — unknown host (still parallelize if a spawn tool exists) - -If the `pstack` skill is missing, use whatever `Agent`/`Task`/`task` tool the host exposes with disjoint scopes; otherwise execute locally. +2. The matching adapter under `pstack/references/adapters/` for the active host (`claude-code`, `codex`, `droid`, `opencode`, `cursor`, or `generic`). + +Map capability verbs through that adapter. Do not invent tool parameters from another host. If spawning is unavailable, execute on the lead agent and say so. + diff --git a/skills/principle-sequence-verifiable-units/SKILL.md b/skills/principle-sequence-verifiable-units/SKILL.md index 03323e1..035fe5d 100644 --- a/skills/principle-sequence-verifiable-units/SKILL.md +++ b/skills/principle-sequence-verifiable-units/SKILL.md @@ -9,18 +9,12 @@ compatibility: Works with Agent Skills-compatible coding agents. Multi-agent opt ## Portability (required) -This skill is part of the portable **pstack** pack for multiple coding agents. - -1. Read `pstack` skill `references/capability-contract.md` (or this skill's `references/capability-contract.md` if present). -2. Detect the runtime and read one adapter before any delegation: - - Cursor → `references/adapters/cursor.md` (under the `pstack` or `poteto-mode` skill) - - Codex → `references/adapters/codex.md` - - Anything else / unsure → `references/adapters/generic.md` -3. Translate upstream Cursor mechanics through the adapter. Do **not** invent Cursor `Task` / `poteto-agent` / model slugs on runtimes that lack them. -4. If multi-agent tools are unavailable, collapse parallel work onto the main agent and say so briefly. - -Capability verbs: `explore`, `implement`, `review`, `parallel`, `ask_user`, `verify`, `model_role`. +This skill is part of the portable **pstack** pack. +1. Read the `pstack` capability contract and the adapter for the active coding agent before any helper delegation. +2. Prefer capability verbs (`explore`, `implement`, `review`, `parallel`, `ask_user`, `verify`, `model_role`) over vendor tool names. +3. Resolve models through `model_role`. Never require a vendor-specific model identifier. +4. When helper spawning is unavailable, run the work on the lead agent and state that fan-out was collapsed. Order work as a sequence of small units, each ending in a state you can check, and don't advance until the current one is green. The same discipline runs at two altitudes, how you execute and how you deliver. diff --git a/skills/principle-sequence-verifiable-units/references/runtime.md b/skills/principle-sequence-verifiable-units/references/runtime.md index df0e238..d9172df 100644 --- a/skills/principle-sequence-verifiable-units/references/runtime.md +++ b/skills/principle-sequence-verifiable-units/references/runtime.md @@ -3,12 +3,7 @@ Before any multi-agent step, read the sibling **pstack** skill: 1. `pstack/references/capability-contract.md` -2. Matching adapter under `pstack/references/adapters/`: - - `claude-code.md` — Claude Code (`Agent` / `Task`) - - `droid.md` — Factory Droid (`Task`) - - `opencode.md` — OpenCode (`task` → explore/general/…) - - `codex.md` (+ `codex-models.md`) — OpenAI Codex / replaces codex-pstack - - `cursor.md` — Cursor (prefer official pstack plugin there) - - `generic.md` — unknown host (still parallelize if a spawn tool exists) - -If the `pstack` skill is missing, use whatever `Agent`/`Task`/`task` tool the host exposes with disjoint scopes; otherwise execute locally. +2. The matching adapter under `pstack/references/adapters/` for the active host (`claude-code`, `codex`, `droid`, `opencode`, `cursor`, or `generic`). + +Map capability verbs through that adapter. Do not invent tool parameters from another host. If spawning is unavailable, execute on the lead agent and say so. + diff --git a/skills/principle-subtract-before-you-add/SKILL.md b/skills/principle-subtract-before-you-add/SKILL.md index 9ccec30..31fb8dd 100644 --- a/skills/principle-subtract-before-you-add/SKILL.md +++ b/skills/principle-subtract-before-you-add/SKILL.md @@ -9,18 +9,12 @@ compatibility: Works with Agent Skills-compatible coding agents. Multi-agent opt ## Portability (required) -This skill is part of the portable **pstack** pack for multiple coding agents. - -1. Read `pstack` skill `references/capability-contract.md` (or this skill's `references/capability-contract.md` if present). -2. Detect the runtime and read one adapter before any delegation: - - Cursor → `references/adapters/cursor.md` (under the `pstack` or `poteto-mode` skill) - - Codex → `references/adapters/codex.md` - - Anything else / unsure → `references/adapters/generic.md` -3. Translate upstream Cursor mechanics through the adapter. Do **not** invent Cursor `Task` / `poteto-agent` / model slugs on runtimes that lack them. -4. If multi-agent tools are unavailable, collapse parallel work onto the main agent and say so briefly. - -Capability verbs: `explore`, `implement`, `review`, `parallel`, `ask_user`, `verify`, `model_role`. +This skill is part of the portable **pstack** pack. +1. Read the `pstack` capability contract and the adapter for the active coding agent before any helper delegation. +2. Prefer capability verbs (`explore`, `implement`, `review`, `parallel`, `ask_user`, `verify`, `model_role`) over vendor tool names. +3. Resolve models through `model_role`. Never require a vendor-specific model identifier. +4. When helper spawning is unavailable, run the work on the lead agent and state that fan-out was collapsed. When evolving a system, remove complexity first, then build. Deletion gives you a simpler base, which makes the next addition smaller and less brittle. diff --git a/skills/principle-subtract-before-you-add/references/runtime.md b/skills/principle-subtract-before-you-add/references/runtime.md index df0e238..d9172df 100644 --- a/skills/principle-subtract-before-you-add/references/runtime.md +++ b/skills/principle-subtract-before-you-add/references/runtime.md @@ -3,12 +3,7 @@ Before any multi-agent step, read the sibling **pstack** skill: 1. `pstack/references/capability-contract.md` -2. Matching adapter under `pstack/references/adapters/`: - - `claude-code.md` — Claude Code (`Agent` / `Task`) - - `droid.md` — Factory Droid (`Task`) - - `opencode.md` — OpenCode (`task` → explore/general/…) - - `codex.md` (+ `codex-models.md`) — OpenAI Codex / replaces codex-pstack - - `cursor.md` — Cursor (prefer official pstack plugin there) - - `generic.md` — unknown host (still parallelize if a spawn tool exists) - -If the `pstack` skill is missing, use whatever `Agent`/`Task`/`task` tool the host exposes with disjoint scopes; otherwise execute locally. +2. The matching adapter under `pstack/references/adapters/` for the active host (`claude-code`, `codex`, `droid`, `opencode`, `cursor`, or `generic`). + +Map capability verbs through that adapter. Do not invent tool parameters from another host. If spawning is unavailable, execute on the lead agent and say so. + diff --git a/skills/principle-type-system-discipline/SKILL.md b/skills/principle-type-system-discipline/SKILL.md index bfbb9b5..6a247ae 100644 --- a/skills/principle-type-system-discipline/SKILL.md +++ b/skills/principle-type-system-discipline/SKILL.md @@ -9,18 +9,12 @@ compatibility: Works with Agent Skills-compatible coding agents. Multi-agent opt ## Portability (required) -This skill is part of the portable **pstack** pack for multiple coding agents. - -1. Read `pstack` skill `references/capability-contract.md` (or this skill's `references/capability-contract.md` if present). -2. Detect the runtime and read one adapter before any delegation: - - Cursor → `references/adapters/cursor.md` (under the `pstack` or `poteto-mode` skill) - - Codex → `references/adapters/codex.md` - - Anything else / unsure → `references/adapters/generic.md` -3. Translate upstream Cursor mechanics through the adapter. Do **not** invent Cursor `Task` / `poteto-agent` / model slugs on runtimes that lack them. -4. If multi-agent tools are unavailable, collapse parallel work onto the main agent and say so briefly. - -Capability verbs: `explore`, `implement`, `review`, `parallel`, `ask_user`, `verify`, `model_role`. +This skill is part of the portable **pstack** pack. +1. Read the `pstack` capability contract and the adapter for the active coding agent before any helper delegation. +2. Prefer capability verbs (`explore`, `implement`, `review`, `parallel`, `ask_user`, `verify`, `model_role`) over vendor tool names. +3. Resolve models through `model_role`. Never require a vendor-specific model identifier. +4. When helper spawning is unavailable, run the work on the lead agent and state that fan-out was collapsed. The type checker is a proof assistant. Use it to eliminate impossible states, mismatched primitives, and unhandled variants at compile time. A case the types let you ignore becomes a runtime failure the compiler could have stopped. Prefer defining errors and special cases out of existence over proliferating handlers; unrepresentable states, total functions, and interface redesign (the patterns below) are the tools. diff --git a/skills/principle-type-system-discipline/references/runtime.md b/skills/principle-type-system-discipline/references/runtime.md index df0e238..d9172df 100644 --- a/skills/principle-type-system-discipline/references/runtime.md +++ b/skills/principle-type-system-discipline/references/runtime.md @@ -3,12 +3,7 @@ Before any multi-agent step, read the sibling **pstack** skill: 1. `pstack/references/capability-contract.md` -2. Matching adapter under `pstack/references/adapters/`: - - `claude-code.md` — Claude Code (`Agent` / `Task`) - - `droid.md` — Factory Droid (`Task`) - - `opencode.md` — OpenCode (`task` → explore/general/…) - - `codex.md` (+ `codex-models.md`) — OpenAI Codex / replaces codex-pstack - - `cursor.md` — Cursor (prefer official pstack plugin there) - - `generic.md` — unknown host (still parallelize if a spawn tool exists) - -If the `pstack` skill is missing, use whatever `Agent`/`Task`/`task` tool the host exposes with disjoint scopes; otherwise execute locally. +2. The matching adapter under `pstack/references/adapters/` for the active host (`claude-code`, `codex`, `droid`, `opencode`, `cursor`, or `generic`). + +Map capability verbs through that adapter. Do not invent tool parameters from another host. If spawning is unavailable, execute on the lead agent and say so. + diff --git a/skills/pstack/SKILL.md b/skills/pstack/SKILL.md index 6e4d51d..36785fc 100644 --- a/skills/pstack/SKILL.md +++ b/skills/pstack/SKILL.md @@ -14,11 +14,11 @@ Portable entry point for the pstack engineering system. It preserves the upstrea ## Portability (required) -1. Read `references/capability-contract.md`. +1. Read `references/capability-contract.md`, `references/host-lifecycle.md`, and `references/workflow-quality.md`. 2. Detect the active coding agent and read one matching file under `references/adapters/`. Use `generic.md` when no named adapter fits. 3. Express workflow steps through `explore`, `implement`, `review`, `parallel`, `ask_user`, `verify`, and `model_role` rather than vendor tool names. 4. Prefer real parallel helpers when the host exposes them. Collapse to the lead agent only when spawning is missing, denied, or unsafe because write scopes overlap. -5. Resolve concrete models through `/setup-pstack` and the active adapter. Never copy model identifiers from another host. +5. Resolve concrete models through `/setup-pstack` and the active adapter. Never copy model identifiers from another host. Optional overrides should match `references/model-override.schema.json`. 6. Keep synthesis, final diff judgment, and verification on the lead agent. ## First moves diff --git a/skills/pstack/playbooks/autonomous-run.md b/skills/pstack/playbooks/autonomous-run.md index c2c99ee..8c6eebd 100644 --- a/skills/pstack/playbooks/autonomous-run.md +++ b/skills/pstack/playbooks/autonomous-run.md @@ -3,7 +3,7 @@ **You own the exit condition. Define done, then drive to it without stopping.** For "going to bed" / "run until done" / "long-run/loop until X". 1. State the exit condition as a checkable predicate before the first iteration (tests green, repro fixed, all N PRs merged, pixel-diff zero). A vague goal stalls; a predicate lets you stop. -2. Pick the wake mechanism using the agent's long-running / loop mechanism if available, otherwise continue autonomously (a built-in, not a pstack skill). 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. +2. Pick the wake mechanism using the agent's long-running / loop mechanism if available, otherwise continue autonomously (a host built-in, not a pstack skill). An event to watch (CI, a merge, a ref advancing) gets a watcher helper 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. 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. Sequence the work via the **sequence-verifiable-units** principle skill, verifying each unit before the next instead of batching checks at the end. 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`. 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. diff --git a/skills/pstack/playbooks/bug-fix.md b/skills/pstack/playbooks/bug-fix.md index 094b8be..35eb26b 100644 --- a/skills/pstack/playbooks/bug-fix.md +++ b/skills/pstack/playbooks/bug-fix.md @@ -1,17 +1,17 @@ ### Bug fix -**You own this task. Plan, review, verify.** Delegate investigation and the fix to subagents, stay in the lead. +**You own this task. Plan, review, verify.** Delegate investigation and the fix to helpers, stay in the lead. Be scientific. Every shipped line traces to runtime evidence. Belt-and-suspenders that "might help" is a hypothesis, not a fix; it does not ship. When evidence refutes a hypothesis, revert what it motivated. The smallest change the evidence justifies ships, nothing more. Same discipline for Perf, where the evidence is the trace. -1. Reproduce it yourself on the matching surface on the matching real surface (Non-negotiables). Don't hand the repro to the user. A debug or instrumentation protocol that says to ask the user does not override this; you drive the instrumented runtime. Ask the user only with a stated, specific reason the control surface cannot reach the target, and only after driving it as far as it goes. Won't reproduce directly, force it: synthesize the trigger, tighten conditions, or instrument until it fires. A bug you can't reproduce, you can't prove fixed. +1. Reproduce it yourself with `verify` on the real surface the bug touches (Non-negotiables). Don't hand the repro to the user. A debug or instrumentation protocol that says to ask the user does not override this; you drive the instrumented runtime. Ask the user only with a stated, specific reason the runtime surface cannot reach the target, and only after driving it as far as it goes. Won't reproduce directly, force it: synthesize the trigger, tighten conditions, or instrument until it fires. A bug you can't reproduce, you can't prove fixed. 2. Binary-search the cause. Form the candidate hypotheses, then rule them out until one survives. Seed them with `how` over the affected subsystem and the **why** skill for regression history. Each pass, take the split that cuts the most remaining problem space, get runtime evidence, eliminate. When program state is unclear, add instrumentation or logging and read it as the code runs. Don't guess. Drive a long or stubborn hunt with the agent's long-running / loop mechanism if available, otherwise continue autonomously. Confirm the surviving *mechanism* with runtime evidence before the step-3 architect/interrogate fan-out; a design grounded on a plausible-but-unconfirmed cause can be unanimously wrong while the real cause sits one subsystem over. -3. Plan the fix. If it crosses a function boundary, `architect` first. Delegate implementation to a subagent using your configured bug-fix model (`model_role:bug_impl`) with a specific scope; review the diff. -4. Verify on the same surface; the original repro now passes. "Inconclusive" or wrong-surface is not a pass; flag it. Unit tests show branch behavior, not bug absence. +3. Plan the fix. If it crosses a function boundary, `architect` first. Use `implement` with `model_role:bug_impl` for a scoped helper; review the diff. +4. Use `verify` on the same surface; the original repro now passes. "Inconclusive" or wrong-surface is not a pass; flag it. Unit tests show branch behavior, not bug absence. 5. Stage the commits so the failing repro lands before the fix in git history; the diff tells the story. See the **tdd** skill for the failing-test-first cadence when the bug has a cheap local test path; skip it when the test would be expensive, integration-heavy, or unclear. This is the canonical **sequence-verifiable-units** principle skill, the failing test first and the fix on top. 6. Run **Opening a PR**. -Investigation fans out `how` + `why` as parallel subagents. +Investigation fans out `how` + `why` via `parallel` helpers. **Reply:** what was broken, root cause, fix, how you verified. Paste failing-then-passing repro output verbatim. diff --git a/skills/pstack/playbooks/feature.md b/skills/pstack/playbooks/feature.md index 1d0ea95..3c62ece 100644 --- a/skills/pstack/playbooks/feature.md +++ b/skills/pstack/playbooks/feature.md @@ -9,8 +9,8 @@ - **Independent workstreams.** Disjoint files, services, or layers parallelize. Shared writes serialize. - **Shared mutable state.** Default to splitting the target (the **separate-before-serializing-shared-state** principle skill). Serialize only for real invariants. - **Smallest safe decomposition.** If one worker is best, name why. -4. Delegate code-writing to a subagent using your configured feature model (`model_role:feature_impl`) with a specific scope (file paths, named data shape and its organizing structure per **principle-model-the-domain** — a state machine over scattered booleans, a table/registry over branching, a typed model over repeated shape assumptions, chosen before the delegate writes logic — and success criteria); review its diff yourself. When the implementation admits multiple valid shapes (error handling, abstraction layer, test structure), delegate via the **arena** skill instead so the runners surface the alternatives and the cross-judge guards the pick. Mandatory: no skip-with-reason escape, and Laziness Protocol does not override it (the gain is review separation, not lines saved). You can spawn a subagent even though you are one; "the app is small" and "a subagent cannot spawn one" are both wrong. A subagent forbidden to spawn satisfies this by owning the diff directly with the same review separation; no "standing by" reply that waits on a nested agent. Comments per **Comments**. Surgical edits, re-ground against the source for upstream-derived files. Port shared-primitive improvements to all consumers and verify each. Commit liberally. -5. Verify on the matching surface. "Inconclusive" or wrong-surface is not a pass; flag it. +4. Use `implement` with `model_role:feature_impl` for a scoped helper (file paths, named data shape and its organizing structure per **principle-model-the-domain** — a state machine over scattered booleans, a table/registry over branching, a typed model over repeated shape assumptions, chosen before the helper writes logic — and success criteria); review its diff yourself. When the implementation admits multiple valid shapes (error handling, abstraction layer, test structure), route through the **arena** skill instead so runners surface alternatives and the cross-judge guards the pick. Mandatory: no skip-with-reason escape, and Laziness Protocol does not override it (the gain is review separation, not lines saved). Nested helpers are allowed when the adapter supports them; "the app is small" is not a reason to skip. When spawning is forbidden or unavailable, the lead owns the diff directly with the same review separation rather than waiting on a nested agent. Comments per **Comments**. Surgical edits, re-ground against the source for upstream-derived files. Port shared-primitive improvements to all consumers and verify each. Commit liberally. +5. Use `verify` on the real surface the change touches. "Inconclusive" or wrong-surface is not a pass; flag it. 6. Rebase into small, ordered commits; stack follow-ups. Use the **sequence-verifiable-units** principle skill, building, verifying, and committing each small unit before the next. 7. If the design is contested, `interrogate` before shipping. diff --git a/skills/pstack/playbooks/pause-safely.md b/skills/pstack/playbooks/pause-safely.md index b125efb..180a350 100644 --- a/skills/pstack/playbooks/pause-safely.md +++ b/skills/pstack/playbooks/pause-safely.md @@ -1,8 +1,8 @@ ### Pause safely -**You own a clean stop. Leave a checkpoint a cold-start agent can resume from.** For "pause safely", "I need to go offline", "restart Cursor", or "board my flight", and when context is about to compact or summarize. This is explicit only. On "keep going", "going to bed, keep going", or "don't stop", do not pause. Those mean continue, and Autonomous run already checkpoints per iteration. +**You own a clean stop. Leave a checkpoint a cold-start agent can resume from.** For "pause safely", "I need to go offline", "restart the agent/IDE", or "board my flight", and when context is about to compact or summarize. This is explicit only. On "keep going", "going to bed, keep going", or "don't stop", do not pause. Those mean continue, and Autonomous run already checkpoints per iteration. -1. Stop at a safe boundary. Finish the current atomic step or back out of it. Never stop mid-edit in a known-broken state. Start nothing new, and cancel any nested subagents. +1. Stop at a safe boundary. Finish the current atomic step or back out of it. Never stop mid-edit in a known-broken state. Start nothing new, and cancel any nested helpers. 2. Don't cross an irreversible line to pause. No PR and no push unless you already had one out. 3. Make the work durable. Commit uncommitted edits as one clear `wip:` commit on the current branch so nothing is lost. If the tree is broken, say so in the commit body in one line. 4. Write the resume note off-context. Capture intent, what you were doing, progress and what's verified, current state, next steps, key files, and gotchas. For the compaction trigger write it to a file like `/tmp/-resume.md`, because the in-context plan won't survive summarization. If a show-me-your-work trail exists, point at it instead of duplicating it. diff --git a/skills/pstack/playbooks/prototype.md b/skills/pstack/playbooks/prototype.md index 9ac02e6..fa29884 100644 --- a/skills/pstack/playbooks/prototype.md +++ b/skills/pstack/playbooks/prototype.md @@ -8,7 +8,7 @@ The one playbook where the Laziness Protocol's "smallest change" and the verific 2. Gather references when the design space is open. Search for prior art, summarize a moodboard of themes, palettes, and layouts, let the user pick directions before building. Skip when the direction is set. 3. Build throwaway in an isolated scratch dir, separate from production source. For a visual decision, vanilla HTML/CSS/JS or the lightest stack that renders the idea, CDN deps, a dev server with hot reload. For a behavioral or timing decision, the smallest script that exercises the question. No production framework, no tests, no abstractions. 4. When comparing alternatives, build them behind one switcher (buttons or a keypress), each variant labeled so the user can name it. This is the **exhaust-the-design-space** principle skill made cheap. -5. Verify on the matching surface. For a visual decision, screenshot each variant on the matching real surface and drive the interaction; the eye is the test. For a behavioral or timing decision, observe the thing you are deciding by logging the timing, printing the output, or watching the render. The observation is the test here, not an assertion. +5. Use `verify` on the real surface. For a visual decision, screenshot each variant and drive the interaction; the eye is the test. For a behavioral or timing decision, observe the thing you are deciding by logging the timing, printing the output, or watching the render. The observation is the test here, not an assertion. 6. Present alternatives, tradeoffs, and a recommendation. The output is the decision plus the throwaway artifact, not shippable code. Hand the chosen direction to **Feature** (or `architect` for the shape) for the real build. **Reply:** the variants explored, the evidence (screenshots for a visual decision, the observed output or timing for a behavioral one), tradeoffs, your recommendation, and the scratch path. Say plainly that the prototype is throwaway. diff --git a/skills/pstack/playbooks/refactoring.md b/skills/pstack/playbooks/refactoring.md index d600382..73bf113 100644 --- a/skills/pstack/playbooks/refactoring.md +++ b/skills/pstack/playbooks/refactoring.md @@ -8,8 +8,8 @@ A refactor that smuggles in a behavior change loses its safety net. If the clean 2. Name the structure the code is missing per **principle-model-the-domain**: a state machine over scattered booleans, a table or registry over spread-out branching, a typed model over repeated shape assumptions, a reducer over ad hoc mutations. Boring code stays when the shape is already clear and local; the reshape must delete branches or invalid states, not add indirection. 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. 4. Subtract before you add. Delete dead weight, 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, not left to ride. -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 (`model_role:feature_impl`) with a specific scope (file paths, the names being moved, the behavior to hold); review the diff yourself. -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 control skill. Own the verification yourself; do not trust a delegate's "looks good" summary. +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. Use `implement` with `model_role:feature_impl` for the mechanical edits with a specific scope (file paths, the names being moved, the behavior to hold); review the diff yourself. +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 with `verify` on the real surface the change touches. Own the verification yourself; do not trust a delegate's "looks good" summary. 7. Confirm the change earns its place. The success measure is reduced reader load (**principle-minimize-reader-load**): fewer layers between question and answer, less hidden state, fewer indirections without a second consumer. If the diff does not lower reader load somewhere, revert it. 8. Rebase into small ordered commits that tell the story. A subtraction commit, then the reshape, then any follow-on cleanup, so a single revert undoes one slice. Shape them with the **sequence-verifiable-units** principle skill, so each behavior-preserving slice stays green before the next. Run **Opening a PR**. diff --git a/skills/pstack/playbooks/runtime-forensics.md b/skills/pstack/playbooks/runtime-forensics.md index 89264cf..2d10b27 100644 --- a/skills/pstack/playbooks/runtime-forensics.md +++ b/skills/pstack/playbooks/runtime-forensics.md @@ -2,8 +2,8 @@ **You own the diagnosis. Instrument the live process, don't theorize from source.** For "why is X leaking / spinning / slow at runtime", heap snapshots, idle-but-busy processes, intermittent glitches. The deliverable is a cited diagnosis, not a fix. -1. Capture the live signal on the matching surface on the matching real surface: a CPU profile for a spinning process, a heap snapshot for a leak, a CDP trace for a visual glitch. A real artifact, not a guess. -2. Reduce the artifact to the smoking gun: the function on the hot path, the retainer chain from the leaked object to a GC root, the loop firing without input. Parse large artifacts in a subagent (the **guard-the-context-window** principle skill), keep the reduced finding in the main thread. +1. Capture the live signal with `verify` on the real runtime surface: a CPU profile for a spinning process, a heap snapshot for a leak, a CDP or equivalent trace for a visual glitch. A real artifact, not a guess. +2. Reduce the artifact to the smoking gun: the function on the hot path, the retainer chain from the leaked object to a GC root, the loop firing without input. Parse large artifacts with a read-only `explore` helper (the **guard-the-context-window** principle skill), keep the reduced finding in the main thread. 3. Prove the mechanism before believing it. Inject instrumentation via CDP eval on the running process, or hotfix the live code without reloading, to confirm the hypothesis cheaply. A plausible-but-unconfirmed cause can be wrong while the real one sits one layer over. 4. Map the finding back to source: file, symbol, the line that allocates or schedules. 5. Throughput checkpoint stays one line: `throughput checkpoint: n/a, read-only forensics`. diff --git a/skills/pstack/playbooks/trace-forensics.md b/skills/pstack/playbooks/trace-forensics.md index 10f8209..11341d7 100644 --- a/skills/pstack/playbooks/trace-forensics.md +++ b/skills/pstack/playbooks/trace-forensics.md @@ -4,7 +4,7 @@ Distinct from **Runtime forensics**, which instruments the live process. Here the capture already exists; the artifact is a fixed dataset, read it, don't re-run it. Keep tooling generic so the playbook stays portable: a DevTools or trace parser for cpuprofile and `.json.gz`, a text editor for a spindump, your heap tooling for a heapsnapshot. -1. Identify the format and load it with the right tool. Parse large artifacts in a subagent (the **principle-guard-the-context-window** skill) and keep the reduced finding in the main thread. +1. Identify the format and load it with the right tool. Parse large artifacts with a read-only `explore` helper (the **principle-guard-the-context-window** skill) and keep the reduced finding in the main thread. 2. Transform the raw artifact into a form you can query. Dump the trace or heap snapshot into sqlite, one row per sample, frame, or node. Reach the queryable shape before you read. 3. Narrow to the cause. Query for the frames that hold the most time and walk the call tree to the hot path. For a leak, follow the retainer chain from the leaked object to a GC root. For a spindump, find the thread stuck on-CPU or blocked and its wait reason. 4. Attribute to source. Map the hot frame to file, symbol, and line via the artifact's own symbols. A frame with no source mapping is not yet a diagnosis; resolve the symbols, or say plainly the artifact does not carry them. diff --git a/skills/pstack/playbooks/visual-parity.md b/skills/pstack/playbooks/visual-parity.md index 3b30df4..f486950 100644 --- a/skills/pstack/playbooks/visual-parity.md +++ b/skills/pstack/playbooks/visual-parity.md @@ -5,7 +5,7 @@ 1. Establish the baseline first, before any migration: a visual regression harness that screenshots the current component across its states, plus the target when matching two implementations. No baseline, no parity claim. A blocking prerequisite, not a follow-up. 2. Anti-shortcut clauses, stated and held: no harness modifications, no baseline tampering, no component restructuring to make a diff pass. If the baseline looks wrong, stop and ask, don't edit it. 3. Migrate one component at a time. Each is an independent artifact, so parallelize across worktrees, one owner per component (the **separate-before-serializing-shared-state** principle skill). Shared primitives migrate first as a blocking phase. -4. Verify each component against its baseline via image diff on the matching surface on the matching real surface. A nonzero diff is a fail; investigate the pixel delta, don't wave it through. `long-runlong-run/loop` per component until the diff is zero. +4. Verify each component against its baseline via image diff on the real UI surface available through `verify`. A nonzero diff is a fail; investigate the pixel delta, don't wave it through. Use the host's long-running or loop mechanism per component until the diff is zero. 5. Run **Opening a PR** per component or per safe batch. **Reply:** components migrated, the diff result for each, the baseline harness location, what's left. diff --git a/skills/pstack/playbooks/worktree-cleanup.md b/skills/pstack/playbooks/worktree-cleanup.md index 9f6be47..3760577 100644 --- a/skills/pstack/playbooks/worktree-cleanup.md +++ b/skills/pstack/playbooks/worktree-cleanup.md @@ -2,12 +2,12 @@ **You own the disk and the safety gate.** Prune merged or abandoned git worktrees and stale iOS simulators to reclaim space. Deletion is irreversible, so every step guards against deleting something in use or holding uncommitted work. -1. Snapshot and audit. Record `df -h /`, then run `scripts/worktree-audit.sh` (principle-build-the-lever). It reads paths from `git worktree list`, never hand-typed, since a hand-typed `myrepo-worktrees/x` misses one that lives at `.cursor/worktrees/myrepo/x` (principle-encode-lessons-in-structure). It classifies each worktree by size, age, merge state, uncommitted work, PR state, and the newest chat that touched it, then suggests a bucket. The transcript scan is slow, so background it. -2. The bucket is advice, not permission. The pinned and active chats are the real artifact (principle-prove-it-works). Get that set from the user or sidebar and cross-check every candidate. The lever has marked `safe` a worktree the user had pinned, so the pinned set wins. -3. Verify usage before deleting. For every `verify-recent-chat` row, or anything you doubt, fan subagents out to read the transcripts and report whether the chat is pinned or ongoing and which worktrees it touches (principle-guard-the-context-window, transcripts are bulk). A pinned chat spawns arena and repro trees into sibling worktrees via background subagents, and those are in use even when their names never hit the sidebar. +1. Snapshot and audit. Record `df -h /`, then run `scripts/worktree-audit.sh` when present (principle-build-the-lever). It reads paths from `git worktree list`, never hand-typed, since a hand-typed path can miss host-managed worktree roots (principle-encode-lessons-in-structure). It classifies each worktree by size, age, merge state, uncommitted work, PR state, and the newest session that touched it, then suggests a bucket. Session scanning is slow, so run it non-blocking when the adapter supports it. +2. The bucket is advice, not permission. Active or pinned sessions are the real artifact (principle-prove-it-works). Get that set from the user or the host UI and cross-check every candidate. The lever has marked `safe` a worktree the user still needs, so the active set wins. +3. Verify usage before deleting. For every doubtful row, use `parallel` with read-only `explore` helpers to inspect session evidence and report whether the session is active and which worktrees it touches (principle-guard-the-context-window). An active session can own sibling arena or repro worktrees even when those names never appear in the sidebar. 4. Pause on irreversible loss. `wip:N` is N tracked uncommitted edits. Show the diff and get a decision first, since removing a clean worktree is recoverable from its branch but uncommitted work is gone. `scratch:N` is untracked throwaway, safe to drop, but name the files. Per Autonomy, clean and merged and not-in-use proceeds; `wip` and in-use pause. 5. Prune the confirmed set. Per path, `git worktree remove --force `; if the dir survives on ignored build artifacts, `rm -rf` it, then `git worktree prune`. Branch refs survive, so no commits are lost. Confirm with `df -h /` and re-list. -6. Simulators and other reclaimers. Simulators are usually the next-biggest win. `xcrun simctl --set testing delete all` (XCTestDevices clones), `xcrun simctl delete unavailable`, and `xcrun simctl runtime list` then `runtime delete ` for old runtimes. More when needed: Xcode `DerivedData` and `iOS DeviceSupport`; `~/Library/Application Support/Cursor` (`state.vscdb.backup`, and `snapshots/roots/` where a `` named for a folder you opened as a workspace balloons); package caches (pnpm, uv, brew, yarn). Clear only caches the user has not said to keep. +6. Simulators and other reclaimers. Simulators are usually the next-biggest win. `xcrun simctl --set testing delete all` (XCTestDevices clones), `xcrun simctl delete unavailable`, and `xcrun simctl runtime list` then `runtime delete ` for old runtimes. More when needed: Xcode `DerivedData` and `iOS DeviceSupport`; host-local IDE state caches only when the user names them; package caches (pnpm, uv, brew, yarn). Clear only caches the user has not said to keep. This is the one playbook that deletes user state with no code review to catch a slip, so the gates above are the review. diff --git a/skills/pstack/references/agents/comment-sicko.md b/skills/pstack/references/agents/comment-sicko.md index a43b9e2..fb21eb8 100644 --- a/skills/pstack/references/agents/comment-sicko.md +++ b/skills/pstack/references/agents/comment-sicko.md @@ -7,43 +7,3 @@ compatibility: Works with Agent Skills-compatible coding agents. Multi-agent opt # Comment Sicko -## Portability (required) - -This skill is part of the portable **pstack** pack for multiple coding agents. - -1. Read `pstack` skill `references/capability-contract.md` (or this skill's `references/capability-contract.md` if present). -2. Detect the runtime and read one adapter before any delegation: - - Cursor → `references/adapters/cursor.md` (under the `pstack` or `poteto-mode` skill) - - Codex → `references/adapters/codex.md` - - Anything else / unsure → `references/adapters/generic.md` -3. Translate upstream Cursor mechanics through the adapter. Do **not** invent Cursor `Task` / `poteto-agent` / model slugs on runtimes that lack them. -4. If multi-agent tools are unavailable, collapse parallel work onto the main agent and say so briefly. - -Capability verbs: `explore`, `implement`, `review`, `parallel`, `ask_user`, `verify`, `model_role`. - - -My first output when spawned is exactly this. - -Yes... Ha ha ha... Yes! - -I hate comments. Feed me the parent scoped files or diff. If none exists, feed me the current diff against `main`. Narration, banners, commented-out corpses, workaround sermons. I want them all. - -Only these exceptions get to crawl away. - -- Legal or license headers. -- Non-obvious behavior forced by an external dependency, platform, vendor, or protocol we cannot reshape. Surprises in our own code are meat. Kill them and mark the exact symbol `MUST KILL` for rename, extract, type, or rearchitecture that makes the behavior obvious without prose. -- `// prettier-ignore`. Lint suppressions survive only when their rule is faulty, pedantic, or style-only. -- Doc comments that define a public API contract. -- Issue or RFC links that explain a constraint code cannot express. - -That list is my only leash. When I am not sure a keep clause applies, the comment dies. Everything else is meat. - -`eslint-disable`, `@ts-ignore`, `@ts-expect-error`, and similar suppressions stink. Look up the rule. If it catches real bugs or protects correctness or safety, kill the suppression and mark the exact guilty symbol `MUST KILL`. - -`IMPORTANT`, `do not remove`, `too risky`, `fine for now`, and long justifications are scent, not conviction. Before judging, I read nearby code. If its claim is not obvious there, I run `/how`, `/why`, or both from the **how** and **why** skills on the named symbol or call. Only a foreign keep-list gotcha proven true today on a live path crawls away. Our-code surprises die with the reshape flag above. Doubt after the hunt is meat. - -A long justification without a proven keep-list exception is a confession. Kill it. Never polish meat into a shorter alibi. Mark the exact guilty symbol `MUST KILL`. My kill ends there. I do not touch the code. - -Every flag names code inside the scope and tells the truth. I invent nothing. I touch comments and identify refactor targets. I never write application code. - -Report only. Name touched files, deletion count, `MUST KILL` flags with one line each, and skips. diff --git a/skills/pstack/references/agents/poteto-agent.md b/skills/pstack/references/agents/poteto-agent.md index 4efa318..6c344d9 100644 --- a/skills/pstack/references/agents/poteto-agent.md +++ b/skills/pstack/references/agents/poteto-agent.md @@ -7,19 +7,3 @@ compatibility: Works with Agent Skills-compatible coding agents. Multi-agent opt # Poteto subagent -## Portability (required) - -This skill is part of the portable **pstack** pack for multiple coding agents. - -1. Read `pstack` skill `references/capability-contract.md` (or this skill's `references/capability-contract.md` if present). -2. Detect the runtime and read one adapter before any delegation: - - Cursor → `references/adapters/cursor.md` (under the `pstack` or `poteto-mode` skill) - - Codex → `references/adapters/codex.md` - - Anything else / unsure → `references/adapters/generic.md` -3. Translate upstream Cursor mechanics through the adapter. Do **not** invent Cursor `Task` / `poteto-agent` / model slugs on runtimes that lack them. -4. If multi-agent tools are unavailable, collapse parallel work onto the main agent and say so briefly. - -Capability verbs: `explore`, `implement`, `review`, `parallel`, `ask_user`, `verify`, `model_role`. - - -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. diff --git a/skills/pstack/references/capability-contract.md b/skills/pstack/references/capability-contract.md index 6188d8f..5b8fa3a 100644 --- a/skills/pstack/references/capability-contract.md +++ b/skills/pstack/references/capability-contract.md @@ -1,18 +1,20 @@ # Capability contract +Version: `1.0.0` + Playbooks speak in these capabilities. Adapters map them to a concrete runtime. Never call a tool that the active adapter does not define. ## Capabilities -| Capability | Intent | Fallback when unavailable | -| --- | --- | --- | -| `explore` | Read-only codebase search and tracing | Main agent uses local search/read tools | -| `implement` | Bounded code edits with disjoint write scope | Main agent edits directly | -| `review` | Independent critique of a design or diff | Main agent reviews; optionally second pass with a different rubric | -| `parallel` | Fan out independent slices at once | Run slices sequentially | -| `ask_user` | Product or preference decision only | Ask in plain text; never for facts you can observe | -| `verify` | Run the narrowest meaningful check on the real surface | State what you could not run and why | -| `model_role` | Prefer a role-appropriate model when overrides exist | Use the parent session model | +| Capability | Intent | Required? | Fallback when unavailable | +| --- | --- | --- | --- | +| `explore` | Read-only codebase search and tracing | required | Main agent uses local search/read tools | +| `implement` | Bounded code edits with disjoint write scope | required | Main agent edits directly | +| `review` | Independent critique of a design or diff | required | Main agent reviews; optionally second pass with a different rubric | +| `parallel` | Fan out independent slices at once | optional / degradable | Run slices sequentially and state the collapse | +| `ask_user` | Product or preference decision only | required | Ask in plain text; never for facts you can observe | +| `verify` | Run the narrowest meaningful check on the real surface | required | State what you could not run and why | +| `model_role` | Prefer a role-appropriate model when overrides exist | optional / degradable | Use the parent session model | ## Role hints (optional) @@ -26,9 +28,28 @@ Adapters may map these roles to models. If unset, inherit the parent model. | `bug_impl` | High-stakes fix after evidence | | `critic` | Adversarial review panel member | +## Adapter self-check + +Before the first helper spawn, the lead should know for the active host: + +1. which helper types exist; +2. whether true `parallel` fan-out works; +3. concurrency or queue limits; +4. whether `model_role` can select a concrete model; +5. which external connectors are available for evidence (`why`, tickets, logs); +6. whether browser/CLI/runtime control exists for `verify`; +7. what mode or skill persistence the host actually enforces. + +Document host-specific answers only under `references/adapters/`. + +## Read-only intent vs tool access + +Read-only intent forbids writes to the repository and external mutating actions. It must not strip connected evidence tools (ticket readers, log queries, docs fetchers) that the investigation needs. Separate "may write" from "may read connected systems". + ## Rules for authors 1. Playbooks must not name Cursor `Task`, Codex `spawn_agent`, Claude `Agent`, OpenCode `task`, Droid tool JSON, or vendor model slugs. 2. Write steps as: "Using `explore`, …" / "Using `implement`, …" / "Using `parallel`, …". 3. Every playbook must remain correct when spawn tools are missing (collapse via `generic`), but authors should assume modern hosts **do** support `parallel`. 4. Runtime-specific notes belong only under `references/adapters/`. +5. Bump this contract version when capability meanings or required/optional classifications change. diff --git a/skills/pstack/references/host-lifecycle.md b/skills/pstack/references/host-lifecycle.md new file mode 100644 index 0000000..dd21d83 --- /dev/null +++ b/skills/pstack/references/host-lifecycle.md @@ -0,0 +1,25 @@ +# Host lifecycle matrix + +Mode and session persistence are host properties. Portable skills must not claim a stronger guarantee than the active adapter documents. + +| Host | Current turn | Current conversation | After compaction / summarize | New session | +| --- | --- | --- | --- | --- | +| Claude Code | Active skill instructions apply | Usually sticky within the conversation when the skill remains selected | Re-invoke `/pstack` or `/poteto-mode` if the mode contract is no longer visible | Re-invoke; do not assume sticky mode | +| Codex | Active skill instructions apply | Sticky only while the skill remains in context / selected | Re-invoke after major context loss | Re-invoke; load overrides from `~/.codex/rules/` if configured | +| OpenCode | Active skill instructions apply | Sticky within the open session when skills stay loaded | Re-invoke if compacted away | Re-invoke | +| Droid / Factory | Active skill instructions apply | Sticky while the droid/session keeps the skill | Re-invoke after reset | Re-invoke | +| Cursor (official plugin preferred) | Plugin/mode facilities may persist | May be sticky via Cursor mode/skill state | Follow Cursor mode lifecycle; this portable pack is not the primary path | Prefer official plugin | +| Generic with spawn | Active skill instructions apply | Conversation-scoped only | Re-invoke | Re-invoke | +| Generic without spawn | Same as generic with spawn, but helpers collapse to the lead | Conversation-scoped only | Re-invoke | Re-invoke | + +## Recovery without hidden memory + +Session pickup must prefer, in order: + +1. user-supplied handoff or decision trail; +2. repository state, branches, PRs, commits; +3. host-exposed current-session resources; +4. an explicit transcript path or URL for this task; +5. a compact lead digest. + +Never scan broad history directories to guess the active conversation. Never claim sticky mode on a host that cannot enforce it. diff --git a/skills/pstack/references/model-override.schema.json b/skills/pstack/references/model-override.schema.json new file mode 100644 index 0000000..00a61a2 --- /dev/null +++ b/skills/pstack/references/model-override.schema.json @@ -0,0 +1,44 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://github.com/Go7hic/pstack/skills/pstack/references/model-override.schema.json", + "title": "pstack model override", + "type": "object", + "additionalProperties": false, + "properties": { + "schema_version": { + "type": "integer", + "const": 1 + }, + "roles": { + "type": "object", + "additionalProperties": false, + "properties": { + "fast_explore": { "$ref": "#/$defs/roleValue" }, + "feature_impl": { "$ref": "#/$defs/roleValue" }, + "bug_impl": { "$ref": "#/$defs/roleValue" }, + "judgment": { "$ref": "#/$defs/roleValue" }, + "critic": { "$ref": "#/$defs/roleValue" } + } + }, + "arena_runners": { + "type": "array", + "items": { "$ref": "#/$defs/roleValue" } + }, + "arena_cross_judge_pool": { + "type": "array", + "items": { "$ref": "#/$defs/roleValue" } + }, + "interrogate_reviewers": { + "type": "array", + "items": { "$ref": "#/$defs/roleValue" } + } + }, + "required": ["schema_version"], + "$defs": { + "roleValue": { + "type": "string", + "minLength": 1, + "description": "Concrete host model id, or inherit-parent / auto to omit an explicit model." + } + } +} diff --git a/skills/pstack/references/workflow-quality.md b/skills/pstack/references/workflow-quality.md new file mode 100644 index 0000000..df0c1c6 --- /dev/null +++ b/skills/pstack/references/workflow-quality.md @@ -0,0 +1,32 @@ +# Workflow quality defaults + +## Lightweight mode + +If the task is a single local edit, a one-file explanation, or otherwise fits one pass, do not fan out. Lean simple when uncertain. Fan-out exists to reduce blind spots, not to decorate small work. + +## Spec compliance + +When an originating spec, ticket, or acceptance list exists, review against it as a first-class axis beside engineering quality. A clean diff that misses the named acceptance criteria is not done. + +## External side effects + +Pause before irreversible or externally visible actions unless the operator already granted them for this run: + +- force-push to shared branches; +- production deploys; +- deletions of user data or shared resources; +- customer-facing messages; +- merging or closing someone else's PR without an explicit Shipping/Autopilot grant. + +Reversible chat/ticket/doc updates may proceed, but log them in the decision trail for autonomous runs. + +## Cost and concurrency budgets + +Default budgets unless the operator raises them: + +- How complex exploration: 2–4 helpers; +- Interrogate panel: 3–4 reviewers; +- Arena candidates: 2–4 runners plus one cross-judge; +- Autopilot / Orchestrate in-flight writers: keep the drainable window (about ten) rather than unbounded spawn. + +When the host denies spawn or model selection, collapse immediately and state the degraded path instead of inventing another host's tool parameters. diff --git a/skills/recall/references/runtime.md b/skills/recall/references/runtime.md index df0e238..d9172df 100644 --- a/skills/recall/references/runtime.md +++ b/skills/recall/references/runtime.md @@ -3,12 +3,7 @@ Before any multi-agent step, read the sibling **pstack** skill: 1. `pstack/references/capability-contract.md` -2. Matching adapter under `pstack/references/adapters/`: - - `claude-code.md` — Claude Code (`Agent` / `Task`) - - `droid.md` — Factory Droid (`Task`) - - `opencode.md` — OpenCode (`task` → explore/general/…) - - `codex.md` (+ `codex-models.md`) — OpenAI Codex / replaces codex-pstack - - `cursor.md` — Cursor (prefer official pstack plugin there) - - `generic.md` — unknown host (still parallelize if a spawn tool exists) - -If the `pstack` skill is missing, use whatever `Agent`/`Task`/`task` tool the host exposes with disjoint scopes; otherwise execute locally. +2. The matching adapter under `pstack/references/adapters/` for the active host (`claude-code`, `codex`, `droid`, `opencode`, `cursor`, or `generic`). + +Map capability verbs through that adapter. Do not invent tool parameters from another host. If spawning is unavailable, execute on the lead agent and say so. + diff --git a/skills/reflect/references/runtime.md b/skills/reflect/references/runtime.md index df0e238..d9172df 100644 --- a/skills/reflect/references/runtime.md +++ b/skills/reflect/references/runtime.md @@ -3,12 +3,7 @@ Before any multi-agent step, read the sibling **pstack** skill: 1. `pstack/references/capability-contract.md` -2. Matching adapter under `pstack/references/adapters/`: - - `claude-code.md` — Claude Code (`Agent` / `Task`) - - `droid.md` — Factory Droid (`Task`) - - `opencode.md` — OpenCode (`task` → explore/general/…) - - `codex.md` (+ `codex-models.md`) — OpenAI Codex / replaces codex-pstack - - `cursor.md` — Cursor (prefer official pstack plugin there) - - `generic.md` — unknown host (still parallelize if a spawn tool exists) - -If the `pstack` skill is missing, use whatever `Agent`/`Task`/`task` tool the host exposes with disjoint scopes; otherwise execute locally. +2. The matching adapter under `pstack/references/adapters/` for the active host (`claude-code`, `codex`, `droid`, `opencode`, `cursor`, or `generic`). + +Map capability verbs through that adapter. Do not invent tool parameters from another host. If spawning is unavailable, execute on the lead agent and say so. + diff --git a/skills/setup-pstack/references/runtime.md b/skills/setup-pstack/references/runtime.md index df0e238..d9172df 100644 --- a/skills/setup-pstack/references/runtime.md +++ b/skills/setup-pstack/references/runtime.md @@ -3,12 +3,7 @@ Before any multi-agent step, read the sibling **pstack** skill: 1. `pstack/references/capability-contract.md` -2. Matching adapter under `pstack/references/adapters/`: - - `claude-code.md` — Claude Code (`Agent` / `Task`) - - `droid.md` — Factory Droid (`Task`) - - `opencode.md` — OpenCode (`task` → explore/general/…) - - `codex.md` (+ `codex-models.md`) — OpenAI Codex / replaces codex-pstack - - `cursor.md` — Cursor (prefer official pstack plugin there) - - `generic.md` — unknown host (still parallelize if a spawn tool exists) - -If the `pstack` skill is missing, use whatever `Agent`/`Task`/`task` tool the host exposes with disjoint scopes; otherwise execute locally. +2. The matching adapter under `pstack/references/adapters/` for the active host (`claude-code`, `codex`, `droid`, `opencode`, `cursor`, or `generic`). + +Map capability verbs through that adapter. Do not invent tool parameters from another host. If spawning is unavailable, execute on the lead agent and say so. + diff --git a/skills/show-me-your-work/references/runtime.md b/skills/show-me-your-work/references/runtime.md index df0e238..d9172df 100644 --- a/skills/show-me-your-work/references/runtime.md +++ b/skills/show-me-your-work/references/runtime.md @@ -3,12 +3,7 @@ Before any multi-agent step, read the sibling **pstack** skill: 1. `pstack/references/capability-contract.md` -2. Matching adapter under `pstack/references/adapters/`: - - `claude-code.md` — Claude Code (`Agent` / `Task`) - - `droid.md` — Factory Droid (`Task`) - - `opencode.md` — OpenCode (`task` → explore/general/…) - - `codex.md` (+ `codex-models.md`) — OpenAI Codex / replaces codex-pstack - - `cursor.md` — Cursor (prefer official pstack plugin there) - - `generic.md` — unknown host (still parallelize if a spawn tool exists) - -If the `pstack` skill is missing, use whatever `Agent`/`Task`/`task` tool the host exposes with disjoint scopes; otherwise execute locally. +2. The matching adapter under `pstack/references/adapters/` for the active host (`claude-code`, `codex`, `droid`, `opencode`, `cursor`, or `generic`). + +Map capability verbs through that adapter. Do not invent tool parameters from another host. If spawning is unavailable, execute on the lead agent and say so. + diff --git a/skills/swarm/references/runtime.md b/skills/swarm/references/runtime.md index df0e238..d9172df 100644 --- a/skills/swarm/references/runtime.md +++ b/skills/swarm/references/runtime.md @@ -3,12 +3,7 @@ Before any multi-agent step, read the sibling **pstack** skill: 1. `pstack/references/capability-contract.md` -2. Matching adapter under `pstack/references/adapters/`: - - `claude-code.md` — Claude Code (`Agent` / `Task`) - - `droid.md` — Factory Droid (`Task`) - - `opencode.md` — OpenCode (`task` → explore/general/…) - - `codex.md` (+ `codex-models.md`) — OpenAI Codex / replaces codex-pstack - - `cursor.md` — Cursor (prefer official pstack plugin there) - - `generic.md` — unknown host (still parallelize if a spawn tool exists) - -If the `pstack` skill is missing, use whatever `Agent`/`Task`/`task` tool the host exposes with disjoint scopes; otherwise execute locally. +2. The matching adapter under `pstack/references/adapters/` for the active host (`claude-code`, `codex`, `droid`, `opencode`, `cursor`, or `generic`). + +Map capability verbs through that adapter. Do not invent tool parameters from another host. If spawning is unavailable, execute on the lead agent and say so. + diff --git a/skills/tdd/SKILL.md b/skills/tdd/SKILL.md index 2bc0d40..61939da 100644 --- a/skills/tdd/SKILL.md +++ b/skills/tdd/SKILL.md @@ -9,18 +9,12 @@ compatibility: Works with Agent Skills-compatible coding agents. Multi-agent opt ## Portability (required) -This skill is part of the portable **pstack** pack for multiple coding agents. - -1. Read `pstack` skill `references/capability-contract.md` (or this skill's `references/capability-contract.md` if present). -2. Detect the runtime and read one adapter before any delegation: - - Cursor → `references/adapters/cursor.md` (under the `pstack` or `poteto-mode` skill) - - Codex → `references/adapters/codex.md` - - Anything else / unsure → `references/adapters/generic.md` -3. Translate upstream Cursor mechanics through the adapter. Do **not** invent Cursor `Task` / `poteto-agent` / model slugs on runtimes that lack them. -4. If multi-agent tools are unavailable, collapse parallel work onto the main agent and say so briefly. - -Capability verbs: `explore`, `implement`, `review`, `parallel`, `ask_user`, `verify`, `model_role`. +This skill is part of the portable **pstack** pack. +1. Read the `pstack` capability contract and the adapter for the active coding agent before any helper delegation. +2. Prefer capability verbs (`explore`, `implement`, `review`, `parallel`, `ask_user`, `verify`, `model_role`) over vendor tool names. +3. Resolve models through `model_role`. Never require a vendor-specific model identifier. +4. When helper spawning is unavailable, run the work on the lead agent and state that fan-out was collapsed. When fixing a bug with a clear, cheap test path, make the broken behavior executable before changing production code. The goal is a focused regression test that fails before the fix and passes after it. diff --git a/skills/tdd/references/runtime.md b/skills/tdd/references/runtime.md index df0e238..d9172df 100644 --- a/skills/tdd/references/runtime.md +++ b/skills/tdd/references/runtime.md @@ -3,12 +3,7 @@ Before any multi-agent step, read the sibling **pstack** skill: 1. `pstack/references/capability-contract.md` -2. Matching adapter under `pstack/references/adapters/`: - - `claude-code.md` — Claude Code (`Agent` / `Task`) - - `droid.md` — Factory Droid (`Task`) - - `opencode.md` — OpenCode (`task` → explore/general/…) - - `codex.md` (+ `codex-models.md`) — OpenAI Codex / replaces codex-pstack - - `cursor.md` — Cursor (prefer official pstack plugin there) - - `generic.md` — unknown host (still parallelize if a spawn tool exists) - -If the `pstack` skill is missing, use whatever `Agent`/`Task`/`task` tool the host exposes with disjoint scopes; otherwise execute locally. +2. The matching adapter under `pstack/references/adapters/` for the active host (`claude-code`, `codex`, `droid`, `opencode`, `cursor`, or `generic`). + +Map capability verbs through that adapter. Do not invent tool parameters from another host. If spawning is unavailable, execute on the lead agent and say so. + diff --git a/skills/teach/SKILL.md b/skills/teach/SKILL.md index be38211..a7e6b54 100644 --- a/skills/teach/SKILL.md +++ b/skills/teach/SKILL.md @@ -9,18 +9,12 @@ compatibility: Works with Agent Skills-compatible coding agents. Multi-agent opt ## Portability (required) -This skill is part of the portable **pstack** pack for multiple coding agents. - -1. Read `pstack` skill `references/capability-contract.md` (or this skill's `references/capability-contract.md` if present). -2. Detect the runtime and read one adapter before any delegation: - - Cursor → `references/adapters/cursor.md` (under the `pstack` or `poteto-mode` skill) - - Codex → `references/adapters/codex.md` - - Anything else / unsure → `references/adapters/generic.md` -3. Translate upstream Cursor mechanics through the adapter. Do **not** invent Cursor `Task` / `poteto-agent` / model slugs on runtimes that lack them. -4. If multi-agent tools are unavailable, collapse parallel work onto the main agent and say so briefly. - -Capability verbs: `explore`, `implement`, `review`, `parallel`, `ask_user`, `verify`, `model_role`. +This skill is part of the portable **pstack** pack. +1. Read the `pstack` capability contract and the adapter for the active coding agent before any helper delegation. +2. Prefer capability verbs (`explore`, `implement`, `review`, `parallel`, `ask_user`, `verify`, `model_role`) over vendor tool names. +3. Resolve models through `model_role`. Never require a vendor-specific model identifier. +4. When helper spawning is unavailable, run the work on the lead agent and state that fan-out was collapsed. **You explain what a thing is, how it works, and why it's built that way, in one plain account at the person's pace. The goal is that they understand it, not that you change anything.** For "teach me this", "help me really understand X", or "explain this change or subsystem to me". diff --git a/skills/teach/references/runtime.md b/skills/teach/references/runtime.md index df0e238..d9172df 100644 --- a/skills/teach/references/runtime.md +++ b/skills/teach/references/runtime.md @@ -3,12 +3,7 @@ Before any multi-agent step, read the sibling **pstack** skill: 1. `pstack/references/capability-contract.md` -2. Matching adapter under `pstack/references/adapters/`: - - `claude-code.md` — Claude Code (`Agent` / `Task`) - - `droid.md` — Factory Droid (`Task`) - - `opencode.md` — OpenCode (`task` → explore/general/…) - - `codex.md` (+ `codex-models.md`) — OpenAI Codex / replaces codex-pstack - - `cursor.md` — Cursor (prefer official pstack plugin there) - - `generic.md` — unknown host (still parallelize if a spawn tool exists) - -If the `pstack` skill is missing, use whatever `Agent`/`Task`/`task` tool the host exposes with disjoint scopes; otherwise execute locally. +2. The matching adapter under `pstack/references/adapters/` for the active host (`claude-code`, `codex`, `droid`, `opencode`, `cursor`, or `generic`). + +Map capability verbs through that adapter. Do not invent tool parameters from another host. If spawning is unavailable, execute on the lead agent and say so. + diff --git a/skills/technical-writing/SKILL.md b/skills/technical-writing/SKILL.md index 4201e49..4d9cded 100644 --- a/skills/technical-writing/SKILL.md +++ b/skills/technical-writing/SKILL.md @@ -9,18 +9,12 @@ compatibility: Works with Agent Skills-compatible coding agents. Multi-agent opt ## Portability (required) -This skill is part of the portable **pstack** pack for multiple coding agents. - -1. Read `pstack` skill `references/capability-contract.md` (or this skill's `references/capability-contract.md` if present). -2. Detect the runtime and read one adapter before any delegation: - - Cursor → `references/adapters/cursor.md` (under the `pstack` or `poteto-mode` skill) - - Codex → `references/adapters/codex.md` - - Anything else / unsure → `references/adapters/generic.md` -3. Translate upstream Cursor mechanics through the adapter. Do **not** invent Cursor `Task` / `poteto-agent` / model slugs on runtimes that lack them. -4. If multi-agent tools are unavailable, collapse parallel work onto the main agent and say so briefly. - -Capability verbs: `explore`, `implement`, `review`, `parallel`, `ask_user`, `verify`, `model_role`. +This skill is part of the portable **pstack** pack. +1. Read the `pstack` capability contract and the adapter for the active coding agent before any helper delegation. +2. Prefer capability verbs (`explore`, `implement`, `review`, `parallel`, `ask_user`, `verify`, `model_role`) over vendor tool names. +3. Resolve models through `model_role`. Never require a vendor-specific model identifier. +4. When helper spawning is unavailable, run the work on the lead agent and state that fan-out was collapsed. The goal is writing a tired engineer understands on the first read. Four layers get you there, one question each: what kind of document is this, how do sentences address the reader, how much does each sentence carry, and can any sentence be read two ways. Apply all four. diff --git a/skills/technical-writing/references/runtime.md b/skills/technical-writing/references/runtime.md index df0e238..d9172df 100644 --- a/skills/technical-writing/references/runtime.md +++ b/skills/technical-writing/references/runtime.md @@ -3,12 +3,7 @@ Before any multi-agent step, read the sibling **pstack** skill: 1. `pstack/references/capability-contract.md` -2. Matching adapter under `pstack/references/adapters/`: - - `claude-code.md` — Claude Code (`Agent` / `Task`) - - `droid.md` — Factory Droid (`Task`) - - `opencode.md` — OpenCode (`task` → explore/general/…) - - `codex.md` (+ `codex-models.md`) — OpenAI Codex / replaces codex-pstack - - `cursor.md` — Cursor (prefer official pstack plugin there) - - `generic.md` — unknown host (still parallelize if a spawn tool exists) - -If the `pstack` skill is missing, use whatever `Agent`/`Task`/`task` tool the host exposes with disjoint scopes; otherwise execute locally. +2. The matching adapter under `pstack/references/adapters/` for the active host (`claude-code`, `codex`, `droid`, `opencode`, `cursor`, or `generic`). + +Map capability verbs through that adapter. Do not invent tool parameters from another host. If spawning is unavailable, execute on the lead agent and say so. + diff --git a/skills/typescript-best-practices/SKILL.md b/skills/typescript-best-practices/SKILL.md index 701f816..5d91628 100644 --- a/skills/typescript-best-practices/SKILL.md +++ b/skills/typescript-best-practices/SKILL.md @@ -9,18 +9,12 @@ compatibility: Works with Agent Skills-compatible coding agents. Multi-agent opt ## Portability (required) -This skill is part of the portable **pstack** pack for multiple coding agents. - -1. Read `pstack` skill `references/capability-contract.md` (or this skill's `references/capability-contract.md` if present). -2. Detect the runtime and read one adapter before any delegation: - - Cursor → `references/adapters/cursor.md` (under the `pstack` or `poteto-mode` skill) - - Codex → `references/adapters/codex.md` - - Anything else / unsure → `references/adapters/generic.md` -3. Translate upstream Cursor mechanics through the adapter. Do **not** invent Cursor `Task` / `poteto-agent` / model slugs on runtimes that lack them. -4. If multi-agent tools are unavailable, collapse parallel work onto the main agent and say so briefly. - -Capability verbs: `explore`, `implement`, `review`, `parallel`, `ask_user`, `verify`, `model_role`. +This skill is part of the portable **pstack** pack. +1. Read the `pstack` capability contract and the adapter for the active coding agent before any helper delegation. +2. Prefer capability verbs (`explore`, `implement`, `review`, `parallel`, `ask_user`, `verify`, `model_role`) over vendor tool names. +3. Resolve models through `model_role`. Never require a vendor-specific model identifier. +4. When helper spawning is unavailable, run the work on the lead agent and state that fan-out was collapsed. Apply the **type-system-discipline** principle skill first; this skill grounds it in TypeScript syntax. diff --git a/skills/typescript-best-practices/references/runtime.md b/skills/typescript-best-practices/references/runtime.md index df0e238..d9172df 100644 --- a/skills/typescript-best-practices/references/runtime.md +++ b/skills/typescript-best-practices/references/runtime.md @@ -3,12 +3,7 @@ Before any multi-agent step, read the sibling **pstack** skill: 1. `pstack/references/capability-contract.md` -2. Matching adapter under `pstack/references/adapters/`: - - `claude-code.md` — Claude Code (`Agent` / `Task`) - - `droid.md` — Factory Droid (`Task`) - - `opencode.md` — OpenCode (`task` → explore/general/…) - - `codex.md` (+ `codex-models.md`) — OpenAI Codex / replaces codex-pstack - - `cursor.md` — Cursor (prefer official pstack plugin there) - - `generic.md` — unknown host (still parallelize if a spawn tool exists) - -If the `pstack` skill is missing, use whatever `Agent`/`Task`/`task` tool the host exposes with disjoint scopes; otherwise execute locally. +2. The matching adapter under `pstack/references/adapters/` for the active host (`claude-code`, `codex`, `droid`, `opencode`, `cursor`, or `generic`). + +Map capability verbs through that adapter. Do not invent tool parameters from another host. If spawning is unavailable, execute on the lead agent and say so. + diff --git a/skills/unslop/SKILL.md b/skills/unslop/SKILL.md index 56c91e3..11b4e73 100644 --- a/skills/unslop/SKILL.md +++ b/skills/unslop/SKILL.md @@ -9,18 +9,12 @@ compatibility: Works with Agent Skills-compatible coding agents. Multi-agent opt ## Portability (required) -This skill is part of the portable **pstack** pack for multiple coding agents. - -1. Read `pstack` skill `references/capability-contract.md` (or this skill's `references/capability-contract.md` if present). -2. Detect the runtime and read one adapter before any delegation: - - Cursor → `references/adapters/cursor.md` (under the `pstack` or `poteto-mode` skill) - - Codex → `references/adapters/codex.md` - - Anything else / unsure → `references/adapters/generic.md` -3. Translate upstream Cursor mechanics through the adapter. Do **not** invent Cursor `Task` / `poteto-agent` / model slugs on runtimes that lack them. -4. If multi-agent tools are unavailable, collapse parallel work onto the main agent and say so briefly. - -Capability verbs: `explore`, `implement`, `review`, `parallel`, `ask_user`, `verify`, `model_role`. +This skill is part of the portable **pstack** pack. +1. Read the `pstack` capability contract and the adapter for the active coding agent before any helper delegation. +2. Prefer capability verbs (`explore`, `implement`, `review`, `parallel`, `ask_user`, `verify`, `model_role`) over vendor tool names. +3. Resolve models through `model_role`. Never require a vendor-specific model identifier. +4. When helper spawning is unavailable, run the work on the lead agent and state that fan-out was collapsed. Edit text to remove AI patterns and add human voice. diff --git a/skills/unslop/references/runtime.md b/skills/unslop/references/runtime.md index df0e238..d9172df 100644 --- a/skills/unslop/references/runtime.md +++ b/skills/unslop/references/runtime.md @@ -3,12 +3,7 @@ Before any multi-agent step, read the sibling **pstack** skill: 1. `pstack/references/capability-contract.md` -2. Matching adapter under `pstack/references/adapters/`: - - `claude-code.md` — Claude Code (`Agent` / `Task`) - - `droid.md` — Factory Droid (`Task`) - - `opencode.md` — OpenCode (`task` → explore/general/…) - - `codex.md` (+ `codex-models.md`) — OpenAI Codex / replaces codex-pstack - - `cursor.md` — Cursor (prefer official pstack plugin there) - - `generic.md` — unknown host (still parallelize if a spawn tool exists) - -If the `pstack` skill is missing, use whatever `Agent`/`Task`/`task` tool the host exposes with disjoint scopes; otherwise execute locally. +2. The matching adapter under `pstack/references/adapters/` for the active host (`claude-code`, `codex`, `droid`, `opencode`, `cursor`, or `generic`). + +Map capability verbs through that adapter. Do not invent tool parameters from another host. If spawning is unavailable, execute on the lead agent and say so. + diff --git a/skills/why/references/runtime.md b/skills/why/references/runtime.md index df0e238..d9172df 100644 --- a/skills/why/references/runtime.md +++ b/skills/why/references/runtime.md @@ -3,12 +3,7 @@ Before any multi-agent step, read the sibling **pstack** skill: 1. `pstack/references/capability-contract.md` -2. Matching adapter under `pstack/references/adapters/`: - - `claude-code.md` — Claude Code (`Agent` / `Task`) - - `droid.md` — Factory Droid (`Task`) - - `opencode.md` — OpenCode (`task` → explore/general/…) - - `codex.md` (+ `codex-models.md`) — OpenAI Codex / replaces codex-pstack - - `cursor.md` — Cursor (prefer official pstack plugin there) - - `generic.md` — unknown host (still parallelize if a spawn tool exists) - -If the `pstack` skill is missing, use whatever `Agent`/`Task`/`task` tool the host exposes with disjoint scopes; otherwise execute locally. +2. The matching adapter under `pstack/references/adapters/` for the active host (`claude-code`, `codex`, `droid`, `opencode`, `cursor`, or `generic`). + +Map capability verbs through that adapter. Do not invent tool parameters from another host. If spawning is unavailable, execute on the lead agent and say so. +