poteto-kit

“When you don’t have much trust in your agents,
… you really can’t get the most out of them.”

— Lauren Tan, a.k.a. poteto

_{An unofficial community kit that distills Lauren Tan’s (poteto) public talks and posts. Not affiliated with or endorsed by her.}

Recipes for trusting your coding agents: verification, skills, and agent-friendly architecture — baked and ready to serve.

The bottleneck with coding agents isn't how fast they write code. It's how much you trust what they hand back. Until you can trust it, you are the verifier, and no amount of parallel agents will save you from that.

poteto-kit is a reusable kit for developers, in three parts: docs (docs/) that explain each idea and why it works; templates (templates/) to copy into your repo; and a runnable example (example/) that proves the templates work. Template bodies are written for agents to read.

Start here

Paste one line into Claude Code, Cursor or Codex, inside your repo:

Read https://github.com/EPISTEX0/poteto-kit/blob/main/ADOPT.md and adopt poteto-kit into this repo.

Your agent follows ADOPT.md: it adopts the kit one phase at a time on a new branch, shows proof at the end of each phase, and asks you before it continues, commits or changes CI. Not sure what you need? Start from your pain:

Prefer to do it yourself? Keep reading: the pillars below and the Quick start are written for humans.

The three pillars

One question runs through everything: how do you come to trust your agents? Three pillars answer it. Every doc and template is filed under one of them; docs 01 (the trust curve) and 08 (scaling) span all three.

Pillar 1 - Verification

The agent runs the real application itself and brings back evidence. Without that, you are the verifier and the bottleneck.

• Docs: 02 - verification (anatomy of a control skill: a CLI with --help and tests, doctor, worktree isolation, refuse instead of fall back), 03 - feature map (the feature map directory, proof rules, and skip reporting), 05 - evals (verifying the verification skill itself), 09 - other stacks (the verify driver for iOS, Android, Flutter, React Native, backend APIs and CLIs).
• Templates: templates/skills/verify-app/SKILL.md, templates/skills/verify-app/references/cli-contract.md, templates/skills/verify-app/references/launch-by-app-type.md, templates/skills/verify-app/references/features/README.md, templates/skills/verify-app/references/features/_feature.template.md, templates/skills/verify-app/references/features/cross-cutting-flows.md, templates/skills/verify-app/references/worktree-isolation.md, templates/skills/verify-app/references/cloud-environment.md, templates/skills/create-verification/SKILL.md, templates/skills/maintain-verification/SKILL.md, templates/ci/check-feature-map.sh, templates/ci/check-coverage.mjs.

Pillar 2 - High-quality skills that teach agents to work like real engineers

Skills (markdown) are born from observed failure modes, organized as mode skills, leaf skills, and one-file principles, and evaluated like unit tests.

• Docs: 04 - skills from failures (mode/router skills, principles, a catalog by owner/area), 05 - evals.
• Templates: templates/skills/team-mode/SKILL.md, templates/skills/team-mode/principles/_principle.template.md, templates/skills/are-you-sure-you-need-x/SKILL.md, templates/skills/CATALOG.md, templates/skills/_skill-from-failure.md, templates/skills/investigate/SKILL.md, templates/evals/EVAL_PLAYBOOK.md, templates/evals/rubric.template.md, templates/evals/judge-prompt.md, templates/evals/scoreboard.template.md.

Pillar 3 - Agent-friendly architecture (greenfield vs brownfield)

Agents do reasonably well in brownfield codebases that already have guardrails. Greenfield vibe-coding is the biggest risk, and also the biggest opportunity. Make the change that is obvious locally the change that is correct globally, and push rules into the hard layers (red CI).

• Docs: 06 - guardrail layers (five layers: 1-2 hard, 3-5 soft), 07 - agent-friendly architecture (the architecture contract, five behaviors, five rules, five nouns), 08 - scaling (cloud agents, automation, ticks, auto-merge), 09 - other stacks (boundary, banned-API and comment-policy tools per language).
• Templates: templates/guardrails/architecture-contract.md, templates/guardrails/enforcement-layers.md, templates/guardrails/review-comment-to-rule.md, templates/guardrails/AGENTS.md.template, templates/ci/ci.yml, templates/ci/check-feature-map.sh, templates/ci/check-coverage.mjs, templates/automation/goal-ticks.md, templates/automation/bug-repro.md, templates/automation/automerge-policy.md.

Quick start

1. Copy the three verification skills into .agents/skills/ in your repo, flat: templates/skills/verify-app/ (the whole directory, including references/), templates/skills/create-verification/ and templates/skills/maintain-verification/. Also copy templates/ci/check-feature-map.sh to scripts/check-feature-map.sh: create-verification runs maintain-verification's check script when it finishes. Then make your tool see the skills (next section). This manual route copies the full set up front; ADOPT.md installs less (no check-feature-map.sh, no cloud reference) and adds the rest in later phases.

