potetos-for-everyone 0.1.0

package/runtime/runner.py

@@ -0,0 +1,240 @@
+from __future__ import annotations
+
+import concurrent.futures
+import datetime as dt
+import json
+import os
+import re
+import secrets
+import subprocess
+import tempfile
+from dataclasses import dataclass, asdict
+from pathlib import Path
+from typing import Any
+
+
+@dataclass
+class RunResult:
+    runner: str
+    returncode: int
+    stdout_file: str
+    stderr_file: str
+    workspace: str
+    branch: str | None
+    command: list[str]
+    timed_out: bool = False
+
+
+def _slug(value: str) -> str:
+    value = re.sub(r"[^A-Za-z0-9._-]+", "-", value).strip("-")
+    return value[:48] or "worker"
+
+
+def _run_id() -> str:
+    stamp = dt.datetime.now(dt.timezone.utc).strftime("%Y%m%dT%H%M%SZ")
+    return f"{stamp}-{secrets.token_hex(3)}"
+
+
+def load_config(path: Path) -> dict[str, Any]:
+    if not path.exists():
+        raise FileNotFoundError(
+            f"runner config not found: {path}. Run setup-pstack or create .potetos/config.json."
+        )
+    data = json.loads(path.read_text(encoding="utf-8"))
+    runners = data.get("runners")
+    if not isinstance(runners, dict) or not runners:
+        raise ValueError("config must contain a non-empty 'runners' object")
+    for name, spec in runners.items():
+        if not isinstance(spec, dict):
+            raise ValueError(f"runner {name!r} must be an object")
+        cmd = spec.get("command")
+        if not isinstance(cmd, list) or not cmd or not all(isinstance(x, str) and x for x in cmd):
+            raise ValueError(f"runner {name!r}.command must be a non-empty string array")
+        if "environment" in spec and not isinstance(spec["environment"], dict):
+            raise ValueError(f"runner {name!r}.environment must be an object")
+        if "env_passthrough" in spec and (not isinstance(spec["env_passthrough"], list) or not all(isinstance(x, str) for x in spec["env_passthrough"])):
+            raise ValueError(f"runner {name!r}.env_passthrough must be a string array")
+    return data
+
+
+def _git_root(workspace: Path) -> Path:
+    p = subprocess.run(
+        ["git", "-C", str(workspace), "rev-parse", "--show-toplevel"],
+        text=True,
+        capture_output=True,
+    )
+    if p.returncode:
+        raise RuntimeError(f"--isolate requires a git worktree: {p.stderr.strip()}")
+    return Path(p.stdout.strip()).resolve()
+
+
+def _isolated_worktree(workspace: Path, run_id: str, runner: str) -> tuple[Path, str]:
+    root = _git_root(workspace)
+    status = subprocess.run(
+        ["git", "-C", str(root), "status", "--porcelain"],
+        text=True,
+        capture_output=True,
+        check=True,
+    ).stdout.splitlines()
+    dirty = []
+    for line in status:
+        path = line[3:] if len(line) > 3 else line
+        if path == ".potetos" or path.startswith(".potetos/"):
+            continue
+        dirty.append(line)
+    if dirty:
+        raise RuntimeError(
+            "--isolate refuses a dirty base because a new worktree would silently omit uncommitted changes: "
+            + "; ".join(dirty[:8])
+        )
+    parent = Path(tempfile.gettempdir()) / "potetos-worktrees" / _slug(root.name)
+    parent.mkdir(parents=True, exist_ok=True)
+    dest = parent / f"{run_id}-{_slug(runner)}"
+    branch = f"potetos/{run_id}/{_slug(runner)}"
+    p = subprocess.run(
+        ["git", "-C", str(root), "worktree", "add", "-b", branch, str(dest), "HEAD"],
+        text=True,
+        capture_output=True,
+    )
+    if p.returncode:
+        raise RuntimeError(f"failed to create isolated worktree: {p.stderr.strip()}")
+    return dest, branch
+
+
+def _render_command(parts: list[str], *, prompt: str, prompt_file: Path, workspace: Path, output_file: Path) -> list[str]:
+    values = {
+        "prompt": prompt,
+        "prompt_file": str(prompt_file),
+        "workspace": str(workspace),
+        "output_file": str(output_file),
+    }
+    rendered = []
+    for part in parts:
+        try:
+            rendered.append(part.format_map(values))
+        except KeyError as e:
+            raise ValueError(f"unknown runner command placeholder: {e.args[0]}") from e
+    return rendered
+
+
+def run_worker(
+    *,
+    config: dict[str, Any],
+    runner: str,
+    prompt: str,
+    workspace: Path,
+    runs_dir: Path,
+    run_id: str | None = None,
+    isolate: bool = False,
+) -> RunResult:
+    run_id = run_id or _run_id()
+    runners = config["runners"]
+    if runner not in runners:
+        raise KeyError(f"runner {runner!r} not configured; available: {', '.join(sorted(runners))}")
+    spec = runners[runner]
+
+    branch = None
+    actual_workspace = workspace.resolve()
+    if isolate:
+        actual_workspace, branch = _isolated_worktree(actual_workspace, run_id, runner)
+
+    outdir = runs_dir.resolve() / run_id / _slug(runner)
+    outdir.mkdir(parents=True, exist_ok=True)
+    prompt_file = outdir / "prompt.txt"
+    stdout_file = outdir / "stdout.txt"
+    stderr_file = outdir / "stderr.txt"
+    result_file = outdir / "result.json"
+    prompt_file.write_text(prompt, encoding="utf-8")
+
+    command = _render_command(
+        spec["command"],
+        prompt=prompt,
+        prompt_file=prompt_file,
+        workspace=actual_workspace,
+        output_file=stdout_file,
+    )
+    env = os.environ.copy()
+    env.update({str(k): str(v) for k, v in spec.get("environment", {}).items()})
+    for key in spec.get("env_passthrough", []):
+        if key not in os.environ:
+            raise ValueError(f"runner {runner!r} requires missing environment variable {key}")
+        env[key] = os.environ[key]
+    timeout = int(spec.get("timeout_seconds", 1800))
+    stdin_text = prompt if spec.get("stdin", False) else None
+
+    timed_out = False
+    try:
+        p = subprocess.run(
+            command,
+            cwd=actual_workspace,
+            input=stdin_text,
+            text=True,
+            capture_output=True,
+            timeout=timeout,
+            env=env,
+        )
+        returncode = p.returncode
+        stdout = p.stdout
+        stderr = p.stderr
+    except subprocess.TimeoutExpired as e:
+        timed_out = True
+        returncode = 124
+        stdout = e.stdout.decode() if isinstance(e.stdout, bytes) else (e.stdout or "")
+        stderr = e.stderr.decode() if isinstance(e.stderr, bytes) else (e.stderr or "")
+        stderr += f"\npotetos: runner timed out after {timeout}s\n"
+
+    stdout_file.write_text(stdout, encoding="utf-8")
+    stderr_file.write_text(stderr, encoding="utf-8")
+    result = RunResult(
+        runner=runner,
+        returncode=returncode,
+        stdout_file=str(stdout_file),
+        stderr_file=str(stderr_file),
+        workspace=str(actual_workspace),
+        branch=branch,
+        command=command,
+        timed_out=timed_out,
+    )
+    result_file.write_text(json.dumps(asdict(result), indent=2) + "\n", encoding="utf-8")
+    return result
+
+
+def run_panel(
+    *,
+    config: dict[str, Any],
+    runner_names: list[str],
+    prompt: str,
+    workspace: Path,
+    runs_dir: Path,
+    isolate: bool = False,
+    max_parallel: int | None = None,
+) -> tuple[str, list[RunResult]]:
+    run_id = _run_id()
+    names = runner_names or list(config["runners"])
+    if not names:
+        raise ValueError("panel requires at least one runner")
+    if len(set(names)) != len(names):
+        raise ValueError("panel runner names must be unique so evidence remains attributable")
+    parallel = max_parallel or min(len(names), int(config.get("max_parallel", 4)))
+    results: list[RunResult] = []
+    with concurrent.futures.ThreadPoolExecutor(max_workers=max(1, parallel)) as pool:
+        futures = {
+            pool.submit(
+                run_worker,
+                config=config,
+                runner=name,
+                prompt=prompt,
+                workspace=workspace,
+                runs_dir=runs_dir,
+                run_id=run_id,
+                isolate=isolate,
+            ): name
+            for name in names
+        }
+        for future in concurrent.futures.as_completed(futures):
+            results.append(future.result())
+    results.sort(key=lambda r: names.index(r.runner))
+    summary = runs_dir.resolve() / run_id / "panel.json"
+    summary.parent.mkdir(parents=True, exist_ok=True)
+    summary.write_text(json.dumps([asdict(r) for r in results], indent=2) + "\n", encoding="utf-8")
+    return run_id, results

