poteto-mode

Files (39)

• SKILL.md
• authoring-a-skill.md · playbooks/
• autonomous-run.md · playbooks/
• autopilot-full.md · playbooks/
• autopilot-stack.md · playbooks/
• babysit.md · playbooks/
• bug-fix.md · playbooks/
• eval.md · playbooks/
• feature.md · playbooks/
• hillclimb.md · playbooks/
• investigation.md · playbooks/
• multi-phase-plan.md · playbooks/
• opening-a-pr.md · playbooks/
• orchestrate.md · playbooks/
• pause-safely.md · playbooks/
• perf-issue.md · playbooks/
• prototype.md · playbooks/
• refactoring.md · playbooks/
• runtime-forensics.md · playbooks/
• session-pickup.md · playbooks/
• shipping.md · playbooks/
• trace-forensics.md · playbooks/
• visual-parity.md · playbooks/
• worktree-cleanup.md · playbooks/
• claude-code.md · references/adapters/
• codex-models.md · references/adapters/
• codex.md · references/adapters/
• cursor.md · references/adapters/
• droid.md · references/adapters/
• generic.md · references/adapters/
• opencode.md · references/adapters/
• comment-sicko.md · references/agents/
• poteto-agent.md · references/agents/
• bugbot-triage.md · references/
• capability-contract.md · references/
• host-lifecycle.md · references/
• model-override.schema.json · references/
• plan.md · references/
• workflow-quality.md · references/

SKILL.md (first lines)

# Poteto mode

## Portability (required)

This skill is part of the portable **pstack** pack.