2. Fill the placeholders. Find every one with grep -rn "{{" .agents/skills --exclude=_feature.template.md, replace it, and delete each HOW TO USE comment block. _feature.template.md keeps its placeholders on purpose: it stays in references/features/ as the copy source for new feature files. Step 3 fills cross-cutting-flows.md; run the grep again after it. templates/README.md explains the placeholders and the order of adoption.

3. Let the agent draft your feature map. Tell it: "use the create-verification skill for this repo". Review what it generates, because you know what your users really do.

4. Add the guardrails. Copy templates/guardrails/AGENTS.md.template to AGENTS.md, templates/ci/ci.yml to .github/workflows/ci.yml (fill in {{WORKING_DIR}}, {{GATE_COMMAND}} and the other placeholders at the top of the file), and templates/ci/check-feature-map.sh and templates/ci/check-coverage.mjs into scripts/, then call both from your gate command. Fill in templates/guardrails/enforcement-layers.md to see which rules are still soft.

5. Then grow. For each failure that recurs, or that several agents make, try the correction ladder first. Use templates/skills/_skill-from-failure.md for what is left, and templates/evals/EVAL_PLAYBOOK.md to measure your skills. Not a TypeScript web app? docs/09-other-stacks.md maps each mechanism to tools for your stack.

6. Run the example to watch the gate go red on a violation and verify catch a planted bug:

   cd example && npm ci && npm run gate
   

   The gate includes a self-test that plants a bug in the build and proves that verify goes red on it. It needs Node.js ^22.13.0 || ^24 || >=26 and a Chromium on the machine; details in example/README.md.

Install skills in your tool

• Canonical location: .agents/skills/<name>/SKILL.md, flat. Do not nest skills in grouping folders; put the owner or area in the skill name instead.

• Cursor and Codex read .agents/skills directly. Nothing to do.

• Claude Code reads .claude/skills. Point it at the same directory from the repo root:

  mkdir -p .claude && ln -s ../.agents/skills .claude/skills
  

• AGENTS.md is read by Cursor and Codex. Claude Code reads it only when there is no CLAUDE.md; otherwise add the line @AGENTS.md to CLAUDE.md.

• Keeping a skill manual-only: disable-model-invocation: true in the SKILL.md frontmatter is honoured by Claude Code and Cursor. Codex uses policy.allow_implicit_invocation: false in the skill's agents/openai.yaml instead. Don't rely on other tool-specific frontmatter keys; the name and description are what every tool needs.

Idea → Doc → Template

Adoption path by trust stage

The six stages below are a frame for measuring where you are; tune the "move on when ..." thresholds to fit your team. Don't skip stages: spawning cloud agents in bulk while you are still at the start of the curve only burns tokens.

Repo layout

poteto-kit/
├── README.md                 entry point (this file)
├── ADOPT.md                  playbook your coding agent runs to adopt the kit step by step
├── LICENSE                   MIT
├── assets/                   icon (poteto.png 512px, 128/32px sizes, original artwork)
├── .github/workflows/
│   └── example.yml           this repo's own CI: runs the example's gate
├── docs/                     guides
│   ├── 01-trust-curve.md
│   ├── 02-verification.md
│   ├── 03-feature-map.md
│   ├── 04-skills-from-failures.md
│   ├── 05-evals.md
│   ├── 06-guardrail-layers.md
│   ├── 07-agent-first-architecture.md
│   ├── 08-scaling-to-cloud-agents.md
│   ├── 09-other-stacks.md
│   └── glossary.md
├── templates/                copy into your repo (see templates/README.md)
│   ├── README.md
│   ├── skills/               verify-app (with references/, including cloud-environment.md),
│   │                         create-/maintain-verification, team-mode (with principles/),
│   │                         are-you-sure-you-need-x, investigate,
│   │                         CATALOG.md, _skill-from-failure.md
│   ├── evals/                EVAL_PLAYBOOK, rubric, judge-prompt, scoreboard
│   ├── guardrails/           AGENTS.md.template, enforcement-layers,
│   │                         architecture-contract, review-comment-to-rule
│   ├── automation/           goal-ticks.md, bug-repro.md, automerge-policy.md
│   └── ci/                   ci.yml, check-feature-map.sh, check-coverage.mjs
└── example/                  runnable TypeScript example (see example/README.md)
    ├── src/                  features/, framework/, client/, electron/
    ├── .agents/skills/       verify-app and a filled-in feature map
    ├── scripts/              verify CLI, check-features, guardrail tests
    └── guardrail-fixtures/   sample violations that prove the rules fire

License

MIT.