package/skills/architect/SKILL.md

@@ -0,0 +1,14 @@
+---
+name: architect
+description: Settle data shapes, ownership, boundaries, and interfaces before code crosses a function/module boundary. Use for non-trivial design work.
+---
+# Architect
+
+Read the caller first. Architecture starts from use, not from an isolated abstraction.
+
+1. Name the domain data shape and invariants.
+2. Map ownership and lifecycle. For concurrency, identify what is truly shared before proposing synchronization.
+3. Draft 2-3 boundary shapes when the decision is contested. If `delegate` is available, assign independent designs; otherwise keep alternatives explicit and sequential.
+4. Compare on reader load, invalid states, migration cost, idempotence, testability, and fit with existing architecture.
+5. Select the smallest coherent shape and write the caller-facing signature/contract before implementation.
+6. Use `interrogate` for high-risk or contested decisions.

package/skills/arena/SKILL.md

@@ -0,0 +1,14 @@
+---
+name: arena
+description: Spawn parallel candidate implementations for the same task, cross-judge, and graft the best parts into the winning base. Use when exploring competing designs or critical artifacts.
+---
+# Arena
+
+Fan out N parallel attempts at the same task, score them against concrete criteria, pick a base, and graft the best ideas from the others.
+
+1. Frame: Define the artifact contract, 3-6 concrete rubric criteria, and isolated candidate output paths.
+2. Fan out: Run parallel candidate attempts on isolated workers (via `delegate` when supported, or labeled sequential passes). Require a concrete artifact and short rationale from each.
+3. Cross-judge: Score each candidate against the rubric criteria, compare trade-offs, and recommend the strongest base.
+4. Pick a base: Select the implementation that is cleanest, easiest to maintain, and safest under domain invariants.
+5. Graft: Port the best independent ideas or edge-case handling from losing candidates into the base by hand.
+6. Verify: Validate the synthesized result against the full test and verification suite.