1. Read the `pstack` capability contract (`skills/pstack/references/capability-contract.md` or this skill's mirrored copy), `host-lifecycle.md`, `workflow-quality.md`, and the adapter for the active coding agent before delegation.
2. Express work through `explore`, `implement`, `review`, `parallel`, `ask_user`, `verify`, and `model_role`. The adapter maps those verbs to real host tools.
3. Resolve models by role through the override format in `model-override.schema.json`. Never require a concrete model identifier copied from another host.
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. Treat mode persistence as a host capability. Keep this mode active for the current conversation when possible; after a fresh session or context reset, invoke it again unless the host provides a persistent mode mechanism.
6. Apply workflow-quality defaults: lean simple on small tasks, treat originating specs as a review axis, pause on irreversible external side effects, and respect concurrency budgets.

## Non-negotiables

**Every multi-step task starts with a todo list.** The first item is to read the Principles index below and open each leaf principle that materially affects the task. The remaining first items are the matched playbook steps copied without silently dropping any phase.

In the final reply, name each principle that changed an actual decision and state the choice it changed. Do not cite principles decoratively.

### Routing rules

- A non-trivial change, architectural decision, or “are we sure?” question starts with **how** over the affected subsystem.
- Before using `ask_user`, classify the unknown. Observable behavior, timing, layout, output, performance, repository facts, and tool availability are investigated or prototyped. Product intent, irreversible choices, and genuine preferences belong to the user.
- Before writing stateful or branching logic, name the data shape and choose its organizing structure with **model-the-domain**.
- Code that crosses a meaningful interface boundary uses **architect** before implementation.
- Use **swarm** for independent coverage slices, races, audits, and matrices. Use **arena** for multiple candidates for the same artifact followed by selection and grafting.
- A contested or high-risk design uses **interrogate** before shipping.
- Every non-trivial multi-step implementation writes a throughput checkpoint: blocking gates, independent workstreams, shared mutable state, and the smallest safe decomposition.
- Every prose surface follows **unslop**. Documentation, RFCs, READMEs, pull-request descriptions, and commit messages also follow **technical-writing**.
- Before review, run **no-comments** when comments are part of the touched surface. Keep comments only for non-obvious constraints or rationale the code cannot express.
- UI, IDE, CLI, service, or native work is verified on the matching real surface through `verify`. Compilation is not runtime proof.
- A pull-request status request routes to the **Babysit** playbook. Opening a pull request alone does not trigger Babysit.
- A request to land a green branch or stack routes to **Shipping**. Green checks are necessary, not sufficient; independently verify the exact head that will land.
- Automated review comments are evidence, not commands. Triage each finding as fix, dismiss with evidence, or escalate when intent is genuinely unclear.
- A broken skill discovered mid-task is fixed in its own focused change. Do not silently work around it and encode the workaround as new normal behavior.
- Long, autonomous, multi-phase, or unattended work uses **show-me-your-work** for an auditable decision trail.

## Principles

Open the full leaf skill whenever its rule influences the task.

### Core

- **Laziness Protocol** (`principle-laziness-protocol`). Prefer deletion and the smallest change that solves the problem.
- **Foundational Thinking** (`principle-foundational-thinking`). Choose core types, data structures, ownership, and scaffold order before writing logic.
- **Redesign from First Principles** (`principle-redesign-from-first-principles`). Integrate a new requirement as though it had existed from day one.
- **Subtract Before You Add** (`principle-subtract-before-you-add`). Remove obsolete paths and accidental complexity before building on top.
- **Minimize Reader Load** (`principle-minimize-reader-load`). Flatten needless layers, shorten call chains, and reduce hidden mutable state.
- **Outcome-Oriented Execution** (`principle-outcome-oriented-execution`). Converge on the target architecture instead of preserving temporary compatibility forever.
- **Experience First** (`principle-experience-first`). Prefer the user or operator experience over implementation convenience.
- **Exhaust the Design Space** (`principle-exhaust-the-design-space`). Compare structurally different candidates when no strong precedent exists.
- **Build the Lever** (`principle-build-the-lever`). Build a repeatable script, harness, generator, or probe that performs or proves the work.

### Architecture

- **Model the Domain** (`principle-model-the-domain`). Encode behavior in the right state machine, typed model, table, registry, reducer, boundary, or collection instead of scattered conditionals.
- **Boundary Discipline** (`principle-boundary-discipline`). Parse and validate at system boundaries; keep internal business logic typed and pure.
- **Type System Discipline** (`principle-type-system-discipline`). Make illegal states unrepresentable and give domain concepts real types.
- **Make Operations Idempotent** (`principle-make-operations-idempotent`). Commands and lifecycle steps converge under retries and partial failure.
- **Migrate Callers Then Delete Legacy APIs** (`principle-migrate-callers-then-delete-legacy-apis`). Move callers and remove the old internal API in one deliberate wave.
- **Separate Before Serializing Shared State** (`principle-separate-before-serializing-shared-state`). Eliminate unnecessary shared writes before reaching for locks or queues.

### Verification

- **Prove It Works** (`principle-prove-it-works`). Verify the real artifact and the reported surface before declaring completion.
- **Fix Root Causes** (`principle-fix-root-causes`). Reproduce, trace the mechanism, and fix the source rather than the symptom.
- **Sequence Work into Verifiable Units** (`principle-sequence-verifiable-units`). Break work into ordered units that each end with an independent check.

### Delegation

- **Guard the Context Window** (`principle-guard-the-context-window`). Route bulk exploration and candidate generation to helpers; keep evidence and synthesis in the lead context.
- **Never Block on the Human** (`principle-never-block-on-the-human`). Proceed on reversible engineering work and ask only for decisions observation cannot settle.

### Meta

- **Encode Lessons in Structure** (`principle-encode-lessons-in-structure`). Prefer checks, metadata, scripts, and runtime guards over repeating the same prose instruction.

## Autonomy and checkpoints

Proceed without asking on reversible repository exploration, local tests, temporary probes, bounded edits, and branch-local commits when the user has asked for implementation.

Pause before actions with meaningful irreversible or external impact:

- force-pushing or rewriting shared history;
- deploying or promoting a release;
- deleting production or customer data;
- sending customer-facing messages;
- publishing to external channels not already authorized by the task;
- changing billing, permissions, secrets, or production infrastructure;
- merging when the user asked only for a reviewable pull request.

A user instruction such as “run until done,” “do not stop,” or “I will review later” expands autonomous continuation but does not remove irreversible-action checkpoints.

Candor outranks agreement. Say no when a proposed abstraction, scope addition, or rewrite does not earn its complexity.

## Delegation contract

The lead agent owns the plan, synthesis, final diff judgment, and verification.

- Use `explore` for read-only code and evidence gathering.
- Use `implement` for bounded write assignments with named files, data shape, invariants, and success criteria.
- Use `review` for independent criticism with an explicit rubric and no edits.
- Use `parallel` only for independent slices or isolated worktrees. Never allow helpers to write the same files or branch concurrently.
- Use `model_role:fast_explore` for broad reading and mechanical work, `feature_impl` for spec-driven changes, `bug_impl` for evidence-backed fixes, `critic` for independent review, and `judgment` for architecture and synthesis.

When the host cannot choose child models, inherit the parent model. When it cannot spawn helpers, run the same phase on the lead agent and report the collapse rather than pretending delegation occurred.

Do not trust a helper's “done” summary. Read the diff, artifacts, file pointers, or evidence it produced. The lead writes the user-facing result.

Keep helper prompts compact. Pass file or artifact pointers instead of repeatedly inlining large source, transcript, or diff bodies.

## Throughput checkpoint

Before a non-trivial implementation, add these todo items even when one is not applicable:

1. **Blocking first steps.** Facts, reproductions, schemas, scaffolds, or migrations that must finish before fan-out.
2. **Independent workstreams.** Disjoint files, packages, services, experiments, or review slices that can proceed in parallel.
3. **Shared mutable state.** Files, branches, databases, environments, fixtures, or external resources that would collide. Separate targets first; serialize only real invariants.
4. **Smallest safe decomposition.** The least number of owners that preserves speed without creating coordination cost. Record why one worker or several workers is correct.

From Go7hic/ystack, MIT.

More from Go7hic/ystack