AI Agent Workflow Collection

How to backfill a newly-added repo or team — the enumerate-then-drain loop, the single-event contract, and resume-safe todo discipline. Load this when handling a .added seed event with the planner on.

Cookbook for composing an applygraphmutations plan — stable entitykey patterns, the canonical label/edge vocabulary, evidence/invalidation/confidence discipline, and a worked example. Load this when building a non-trivial mutation plan.

Use when an agent needs recent or historical change context: what changed recently, regressions, merged PRs, tickets, docs, incidents, deployments, releases, and source-history ingestion.

Use when the task involves running, explaining, or troubleshooting the Potpie CLI. Covers doctor, login, pot management, search, and ingest commands.

Use when the Potpie CLI is failing — especially around API key, URL config, 401, 404, pot scope, or search/ingest HTTP errors.

Use when an agent needs project context from the context engine through MCP tools. Covers contextresolve recipes for feature, debugging, review, operations, docs, and onboarding without adding separate context tools.

Use while debugging or troubleshooting failures, flaky tests, incidents, production alerts, CI failures, local dev setup issues, repeated bugs, prior fixes, failed attempts, and verification history.

Use when the task can read or write the project-memory graph through the potpie CLI: discover the contract with graph catalog, read named views with graph read, resolve entity identity with graph search-entities, create validated plans with graph propose, commit plans with graph commit --verify, inspect quality with graph quality, or capture uncertain work with graph inbox. Also covers writing retrieval-grade descriptions and responding to nudges. Prefer this over the MCP context tools whenever the shell is available.

Use for project infra and architecture context: environments, adapters, runtime configuration, deployments, service dependencies, datastores, API contracts, ownership, incidents, and dependency blast radius.

Use when the task is about pot resolution: pot use, env maps, git origin parsing, repo-to-pot mapping, or search/ingest scope inference.

Use before writing, modifying, reviewing, refactoring, or testing code so repo/project preferences surface: error handling, file structure, frameworks, logging, dependency choices, testing, security, API style, and naming. Also use after code work when a reusable project preference should be recorded.

Use when establishing, refreshing, or deeply understanding a repository's baseline memory in Potpie: purpose, application type, features, services/modules, environments, deploy shape, dependencies, API contracts, datastores, integrations, ownership, and explicit preferences. The harness reads authored and code-adjacent sources, then writes graph workbench mutations.

Use when the user explicitly asks to ingest, refresh, or deeply understand a repository, PR, issue, ticket, runbook, incident report, document, or web link into Potpie. The harness performs todo-driven discovery, uses local/GitHub/integration tools and read-only subagents when available, builds evidence-backed semantic mutations, and writes through graph propose/verified commit.

How to use the cloned-repo sandbox tools and recover from their failure modes (clone-in-progress, unknown ref, truncation, ambiguous/unknown repo, transient unavailability). Load this when a sandbox tool errors or returns an unexpected shape.