package/skills/automate-me/SKILL.md

@@ -0,0 +1,11 @@
+---
+name: automate-me
+description: Create a personal mode skill from recurring workflow patterns in available history. Use when the user wants their own agent style encoded.
+---
+# Automate Me
+
+1. Gather a representative sample of the user's actual completed workflows from available, authorized history. Do not infer private history you cannot access.
+2. Extract repeated triggers, decisions, quality gates, preferred artifacts, and successful repair loops. Ignore one-off stylistic quirks unless explicitly requested.
+3. Separate universal engineering principles from user-specific routing preferences.
+4. Draft a `<name>-mode` Agent Skill that routes through existing skills rather than duplicating them.
+5. Validate triggers against positive and negative examples, then present the generated skill and evidence behind each rule.

package/skills/blast-radius/SKILL.md

@@ -0,0 +1,11 @@
+---
+name: blast-radius
+description: Prove what a small-looking change can affect before or after editing. Use for compatibility, caller, state, schema, or behavior impact analysis.
+---
+# Blast Radius
+
+1. Name the changed contract: type, value, state transition, API, storage shape, timing, style token, or side effect.
+2. Enumerate direct readers/writers/callers and any serialized/public boundaries.
+3. Trace transitive assumptions by search, type references, tests, runtime wiring, and history as available.
+4. Identify the strongest fact that would make the change safe and prove that fact by running or inspecting code when possible.
+5. Return affected surfaces grouped as definite, plausible, and ruled out with evidence. Never write "safe" without the proof behind it.

package/skills/bro/SKILL.md

@@ -0,0 +1,7 @@
+---
+name: bro
+description: Restate the last technical explanation in plain human language with minimal jargon. Use when the user asks for a simpler version.
+---
+# Bro
+
+Restate the answer in ordinary language. Keep the causal chain and the important caveat. Replace jargon with a concrete example where possible. Do not dumb down the actual conclusion or add new claims.

package/skills/create-verification-skill/SKILL.md

@@ -0,0 +1,11 @@
+---
+name: create-verification-skill
+description: Generate a project-local verification skill that drives the real app and captures evidence. Use when setting up automated verification for a repo.
+---
+# Create Verification Skill
+
+1. Interview the repository to discover primary user-facing surfaces (web UI, CLI, API, app).
+2. Identify the canonical local start command, ports, environment variables, and required seed data.
+3. Determine how an agent can programmatically drive the system (browser/CDP, PTY/CLI, HTTP requests) and capture evidence (screenshots, transcripts, logs, exit codes).
+4. Verify isolation requirements: identify if instances can run concurrently or need dedicated ports/profiles.
+5. Create `.agents/skills/verify-<app>/SKILL.md` with explicit launch, drive, observe, and cleanup instructions.

package/skills/figure-it-out/SKILL.md

@@ -0,0 +1,13 @@
+---
+name: figure-it-out
+description: Design a rigorous custom playbook when no bundled playbook safely fits a large or unusual task. Use for cross-cutting ambiguous execution.
+---
+# Figure It Out
+
+1. Define the completion predicate and non-goals.
+2. Inventory uncertainty. Split it into factual questions, empirical forks, product preferences, and irreversible decisions.
+3. Resolve facts by investigation and empirical forks by prototype instead of asking the human when tools can decide.
+4. Build a dependency graph of verifiable work units with a proof attached to every node.
+5. Identify which units can safely fan out and which share mutable state.
+6. Write the bespoke playbook, then execute it using existing skills rather than improvising around its gates.
+7. Maintain a decision trail for work that can outlive the current session.

package/skills/how/SKILL.md

@@ -0,0 +1,14 @@
+---
+name: how
+description: Trace how a subsystem works using code and runtime evidence. Use for architecture walkthroughs, data flow, call paths, and are-we-sure investigations.
+---
+# How
+
+Build an evidence-backed explanation of how the requested subsystem works.
+
+1. Find the public/consumer entry point, then trace data and control flow toward the effect. Do not start from filenames guessed by name alone.
+2. Read the core types and state ownership before narrating individual functions.
+3. Use `vcs`, tests, or `observe` when they resolve an ambiguity. If `delegate` exists, split independent exploration areas and reconcile them yourself.
+4. Draw a compact text or Mermaid diagram when it reduces reader load.
+5. Test at least one claim that could easily be wrong by running or inspecting the real path.
+6. Explain in consumer order: trigger -> boundary -> state/transform -> side effect -> observable result. Name file/symbol evidence and uncertainty.

package/skills/interrogate/SKILL.md

@@ -0,0 +1,14 @@
+---
+name: interrogate
+description: Adversarially review a diff or design with independent lenses and evidence. Use before shipping contested or high-impact changes.
+---
+# Interrogate
+
+Reviewers are attackers, not style voters.
+
+1. Freeze the exact artifact/revision and acceptance criteria.
+2. Cover at least these lenses: correctness/invariants, boundary/API compatibility, concurrency/state, tests/verification quality, and maintainability/reader load. Add security/performance when relevant.
+3. Use independent workers/models when `delegate` exists. Otherwise run separate sequential lenses and disclose they share context.
+4. Require each finding to include a concrete failure mode and evidence or a reproducible check. Reject unsupported nits.
+5. The owning agent adjudicates every finding as fix, dismiss, or investigate. Never pass reviewer prose through unexamined.
+6. Re-run targeted proof after accepted fixes.

package/skills/maintain-verification-skill/SKILL.md

@@ -0,0 +1,11 @@
+---
+name: maintain-verification-skill
+description: Repair a project verification skill whose feature map or commands drifted. Use when app behavior and verification docs no longer agree.
+---
+# Maintain Verification Skill
+
+1. Diff the current product surfaces against the verification feature map.
+2. Run one representative live pass before changing the skill so drift is observed, not guessed.
+3. Classify differences as product regression, intentional product change, environment drift, or verifier bug.
+4. Update only proven verifier drift. Do not rewrite expectations to make a product regression green.
+5. Re-run affected features plus one untouched control feature.

package/skills/make-bot-ui/SKILL.md

@@ -0,0 +1,11 @@
+---
+name: make-bot-ui
+description: Build a small operator UI over an agent/webhook backend. Use when buttons or controls should trigger an agent workflow.
+---
+# Make Bot UI
+
+1. Define the operator actions, payload schema, authentication boundary, and observable completion state before UI code.
+2. Keep secrets server-side. Treat webhook URLs/tokens as credentials.
+3. Implement the thinnest UI that exposes state, errors, retries, and idempotent request IDs.
+4. Make every action safe under duplicate delivery or refresh.
+5. Verify one full round trip through the real backend when `observe`/network access exists. Otherwise ship a deterministic local mock plus an explicit integration gap.

package/skills/no-comments/SKILL.md

@@ -0,0 +1,11 @@
+---
+name: no-comments
+description: Remove redundant comments, dead workaround explanations, and AI tells from code while preserving necessary constraints. Use when cleaning up code or diffs.
+---
+# No Comments
+
+1. Identify comments that explain obvious code, restate syntax, or explain temporary workarounds that should be deleted.
+2. Distinguish legitimate constraints (hard external requirements, regulatory/spec references, non-obvious invariants) from redundant explanations.
+3. Convert valid constraint comments into types, tests, assertions, or lints whenever possible.
+4. Delete redundant commentary, commented-out dead code, and speculative notes.
+5. Verify that code remains readable and self-documenting through clear naming and small, focused functions.

package/skills/poteto-mode/SKILL.md

@@ -0,0 +1,93 @@
+---
+name: poteto-mode
+description: Lauren Tan-inspired rigorous engineering mode for concise communication, deliberate decomposition, simple code, independent review when available, and runtime verification. Use for non-trivial engineering tasks or when the user asks for Poteto Mode/pstack-style rigor.
+---
+# Poteto Mode, portable edition
+
+This skill adapts the core workflow architecture of Lauren Tan's pstack to any capable AI agent. Credit and provenance live in the repository `NOTICE.md`.
+
+## Non-negotiables
+
+1. **Classify before acting.** Match the request to one playbook below. For large cross-cutting work with no clean match, use `figure-it-out`. For program-scale standing work, use `orchestrate`.
+2. **Name the data shape before non-trivial code.** Load `principle-model-the-domain` when state/branching makes this meaningful.
+3. **Resolve empirical forks empirically.** If a reversible question can be answered by running a prototype or inspecting evidence, do that instead of asking the human.
+4. **Cross a boundary deliberately.** Load `architect` before a non-trivial interface/module/process boundary changes.
+5. **Use parallelism only when it is real.** `arena`, `swarm`, and `interrogate` may use isolated `delegate` workers. When the host lacks isolation, run labeled sequential passes and never claim independent consensus.
+6. **Own delegated work.** Review artifacts and evidence yourself. A worker's "done" is not proof.
+7. **Finish with the real proof.** Load `principle-prove-it-works`. Verify through the closest consumer-facing artifact available. Name any missing runtime surface.
+8. **Keep the change small.** Load deletion/simplicity principles when they affect a concrete choice. Do not apply principles as decorative slogans.
+9. **Write plainly.** For durable docs load `technical-writing`; for any prose, apply `unslop`.
+10. **Respect host safety and permissions.** Reversible workspace work can proceed. Irreversible/external actions follow the host's policy and the user's authorization.
+
+## Capability behavior
+
+Read the repository `PORTABILITY.md` when present. Feature-detect `run`, `vcs`, `delegate`, `search`, `observe`, and `track`. Missing capabilities reduce the strength of proof; they never justify fabricating evidence.
+
+## Routing
+
+- `investigation`: Read-only investigation
+- `bug-fix`: Bug fix
+- `perf-issue`: Performance issue
+- `hillclimb`: Metric hillclimb
+- `runtime-forensics`: Runtime forensics
+- `trace-forensics`: Captured trace forensics
+- `feature`: Feature
+- `refactoring`: Refactoring
+- `prototype`: Prototype
+- `visual-parity`: Visual parity
+- `authoring-a-skill`: Authoring a skill
+- `eval`: Skill or prompt evaluation
+- `babysit`: Drive a PR to merge-ready
+- `shipping`: Verify and ship
+- `autonomous-run`: Autonomous run
+- `orchestrate`: Project orchestration
+- `autopilot-full`: Independent PR autopilot
+- `autopilot-stack`: Linear stack autopilot
+- `session-pickup`: Session pickup
+- `pause-safely`: Pause safely
+- `multi-phase-plan`: Multi-phase work
+- `worktree-cleanup`: Worktree and local-state cleanup
+- `opening-a-pr`: Open a pull request
+
+The internal `opening-a-pr` playbook is normally a final step when the task includes creating a PR and the host can do so.
+
+## Execution
+
+1. Read the selected file in `playbooks/` completely.
+2. If the host offers a todo/task tracker, copy the playbook steps into it. Otherwise keep a compact checklist in working notes. Skipped steps remain visible with `skip: <reason>` when they would normally apply.
+3. Load only supporting skills/principles that a concrete step triggers. Avoid loading the entire stack into context.
+4. Execute in verifiable units. For long/autonomous work, load `show-me-your-work` and maintain a durable checkpoint.
+5. Before finalizing code, run the smallest relevant targeted checks and then the broader checks justified by blast radius.
+6. Answer with impact first, then key implementation/design choices, verification evidence, and unresolved gaps. Do not forward raw worker summaries.
+
+## Principle index
+
+Load a leaf skill only when its rule changes a decision in this task.
+
+- `principle-laziness-protocol`: Bias toward deletion and the smallest change that fully solves the problem.
+- `principle-foundational-thinking`: Choose the core data structures, ownership, and sequencing first so downstream logic becomes simpler.
+- `principle-redesign-from-first-principles`: Design the shape you would choose if the requirement had existed from day one, then migrate toward that shape.
+- `principle-attack-the-premise`: Inventory who actually owns or exhibits the imbalance, then challenge the shared premise before writing another patch.
+- `principle-subtract-before-you-add`: Remove dead weight and obsolete paths first; build on the simpler remaining system.
+- `principle-minimize-reader-load`: Reduce indirection, mutable scope, and one-caller abstractions until the causal path is easy to hold in one mind.
+- `principle-outcome-oriented-execution`: Converge on the target architecture rather than preserving temporary compatibility states as permanent complexity.
+- `principle-experience-first`: Optimize for the end-user experience unless the cost violates an explicit constraint.
+- `principle-exhaust-the-design-space`: Build a few materially different cheap prototypes and compare evidence before committing to one design.
+- `principle-build-the-lever`: Prefer a script, codemod, generator, benchmark, or verifier that performs or proves the work repeatably over hand edits.
+- `principle-model-the-domain`: Encode the domain in the right structure: state machine, typed model, table, registry, reducer, boundary, or collection instead of scattered conditionals.
+- `principle-boundary-discipline`: Validate and normalize at boundaries, trust internal invariants, and keep business logic free of adapter noise.
+- `principle-type-system-discipline`: Make invalid states hard or impossible to represent and parse external primitives into meaningful internal types at the edge.
+- `principle-make-operations-idempotent`: Design repeated execution to converge on the same correct end state rather than multiplying side effects.
+- `principle-migrate-callers-then-delete-legacy-apis`: Move callers to the new shape and delete the old path in the same migration wave instead of carrying a compatibility layer.
+- `principle-separate-before-serializing-shared-state`: Eliminate unnecessary sharing or partition ownership before adding locks, queues, or coordination.
+- `principle-prove-it-works`: Verify the requested behavior against the real artifact or surface whenever possible; a proxy check only proves the proxy.
+- `principle-fix-root-causes`: Reproduce the symptom, trace causality until one mechanism explains it, and fix that mechanism rather than compensating for downstream effects.
+- `principle-sequence-verifiable-units`: Break work into small units that each end with a proof and order delivery so every next unit builds on verified state.
+- `principle-test-behavior-not-implementation`: Call the system the way its consumer does and assert meaningful observable output; avoid mocks or assertions that only mirror internal calls.
+- `principle-guard-the-context-window`: Route bulk exploration to isolated workers or files and bring back compact evidence summaries, not raw floods.
+- `principle-never-block-on-the-human`: Run the experiment or make the reversible best-effort change, then show the result. Ask only for genuine preference, authority, or irreversible decisions.
+- `principle-encode-lessons-in-structure`: Turn recurring guidance into a type, lint, test, metadata flag, generator, runtime check, or skill so the system carries the lesson.
+
+## Autonomy
+
+Prefer action over clarification for reversible work whose correct answer can be observed. Ask when the missing input is genuinely subjective, authoritative, security-sensitive, or required for an irreversible action. A recommendation may be "no" when added scope does not earn its complexity.

package/skills/poteto-mode/playbooks/authoring-a-skill.md

@@ -0,0 +1,7 @@
+# Authoring a skill
+
+1. Define precise triggers, non-triggers, outcome, and required capabilities.
+2. Keep the SKILL.md focused. Move heavy examples, references, and scripts into progressive-disclosure files.
+3. Use portable capability language. Add a fallback for optional capabilities instead of hard-coding one host tool.
+4. Validate Agent Skills frontmatter and directory/name parity.
+5. Exercise the skill on representative positive and negative cases. Revise based on behavior, not aesthetics alone.

package/skills/poteto-mode/playbooks/autonomous-run.md

@@ -0,0 +1,7 @@
+# Autonomous run
+
+1. Translate the request into an explicit completion predicate, constraints, and irreversible-action boundaries.
+2. Create a decision trail and a small queue of verifiable units.
+3. Loop: choose the highest-leverage unit, execute it, verify it, checkpoint the result, then recompute the queue from evidence.
+4. Do not idle waiting for a human on reversible work. Do not fabricate progress when a capability is unavailable.
+5. Stop only when the predicate is satisfied, an explicit safety boundary requires the human, or a blocker cannot be removed with available capabilities.

package/skills/poteto-mode/playbooks/autopilot-full.md

@@ -0,0 +1,7 @@
+# Independent PR autopilot
+
+1. Inventory the independent PR/change queue and define merge criteria for each item.
+2. Assign one owner per item. Owners build, verify, address review/CI, and maintain a clean head.
+3. Before merge, obtain an independent verification verdict for that exact head.
+4. Allow the owner to land only after the independent verdict and current PR state agree.
+5. Reconcile the base after each merge and re-evaluate queued items for new conflicts or invalidated assumptions.

package/skills/poteto-mode/playbooks/autopilot-stack.md

@@ -0,0 +1,7 @@
+# Linear stack autopilot
+
+1. Define the ordered change stack and acceptance gate for every layer.
+2. Build each layer on the verified previous layer. Keep one coherent linear base and avoid parallel edits to shared stack state.
+3. Verify each layer before adding the next; repair at the lowest layer that explains a failure.
+4. Deliver the full reviewed stack without landing it unless the operator explicitly requested shipping.
+5. Report stack order, head revisions, per-layer proof, and any assumptions the operator must check before landing.

package/skills/poteto-mode/playbooks/babysit.md

@@ -0,0 +1,7 @@
+# Drive a PR to merge-ready
+
+1. Inspect current branch/PR state, review threads, conflicts, and CI before changing anything.
+2. Classify blockers into code defect, flaky/infrastructure failure, conflict, review request, or non-actionable noise.
+3. Resolve one concrete blocker at a time. Reproduce code failures when possible and keep fixes scoped.
+4. Re-run only the checks needed to establish a new state, then refresh PR status.
+5. Stop at merge-ready or a real external blocker. Report outstanding items exactly; do not equate green CI with safe-to-merge.

package/skills/poteto-mode/playbooks/bug-fix.md

@@ -0,0 +1,8 @@
+# Bug fix
+
+1. Reproduce the defect on the closest real surface available. Record exact observed and expected behavior.
+2. Trace the failing behavior to a root cause before editing. If the symptom cannot be reproduced, gather evidence rather than guessing.
+3. When a cheap automated path exists, add or identify a behavior-level check that fails for the same reason.
+4. Make the smallest change that fixes the root cause. Avoid nearby cleanup unless it reduces the fix itself.
+5. Re-run the reproduction and targeted checks, then the smallest broader suite that can catch collateral damage.
+6. Report root cause, change, proof, and any verification surface that was unavailable.

package/skills/poteto-mode/playbooks/eval.md

@@ -0,0 +1,7 @@
+# Skill or prompt evaluation
+
+1. Define the behavior under test, score rubric, guardrails, and representative task set before seeing candidate outputs.
+2. Freeze the baseline and candidate. Randomize or blind judging when practical.
+3. Run both under comparable tools, models, context, and budgets.
+4. Score outcomes and failure modes, not writing similarity. Inspect regressions individually.
+5. Promote only when the candidate clears the primary metric without unacceptable guardrail regressions. Preserve the eval artifacts.

package/skills/poteto-mode/playbooks/feature.md

@@ -0,0 +1,8 @@
+# Feature
+
+1. Name the user-visible outcome and the core data shape/state transition before writing logic.
+2. Inspect the existing caller, boundary, and test/verification path. Reuse the native shape when it already fits.
+3. Write a throughput checkpoint: what can be implemented and verified as one coherent unit, and what is explicitly out of scope.
+4. Settle cross-boundary types/contracts before implementation. Prototype only genuine empirical forks.
+5. Implement the smallest end-to-end slice that produces the outcome.
+6. Verify through the consumer-facing path, plus targeted automated checks. Report the outcome before implementation detail.

package/skills/poteto-mode/playbooks/hillclimb.md

@@ -0,0 +1,8 @@
+# Metric hillclimb
+
+1. Define one primary metric, guardrail metrics, target, and reproducible benchmark command.
+2. Capture and save the baseline.
+3. Create a ranked hypothesis queue. Change one meaningful variable per iteration.
+4. For each iteration, benchmark before accepting it. Keep only wins that survive the guardrails.
+5. Checkpoint each accepted win independently so the sequence is bisectable and reversible.
+6. Stop at the target, a clearly exhausted hypothesis space, or a real blocker. Summarize accepted and rejected hypotheses with evidence.

package/skills/poteto-mode/playbooks/investigation.md

@@ -0,0 +1,7 @@
+# Read-only investigation
+
+1. Restate the question as a falsifiable claim or a small set of claims.
+2. Map the evidence that can answer it: code, tests, history, docs, tickets, runtime data, or connected sources. Read the highest-signal source first.
+3. Trace the relevant call/data path end to end. Separate observed facts from inference.
+4. Try to disprove the leading explanation with one targeted counter-check.
+5. Answer the question directly. Cite concrete files, revisions, commands, or external evidence that were actually inspected. Name unresolved gaps.

package/skills/poteto-mode/playbooks/multi-phase-plan.md

@@ -0,0 +1,7 @@
+# Multi-phase work
+
+1. Define the target end state and phase boundaries in terms of observable acceptance criteria.
+2. Order phases so each one simplifies or unlocks the next and can be verified independently.
+3. Name temporary states explicitly. Do not preserve a transition API as permanent architecture unless it earns a long-term role.
+4. For each phase, list input state, changes, proof, rollback/checkpoint, and dependencies.
+5. Execute and verify one phase at a time. Re-plan downstream phases when evidence invalidates the original sequence.

package/skills/poteto-mode/playbooks/opening-a-pr.md

@@ -0,0 +1,7 @@
+# Open a pull request
+
+1. Review the complete diff against the task and remove unrelated changes.
+2. Run targeted and required repository checks. Record exact results.
+3. Write a concise title and description centered on user/maintainer impact, root cause or design choice, and verification.
+4. Open the PR through the available VCS host only when permissions allow. Return the real URL or identifier; never invent one.
+5. Refresh status once and report any immediate blocker.

package/skills/poteto-mode/playbooks/orchestrate.md

@@ -0,0 +1,8 @@
+# Project orchestration
+
+1. Define program outcome, milestone graph, shared interfaces, acceptance gates, and integration branch/state.
+2. Partition work so each slice has one owner and minimal shared mutable state. Separate before serializing.
+3. Delegate independent slices when isolated workers exist. Otherwise sequence them and label the loss of independent verification.
+4. Require each slice to return artifacts and evidence, not a done-summary. Integrate only after owner-independent review.
+5. Continuously recompute dependencies and risk. Keep a durable decision/integration log for session pickup.
+6. Close milestones only when the integrated artifact passes its gate, then verify the program-level outcome.

package/skills/poteto-mode/playbooks/pause-safely.md

@@ -0,0 +1,7 @@
+# Pause safely
+
+1. Stop creating new work and finish or revert any half-applied local operation.
+2. Record branch/worktree, dirty files, running jobs, external state, decisions, and the last verified checkpoint.
+3. Run the cheapest sanity check that proves the paused state is coherent.
+4. Write a pickup note with exact next action and any action that must not be repeated.
+5. Do not leave irreversible external actions armed or ambiguous.

package/skills/poteto-mode/playbooks/perf-issue.md

@@ -0,0 +1,8 @@
+# Performance issue
+
+1. Define the user-visible metric and capture a baseline under controlled conditions.
+2. Profile or instrument the actual slow path. Do not optimize from source inspection alone when measurement is possible.
+3. Name the dominant cost and form one hypothesis that predicts a measurable improvement.
+4. Apply the smallest change that tests the hypothesis.
+5. Re-measure against the same baseline. Reject changes that merely move cost or regress another required metric.
+6. Report before/after numbers, environment, traces used, and remaining bottlenecks.