{"owner":"potpie-ai","repo":"potpie","hasSkills":true,"totalSkillsCount":16,"totalTokensCount":9280,"categories":["anthropic-skill","command-prompt","marketplace","plugin-manifest"],"hasMcp":false,"mcpConfig":null,"found":["potpie/cli/templates/agent_bundle/.agents/skills/potpie-source-ingestion/SKILL.md","potpie/cli/templates/agent_bundle/.agents/skills/potpie-infra-architecture/SKILL.md","potpie/cli/templates/agent_bundle/.agents/skills/potpie-graph/SKILL.md","potpie/cli/templates/agent_bundle/.agents/skills/potpie-debug-memory/SKILL.md","potpie/cli/templates/agent_bundle/.agents/skills/potpie-cli/SKILL.md","potpie/cli/templates/agent_bundle/.agents/skills/potpie-change-timeline/SKILL.md","potpie/context-engine/src/potpie_context_engine/adapters/outbound/reconciliation/skills/graph-mutation-plan/SKILL.md","potpie/context-engine/src/potpie_context_engine/adapters/outbound/reconciliation/skills/backfill-enumerate-drain/SKILL.md","potpie/cli/templates/claude_plugin/commands/potpie-feature.md","potpie/cli/templates/claude_plugin/commands/potpie-record.md","potpie/cli/templates/claude_plugin/.claude-plugin/marketplace.json","potpie/cli/templates/claude_plugin/.claude-plugin/plugin.json","potpie/cli/templates/claude_bundle/.claude/commands/potpie-feature.md","potpie/cli/templates/claude_bundle/.claude/commands/potpie-record.md","potpie/cli/templates/agent_bundle/.agents/skills/potpie-graph/agents/openai.yaml","potpie/cli/templates/agent_bundle/.agents/skills/potpie-cli/agents/openai.yaml"],"skills":{"potpie/cli/templates/agent_bundle/.agents/skills/potpie-source-ingestion/SKILL.md":"---\nname: potpie-source-ingestion\nversion: \"5\"\ndescription: \"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. Document payloads (PDF, spreadsheet, markdown/HTML) route through the per-format potpie-resource-* skills and `potpie resource import`.\"\n---\n\n# Potpie Source Ingestion\n\nUse this skill for explicit ingestion requests. The harness is the intelligence:\nit gathers source data, reads it, decides what is durable, resolves identity, and\nwrites semantic graph mutations with evidence. Potpie validates and stores; it\ndoes not decide what source material means.\n\n## Non-Negotiables\n\n- Use a todo/checklist for every repository or multi-source ingestion. Do not\n jump directly from a README to graph writes.\n- Local inspection is required for repo understanding. Scanner-driven graph\n updates are forbidden. Inspect files with `rg`, `rg --files`, `git`, and\n structured tooling; do not run legacy or deterministic ingestion/scanner\n commands that walk the tree and write graph facts.\n- Use subagents only for read-only discovery slices. The main agent owns source\n selection, identity resolution, mutation proposals, commits, and final\n synthesis.\n- Do not write until each required discovery lane is complete, explicitly\n unavailable, or intentionally scoped out by the user.\n- Every write needs source refs, source authority, truth class, confidence,\n compact summary, and retrieval-grade description.\n\n## Phase 0: Scope And Preflight\n\n1. Define source kind, pot/project, repo/path/URL, time window, and target memory\n shape: baseline, history, docs, infra, debug memory, preferences, or all.\n2. Verify Potpie scope and graph availability with one call:\n\n```bash\npotpie status\n```\n\nIt reports the daemon, the active pot, backend readiness and claim counts;\nevery later read names the pot it used in its header, so do not pre-read\n`pot info`, `source list` or `graph status`. Pass `--pot ` on later\ncalls once the pot is known.\n\n3. If the repo is not registered, register metadata only. Use explicit `--pot`\n when pot scope is ambiguous:\n\n```bash\npotpie source add repo . --pot \n```\n\n4. Inspect the full destination ontology before selecting mutation shapes:\n\n```bash\npotpie --json graph catalog --profile full --pot \n```\n\nRead the [ontology selection guidance](../potpie-graph/SKILL.md#ontology-selection)\nto distinguish facts, decisions, policies, events, and source material. Reuse\nthis catalog during the task; `--profile read` omits the ontology. Select from\nall supported entities and predicates, then use templates for payload shape.\nThe templates are examples, not an exhaustive list of relationships.\n`graph describe --examples` carries read examples only.\n\n```bash\npotpie graph mutation-template --kind repo-baseline\npotpie graph mutation-template --kind infra-snapshot\npotpie graph mutation-template --kind timeline-change\npotpie graph mutation-template --kind preference-policy\npotpie graph mutation-template --kind bug-fix\n```\n\n5. If the CLI is unavailable or broken, continue discovery, build the proposed\n evidence matrix, and stop before committing graph writes.\n\n## Phase 1: Todo Plan\n\nCreate and maintain todos with at least these lanes for repository ingestion:\n\n- Scope, pot, source registration, and graph contract preflight.\n- Product/docs: README, docs, ADRs, runbooks, public docs, linked websites.\n- Local repo map: manifests, packages/apps, entrypoints, route/API surfaces,\n tests, framework config, major modules, generated/API specs.\n- Runtime/deploy: Dockerfiles, compose, Kubernetes, Terraform, CI workflows,\n deploy scripts, environment templates, feature flags.\n- API/data/integrations: service clients, adapters, datastores, models,\n queues, auth providers, external APIs.\n- GitHub/history: repo metadata, topics, releases/tags, recent merged PRs, open\n issues, linked tickets/docs, CI/deploy records.\n- Preferences/workflows: explicit coding style, test commands, local dev setup,\n release/deploy/runbook workflows.\n- Synthesis: evidence matrix, candidate graph facts, identity resolution,\n proposal, verified commit, and gate-driven follow-up checks.\n\nUpdate todos as lanes finish. Preserve uncertain findings for the inbox instead\nof forcing them into canonical graph claims.\n\n## Phase 2: Parallel Discovery\n\nParallelize independent read-only slices when tools allow it. Recommended\nsubagent prompts:\n\n- Docs/product: \"Read README, docs, ADRs, runbooks, package metadata, and linked\n product pages. Return product purpose, features, explicit decisions,\n preferences, workflows, and source refs. Do not write mutations.\"\n- Local architecture: \"Inspect manifests, top-level apps/packages, entrypoints,\n route/API surfaces, tests, and framework config. Return service/module map,\n likely features, explicit source files, uncertainty, and no mutations.\"\n- Runtime/deploy: \"Inspect Docker/compose/Kubernetes/Terraform/CI/deploy/env\n templates. Return environments, deploy shape, config variables, workflows,\n datastores, and source refs. Do not write mutations.\"\n- API/data/integrations: \"Inspect route specs, client/adapters, models,\n datastores, queues, auth, and external integrations. Return candidate\n APIContract/DataStore/Adapter/Dependency facts with evidence. No mutations.\"\n- GitHub history: \"Use GitHub tools/CLI for repo metadata, releases, recent\n merged PRs, open issues, linked tickets/docs, and CI signal. Return timeline,\n fixes, decisions, bug patterns, and source refs. No mutations.\"\n- Preferences: \"Find explicit preferences in docs, config, tests, contribution\n guides, PR templates, and comments. Return only explicit reusable policies\n with evidence. No mutations.\"\n\nThe main agent should continue non-overlapping discovery while subagents run.\n\n## Phase 3: Local Repo Inspection Targets\n\nUse structured, bounded local inspection. Examples:\n\n```bash\nrg --files -g 'README*' -g 'docs/**' -g '*ADR*' -g 'package.json' -g 'pyproject.toml' -g 'Cargo.toml' -g 'go.mod'\nrg --files -g 'Dockerfile*' -g 'docker-compose*' -g '.github/workflows/**' -g '*.tf' -g 'k8s/**' -g '.env*'\nrg -n \"FastAPI|APIRouter|express\\\\(|router\\\\.|Django|Flask|NextResponse|route\\\\(\" .\nrg -n \"postgres|mysql|redis|mongo|s3|kafka|rabbit|queue|oauth|stripe|slack|github|linear|jira\" .\nrg -n \"pytest|vitest|jest|playwright|make test|npm test|uv run|cargo test\" README* docs .github pyproject.toml package.json Makefile\n```\n\nDo not infer durable facts from filenames alone. Use files to locate sources of\ntruth, then read the relevant snippets or authored docs.\n\n## Phase 4: Hosted/GitHub Hydration\n\nUse the agent's integration tools/connectors, including GitHub app/MCP/CLI\ntools when available, not Potpie queue ingestion commands. For GitHub-backed\nrepo ingestion, gather the items below. Do not use Potpie CLI queue ingestion.\n\n- Repository metadata: full name, default branch, description, topics,\n visibility, homepage, license, archived/fork status.\n- Documentation: README, contributing guide, CODEOWNERS, PR/issue templates,\n docs linked from the repo.\n- Releases/tags when they describe shipped behavior or deploy cadence.\n- Recent merged PRs: title, body, author, merged date, branch, labels, linked\n issues, changed filenames; fetch patches only when author text is insufficient.\n- Open/high-signal issues: title, body, labels, state, author, comments when\n available; issues can record requests/bugs but do not prove fixes.\n- CI/workflows: workflow files and failed/passing runs only when relevant to\n durable workflows, release process, or recurring failures.\n- Linked systems: Linear/Jira/Confluence/Slack/docs mentioned in repo, PRs, or\n issues when corresponding tools are available.\n\nRespect API limits and user scope. Prefer recent/high-signal items over\nexhaustive pagination unless the user explicitly asks for full history.\n\n## Phase 5: Evidence Matrix\n\nBefore writing, build a compact matrix:\n\n| Candidate | Entity types + predicate + direction | Source refs | Authority | Truth class | Confidence | Action |\n|---|---|---|---|---|---|---|\n| Worker uses Redis | Service → USES → DataStore | file/doc locator | authoritative_code | authoritative_fact | 0.95 | commit / inbox / skip |\n\nSelect type/predicate from the inspected catalog and record the intended read\nthat should retrieve the fact. Classify meaning independently of authority:\na source-backed behavior is not a preference, and `feature_note` is not a\nsubstitute for a `Feature` with its supported relations.\n\nGuidelines:\n\n- Use `authoritative_fact` for explicit docs/config/code ownership facts.\n- Use `source_observation` for observed source material that may not be policy.\n- Use `agent_claim` for lower-authority synthesis from multiple weak signals.\n- Use `preference` only for explicit reusable project preferences.\n- Use `timeline_event` for source-time activity from PRs, tickets, releases, or\n deployments.\n- Put uncertain but potentially useful findings into `graph inbox add`.\n\n## Phase 6: Identity Resolution\n\nResolve before linking — one untyped search per entity you intend to link and\nhave not already seen in a read (a wrong `--type` guess returns nothing);\nnarrow by `--source-ref` for tickets and PRs:\n\n```bash\npotpie graph search-entities \"\" --limit 10\npotpie graph search-entities \"\" --source-ref --limit 10\n```\n\nReuse canonical keys. If duplicate candidates appear, stop and use inbox or a\nreview-required correction flow; do not create near-duplicate entities.\n\n## Phase 7: Write\n\nAuthor semantic mutation JSON from the `graph mutation-template` skeletons\nprinted in Phase 0; `propose` validates against the live contract and names\nevery rejected operation by index. Omit `graph_contract_version` from the\npayload. Use the full catalog inspected in Phase 0 for relationships absent\nfrom the templates. Refresh it if the destination or contract changes.\n\n```bash\npotpie --json graph propose --file mutation.json\n```\n\nInspect proposal status, diff, warnings, rejected operations, conflicts, and\nreview flags:\n\n- `invalid` or rejected operations: fix the mutation or skip the weak fact.\n- `conflict` or duplicate risk: resolve identity or use inbox.\n- `review_required`: ask for approval, then re-run\n `potpie --json graph propose --file mutation.json --approved-by `\n and commit with `--verify`, or commit the plan you have with\n `potpie --json graph commit --approved-by --verify`;\n `commit` without an approval answers `review_required` again.\n- `validated` / low-risk: commit with `--verify`.\n\n```bash\npotpie --json graph commit --verify\n```\n\n`commit --verify` prints the plan id, readback and quality status;\n`graph history --plan ` is for later inspection.\n\nFor large batches of agent-authored mutations, use `graph bulk apply` with\ndry-run, chunking, manifest, and verify. Bulk apply must only apply facts the\nharness already selected.\n\n## Phase 8: Verify And Quality Gate\n\n`graph commit --verify` reads back committed claims and checks quality. When it\nwarns or fails, drill down with affected reads and quality reports:\n\n```bash\npotpie graph read --subgraph features --view feature_context --scope anchor_entity_key: --limit 50\npotpie graph read --subgraph infra_topology --view service_neighborhood --scope service: --depth 2 --direction both --limit 50\npotpie graph read --subgraph recent_changes --view timeline --scope repo: --limit 50 --format table\npotpie --json graph quality duplicate-candidates --limit 20\npotpie --json graph quality low-confidence --limit 20\npotpie --json graph quality conflicting-claims --limit 20\npotpie --json graph quality orphan-entities --limit 20\n```\n\nVerify the selected representation as well as persistence: read each affected\nfamily and confirm the intended typed relationships and evidence. A valid plan\nor passing quality report cannot establish that factual prose belongs under\n`POLICY_APPLIES_TO`. If a fact is stored but absent from its intended read,\ninspect its type, relation, and scope before adding another claim.\nIf the verified commit misses expected facts, fix the mutation or record an inbox item.\nReport what was ingested, what was skipped, and what remains uncertain.\n\nReport it with the commands, not as prose alone: the `propose` and\n`commit --verify` you ran, the `plan_id` they returned, and the verify outcome.\nAn ingestion the reader cannot re-open with `graph history --plan ` is\none they have to take on trust, and the whole point of the verified gate is that\nthey do not have to. Name the reads that came back empty as well — they are why\na slice of the evidence matrix stayed thin.\n\nWhen the ingested source described a topology — a service map, a deploy shape, a\nset of dependencies — draw what you wrote as a mermaid ` ```mermaid ` /\n`flowchart LR` block, using the same entity keys and predicates that went into\nthe mutation, so the picture and the graph can be compared line by line. Nothing else here is a shape: counts, skipped\nsources, and open questions belong in a list.\n\n## Repository Baseline\n\nFor repository ingestion, run baseline before change history. Use\n`potpie-repo-baseline` in deep mode when the user asks to ingest or understand a\nrepo deeply. Record source-backed purpose, application type, features,\nservice/module map, API contracts, datastores, integrations, environments,\ndeploy shape, ownership, and explicit project preferences. Then use\n`potpie-change-timeline` for recent or historical activity. Do not infer\nbaseline architecture from PR titles or issue status.\n\nRepresent capabilities as `Feature` entities. Link repositories or services to\nfeatures with `PROVIDES`, and use `IMPLEMENTED_IN` only when a source locates\nthe implementation.\n\n## Document Payloads\n\nWhen a source is a document whose *content* must stay searchable and citable —\na PDF, a spreadsheet, a long markdown/HTML doc, an exported wiki page — do not\npaste its body into summaries, descriptions, or claims. Payloads never enter\nthe graph. Use the matching per-format skill (`potpie-resource-pdf`,\n`potpie-resource-spreadsheet`, `potpie-resource-markdown`): you write an\nextraction script, the script emits a chunk directory, and\n`potpie resource import` stores the bytes and writes the Document/section\nstructure to the graph. Agent-authored section summaries index each section\nfor graph context, and the resource index searches the chunk text. Then link\ncoverage with `DOCUMENTS` claims, and for structured data derive the durable\nfacts as ordinary claims citing `potpie://res/...` chunk ids as evidence. Facts\na document *states* (decisions, preferences, infra) are still recorded as\nnormal graph claims under the rules below — the resource store holds the\nevidence payload, not the conclusions.\n\nA document is not a registrable source: `source add` refuses a document kind\nwith `source_kind_is_a_document`. When only a pointer is wanted and the text\nneed not be searchable, a `doc_reference` record whose summary says what the\ndocument covers is enough.\n\n## Source Rules\n\n- Tickets and issues can record timeline events, bug patterns, decisions, and\n docs. They do not prove a fix unless tied to a merged PR, commit, deployment,\n or explicit shipped-resolution source.\n- Documents can record preferences, decisions, runbook notes, service notes, and\n infra facts only when they explicitly say them. Their payloads belong in the\n resource store (see Document Payloads above), never in graph properties.\n- Logs and transcripts can record diagnostic signals, investigations, fixes, and\n verifications. Keep raw logs out of descriptions except for short distinctive\n error text.\n\n## Protocol definitions and codecs\n\nWhen the source or question concerns telegrams, message layouts, field/value\nmeanings, revisions or decoder changes, check the catalog for\n`protocols.message_context` and, when it is advertised, follow\n[the shared protocol reference](../potpie-graph/references/protocols.md). The\nextension is opt-in (`potpie config set graph.protocols on`), so a catalog\nwithout it means protocol memory is off. Use explicit protocol reads alongside\nexisting Service/CodeAsset context. Preserve immutable source evidence and\npartial coverage; capabilities do not establish traffic.\n","potpie/cli/templates/agent_bundle/.agents/skills/potpie-infra-architecture/SKILL.md":"---\nname: potpie-infra-architecture\nversion: \"5\"\ndescription: \"Use for project infra and architecture context: environments, adapters, runtime configuration, deployments, service dependencies, datastores, API contracts, ownership, incidents, and dependency blast radius.\"\n---\n\n# Potpie Infra Architecture\n\nUse this skill when the task touches environments, adapters, deployment behavior,\nruntime config, service dependencies, production incidents, or architecture\nchanges.\n\n## Fast Path\n\nShare one discovery pass with other skills; reuse current reads and hook context\nfor the same task, pot, and scope. Run broad resolve and an untyped entity lookup\nconcurrently when the task names a service, environment, adapter, or dependency\nwhose canonical key is unknown. Skip the lookup when a key is already known.\nFor code changes, scoped preferences can run alongside both. Use a known\nexplicit pot selector; resolve ambiguous routing before scoped retrieval and\ncheck returned pot IDs before combining results.\n\nBroad context and conditional identity lookup:\n\n```bash\npotpie resolve \"\"\npotpie graph search-entities \"\" --limit 10\n```\n\nUse the returned canonical service key for a neighborhood when the task needs\nrelationships or resolve leaves a gap; do not guess an anchor. For a direct\nentity question, identity lookup then neighborhood can suffice without resolve.\nThe `service:` below stands for that returned key. Start with\n**no `--environment`**:\n\n```bash\npotpie graph read --subgraph infra_topology --view service_neighborhood --scope service: --depth 2 --direction both --limit 20\n```\n\nThe environment filter defaults to `qualified_only`: `--environment prod`\nalone drops every unqualified edge — `USES`, `DEFINED_IN`, `OWNED_BY` — and\nanswers \"talks to nothing\". To exclude other environments, keep them explicitly:\n\n```bash\npotpie graph read --subgraph infra_topology --view service_neighborhood --scope service:,include_unqualified_environment:true --environment --depth 2 --direction both --limit 20\n```\n\nAn empty neighborhood can mean missing relations, not a wrong key. Start with\n`--depth 2 --direction both`; `--direction` accepts `out`, `in` or `both`, and\nany other spelling is refused. A `--depth` past the view's maximum runs at the\nmaximum and says so. Alternatively, for\neverything the graph holds about one service — decisions, preferences, timeline\nand features beside the topology — use one flat list:\n\n```bash\npotpie graph neighborhood --entity service: --detail summary --limit 20\n```\n\nChoose the neighborhood that answers the question; do not automatically run\nboth. Fetch already-discovered document chunks with `potpie resource get`\nconcurrently with neighborhood reads, and stop expanding once the required\nevidence is covered. Pass `--pot ` once the pot is known.\n\n## Apply Results\n\nUse infra context for blast radius, where-to-look decisions, deployment changes,\nadapter selection, and incident debugging. Preserve environment qualifiers; a\nstaging dependency is not proof of a production dependency.\n\nLook for explicit topology facts: `DEFINED_IN`, `DEPLOYED_TO`, `DEPENDS_ON`,\n`USES`, `EXPOSES`, `HOSTED_ON`, and `OWNED_BY`.\n\n## Report Back\n\nShow the `graph read` you ran, including the `--depth`, `--limit`, and any\n`--environment` you chose. A neighborhood is only interpretable next to its\nbounds: \"nothing depends on it\" means one thing at `--depth 2` and another at\n`--depth 1`, and the reader cannot tell which you meant unless the command is on\nthe page.\n\nA neighborhood is the case a diagram was made for — draw it:\n\n```mermaid\nflowchart LR\n payments[\"payments-api (prod)\"] -->|DEPENDS_ON| ledger[\"ledger-api (prod)\"]\n payments -->|USES| pgdb[(\"payments-db\")]\n ledger -.->|USES, inferred| cache[(\"redis\")]\n```\n\nKeep the environment qualifier on the node, label every edge with its predicate,\nand dash any edge you inferred rather than read — a solid edge asserts the graph\nsays so. Blast radius is the same picture with the direction reversed. Do not\ndraw one dependency; say it in a sentence.\n\n## Record Architecture\n\nRecord only source-backed topology or carefully labeled agent inferences. Use\n`authoritative_fact` when evidence is an explicit source of truth such as\ndeployment config, service manifest, infra doc, ADR, or user statement. Use\n`agent_claim` for lower-authority interpretation.\n\nTopology edges are not a `potpie record` type; write them as a plan:\n\n```bash\npotpie graph mutation-template --kind infra-snapshot\npotpie --json graph propose --file mutation.json\npotpie --json graph commit --verify\n```\n\nReuse the keys your reads returned. Omit `graph_contract_version` from the\npayload. If `propose` answers `review_required`, ask the user, then re-run it\nwith `--approved-by ` and commit as above (or pass `--approved-by` to\nthe commit); `commit --verify` prints the plan id, readback and quality status.\n\nA decision *about* the architecture is one call:\n\n```bash\npotpie record --type decision --summary \"\" --detail rationale=\"\" --scope service:\n```\n\nEvery durable infra fact needs an environment when the fact differs by\nenvironment, evidence when available, and a retrieval-grade description.\n\nArchitecture capture is harness-led: inspect authoritative sources and write\nsemantic facts. Do not use scanner-driven graph updates or infer topology from\ndirectory names, imports, or package files alone.\n\n## Protocol definitions and codecs\n\nWhen the source or question concerns telegrams, message layouts, field/value\nmeanings, revisions or decoder changes, check the catalog for\n`protocols.message_context` and, when it is advertised, follow\n[the shared protocol reference](../potpie-graph/references/protocols.md). The\nextension is opt-in (`potpie config set graph.protocols on`), so a catalog\nwithout it means protocol memory is off. Use explicit protocol reads alongside\nexisting Service/CodeAsset context. Preserve immutable source evidence and\npartial coverage; capabilities do not establish traffic.\n","potpie/cli/templates/agent_bundle/.agents/skills/potpie-graph/SKILL.md":"# potpie-graph\n\nPath: `potpie/cli/templates/agent_bundle/.agents/skills/potpie-graph/SKILL.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/potpie-ai/potpie/HEAD/potpie/cli/templates/agent_bundle/.agents/skills/potpie-graph/SKILL.md)","potpie/cli/templates/agent_bundle/.agents/skills/potpie-debug-memory/SKILL.md":"# potpie-debug-memory\n\nPath: `potpie/cli/templates/agent_bundle/.agents/skills/potpie-debug-memory/SKILL.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/potpie-ai/potpie/HEAD/potpie/cli/templates/agent_bundle/.agents/skills/potpie-debug-memory/SKILL.md)","potpie/cli/templates/agent_bundle/.agents/skills/potpie-cli/SKILL.md":"# potpie-cli\n\nPath: `potpie/cli/templates/agent_bundle/.agents/skills/potpie-cli/SKILL.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/potpie-ai/potpie/HEAD/potpie/cli/templates/agent_bundle/.agents/skills/potpie-cli/SKILL.md)","potpie/cli/templates/agent_bundle/.agents/skills/potpie-change-timeline/SKILL.md":"# potpie-change-timeline\n\nPath: `potpie/cli/templates/agent_bundle/.agents/skills/potpie-change-timeline/SKILL.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/potpie-ai/potpie/HEAD/potpie/cli/templates/agent_bundle/.agents/skills/potpie-change-timeline/SKILL.md)","potpie/context-engine/src/potpie_context_engine/adapters/outbound/reconciliation/skills/graph-mutation-plan/SKILL.md":"# graph-mutation-plan\n\nPath: `potpie/context-engine/src/potpie_context_engine/adapters/outbound/reconciliation/skills/graph-mutation-plan/SKILL.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/potpie-ai/potpie/HEAD/potpie/context-engine/src/potpie_context_engine/adapters/outbound/reconciliation/skills/graph-mutation-plan/SKILL.md)","potpie/context-engine/src/potpie_context_engine/adapters/outbound/reconciliation/skills/backfill-enumerate-drain/SKILL.md":"# backfill-enumerate-drain\n\nPath: `potpie/context-engine/src/potpie_context_engine/adapters/outbound/reconciliation/skills/backfill-enumerate-drain/SKILL.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/potpie-ai/potpie/HEAD/potpie/context-engine/src/potpie_context_engine/adapters/outbound/reconciliation/skills/backfill-enumerate-drain/SKILL.md)","potpie/cli/templates/claude_plugin/commands/potpie-feature.md":"# Command: /potpie-feature\n\nPath: `potpie/cli/templates/claude_plugin/commands/potpie-feature.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/potpie-ai/potpie/HEAD/potpie/cli/templates/claude_plugin/commands/potpie-feature.md)","potpie/cli/templates/claude_plugin/commands/potpie-record.md":"# Command: /potpie-record\n\nPath: `potpie/cli/templates/claude_plugin/commands/potpie-record.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/potpie-ai/potpie/HEAD/potpie/cli/templates/claude_plugin/commands/potpie-record.md)","potpie/cli/templates/claude_plugin/.claude-plugin/marketplace.json":"# Claude Plugin Marketplace Catalog\n\nPath: `potpie/cli/templates/claude_plugin/.claude-plugin/marketplace.json`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/potpie-ai/potpie/HEAD/potpie/cli/templates/claude_plugin/.claude-plugin/marketplace.json)","potpie/cli/templates/claude_plugin/.claude-plugin/plugin.json":"# claude-plugin Plugin Manifest\n\nPath: `potpie/cli/templates/claude_plugin/.claude-plugin/plugin.json`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/potpie-ai/potpie/HEAD/potpie/cli/templates/claude_plugin/.claude-plugin/plugin.json)","potpie/cli/templates/claude_bundle/.claude/commands/potpie-feature.md":"# Command: /potpie-feature\n\nPath: `potpie/cli/templates/claude_bundle/.claude/commands/potpie-feature.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/potpie-ai/potpie/HEAD/potpie/cli/templates/claude_bundle/.claude/commands/potpie-feature.md)","potpie/cli/templates/claude_bundle/.claude/commands/potpie-record.md":"# Command: /potpie-record\n\nPath: `potpie/cli/templates/claude_bundle/.claude/commands/potpie-record.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/potpie-ai/potpie/HEAD/potpie/cli/templates/claude_bundle/.claude/commands/potpie-record.md)","potpie/cli/templates/agent_bundle/.agents/skills/potpie-graph/agents/openai.yaml":"# Agents Skill\n\nPath: `potpie/cli/templates/agent_bundle/.agents/skills/potpie-graph/agents/openai.yaml`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/potpie-ai/potpie/HEAD/potpie/cli/templates/agent_bundle/.agents/skills/potpie-graph/agents/openai.yaml)","potpie/cli/templates/agent_bundle/.agents/skills/potpie-cli/agents/openai.yaml":"# Agents Skill\n\nPath: `potpie/cli/templates/agent_bundle/.agents/skills/potpie-cli/agents/openai.yaml`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/potpie-ai/potpie/HEAD/potpie/cli/templates/agent_bundle/.agents/skills/potpie-cli/agents/openai.yaml)"},"files":{"potpie/cli/templates/agent_bundle/.agents/skills/potpie-source-ingestion/SKILL.md":"---\nname: potpie-source-ingestion\nversion: \"5\"\ndescription: \"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. Document payloads (PDF, spreadsheet, markdown/HTML) route through the per-format potpie-resource-* skills and `potpie resource import`.\"\n---\n\n# Potpie Source Ingestion\n\nUse this skill for explicit ingestion requests. The harness is the intelligence:\nit gathers source data, reads it, decides what is durable, resolves identity, and\nwrites semantic graph mutations with evidence. Potpie validates and stores; it\ndoes not decide what source material means.\n\n## Non-Negotiables\n\n- Use a todo/checklist for every repository or multi-source ingestion. Do not\n jump directly from a README to graph writes.\n- Local inspection is required for repo understanding. Scanner-driven graph\n updates are forbidden. Inspect files with `rg`, `rg --files`, `git`, and\n structured tooling; do not run legacy or deterministic ingestion/scanner\n commands that walk the tree and write graph facts.\n- Use subagents only for read-only discovery slices. The main agent owns source\n selection, identity resolution, mutation proposals, commits, and final\n synthesis.\n- Do not write until each required discovery lane is complete, explicitly\n unavailable, or intentionally scoped out by the user.\n- Every write needs source refs, source authority, truth class, confidence,\n compact summary, and retrieval-grade description.\n\n## Phase 0: Scope And Preflight\n\n1. Define source kind, pot/project, repo/path/URL, time window, and target memory\n shape: baseline, history, docs, infra, debug memory, preferences, or all.\n2. Verify Potpie scope and graph availability with one call:\n\n```bash\npotpie status\n```\n\nIt reports the daemon, the active pot, backend readiness and claim counts;\nevery later read names the pot it used in its header, so do not pre-read\n`pot info`, `source list` or `graph status`. Pass `--pot ` on later\ncalls once the pot is known.\n\n3. If the repo is not registered, register metadata only. Use explicit `--pot`\n when pot scope is ambiguous:\n\n```bash\npotpie source add repo . --pot \n```\n\n4. Inspect the full destination ontology before selecting mutation shapes:\n\n```bash\npotpie --json graph catalog --profile full --pot \n```\n\nRead the [ontology selection guidance](../potpie-graph/SKILL.md#ontology-selection)\nto distinguish facts, decisions, policies, events, and source material. Reuse\nthis catalog during the task; `--profile read` omits the ontology. Select from\nall supported entities and predicates, then use templates for payload shape.\nThe templates are examples, not an exhaustive list of relationships.\n`graph describe --examples` carries read examples only.\n\n```bash\npotpie graph mutation-template --kind repo-baseline\npotpie graph mutation-template --kind infra-snapshot\npotpie graph mutation-template --kind timeline-change\npotpie graph mutation-template --kind preference-policy\npotpie graph mutation-template --kind bug-fix\n```\n\n5. If the CLI is unavailable or broken, continue discovery, build the proposed\n evidence matrix, and stop before committing graph writes.\n\n## Phase 1: Todo Plan\n\nCreate and maintain todos with at least these lanes for repository ingestion:\n\n- Scope, pot, source registration, and graph contract preflight.\n- Product/docs: README, docs, ADRs, runbooks, public docs, linked websites.\n- Local repo map: manifests, packages/apps, entrypoints, route/API surfaces,\n tests, framework config, major modules, generated/API specs.\n- Runtime/deploy: Dockerfiles, compose, Kubernetes, Terraform, CI workflows,\n deploy scripts, environment templates, feature flags.\n- API/data/integrations: service clients, adapters, datastores, models,\n queues, auth providers, external APIs.\n- GitHub/history: repo metadata, topics, releases/tags, recent merged PRs, open\n issues, linked tickets/docs, CI/deploy records.\n- Preferences/workflows: explicit coding style, test commands, local dev setup,\n release/deploy/runbook workflows.\n- Synthesis: evidence matrix, candidate graph facts, identity resolution,\n proposal, verified commit, and gate-driven follow-up checks.\n\nUpdate todos as lanes finish. Preserve uncertain findings for the inbox instead\nof forcing them into canonical graph claims.\n\n## Phase 2: Parallel Discovery\n\nParallelize independent read-only slices when tools allow it. Recommended\nsubagent prompts:\n\n- Docs/product: \"Read README, docs, ADRs, runbooks, package metadata, and linked\n product pages. Return product purpose, features, explicit decisions,\n preferences, workflows, and source refs. Do not write mutations.\"\n- Local architecture: \"Inspect manifests, top-level apps/packages, entrypoints,\n route/API surfaces, tests, and framework config. Return service/module map,\n likely features, explicit source files, uncertainty, and no mutations.\"\n- Runtime/deploy: \"Inspect Docker/compose/Kubernetes/Terraform/CI/deploy/env\n templates. Return environments, deploy shape, config variables, workflows,\n datastores, and source refs. Do not write mutations.\"\n- API/data/integrations: \"Inspect route specs, client/adapters, models,\n datastores, queues, auth, and external integrations. Return candidate\n APIContract/DataStore/Adapter/Dependency facts with evidence. No mutations.\"\n- GitHub history: \"Use GitHub tools/CLI for repo metadata, releases, recent\n merged PRs, open issues, linked tickets/docs, and CI signal. Return timeline,\n fixes, decisions, bug patterns, and source refs. No mutations.\"\n- Preferences: \"Find explicit preferences in docs, config, tests, contribution\n guides, PR templates, and comments. Return only explicit reusable policies\n with evidence. No mutations.\"\n\nThe main agent should continue non-overlapping discovery while subagents run.\n\n## Phase 3: Local Repo Inspection Targets\n\nUse structured, bounded local inspection. Examples:\n\n```bash\nrg --files -g 'README*' -g 'docs/**' -g '*ADR*' -g 'package.json' -g 'pyproject.toml' -g 'Cargo.toml' -g 'go.mod'\nrg --files -g 'Dockerfile*' -g 'docker-compose*' -g '.github/workflows/**' -g '*.tf' -g 'k8s/**' -g '.env*'\nrg -n \"FastAPI|APIRouter|express\\\\(|router\\\\.|Django|Flask|NextResponse|route\\\\(\" .\nrg -n \"postgres|mysql|redis|mongo|s3|kafka|rabbit|queue|oauth|stripe|slack|github|linear|jira\" .\nrg -n \"pytest|vitest|jest|playwright|make test|npm test|uv run|cargo test\" README* docs .github pyproject.toml package.json Makefile\n```\n\nDo not infer durable facts from filenames alone. Use files to locate sources of\ntruth, then read the relevant snippets or authored docs.\n\n## Phase 4: Hosted/GitHub Hydration\n\nUse the agent's integration tools/connectors, including GitHub app/MCP/CLI\ntools when available, not Potpie queue ingestion commands. For GitHub-backed\nrepo ingestion, gather the items below. Do not use Potpie CLI queue ingestion.\n\n- Repository metadata: full name, default branch, description, topics,\n visibility, homepage, license, archived/fork status.\n- Documentation: README, contributing guide, CODEOWNERS, PR/issue templates,\n docs linked from the repo.\n- Releases/tags when they describe shipped behavior or deploy cadence.\n- Recent merged PRs: title, body, author, merged date, branch, labels, linked\n issues, changed filenames; fetch patches only when author text is insufficient.\n- Open/high-signal issues: title, body, labels, state, author, comments when\n available; issues can record requests/bugs but do not prove fixes.\n- CI/workflows: workflow files and failed/passing runs only when relevant to\n durable workflows, release process, or recurring failures.\n- Linked systems: Linear/Jira/Confluence/Slack/docs mentioned in repo, PRs, or\n issues when corresponding tools are available.\n\nRespect API limits and user scope. Prefer recent/high-signal items over\nexhaustive pagination unless the user explicitly asks for full history.\n\n## Phase 5: Evidence Matrix\n\nBefore writing, build a compact matrix:\n\n| Candidate | Entity types + predicate + direction | Source refs | Authority | Truth class | Confidence | Action |\n|---|---|---|---|---|---|---|\n| Worker uses Redis | Service → USES → DataStore | file/doc locator | authoritative_code | authoritative_fact | 0.95 | commit / inbox / skip |\n\nSelect type/predicate from the inspected catalog and record the intended read\nthat should retrieve the fact. Classify meaning independently of authority:\na source-backed behavior is not a preference, and `feature_note` is not a\nsubstitute for a `Feature` with its supported relations.\n\nGuidelines:\n\n- Use `authoritative_fact` for explicit docs/config/code ownership facts.\n- Use `source_observation` for observed source material that may not be policy.\n- Use `agent_claim` for lower-authority synthesis from multiple weak signals.\n- Use `preference` only for explicit reusable project preferences.\n- Use `timeline_event` for source-time activity from PRs, tickets, releases, or\n deployments.\n- Put uncertain but potentially useful findings into `graph inbox add`.\n\n## Phase 6: Identity Resolution\n\nResolve before linking — one untyped search per entity you intend to link and\nhave not already seen in a read (a wrong `--type` guess returns nothing);\nnarrow by `--source-ref` for tickets and PRs:\n\n```bash\npotpie graph search-entities \"\" --limit 10\npotpie graph search-entities \"\" --source-ref --limit 10\n```\n\nReuse canonical keys. If duplicate candidates appear, stop and use inbox or a\nreview-required correction flow; do not create near-duplicate entities.\n\n## Phase 7: Write\n\nAuthor semantic mutation JSON from the `graph mutation-template` skeletons\nprinted in Phase 0; `propose` validates against the live contract and names\nevery rejected operation by index. Omit `graph_contract_version` from the\npayload. Use the full catalog inspected in Phase 0 for relationships absent\nfrom the templates. Refresh it if the destination or contract changes.\n\n```bash\npotpie --json graph propose --file mutation.json\n```\n\nInspect proposal status, diff, warnings, rejected operations, conflicts, and\nreview flags:\n\n- `invalid` or rejected operations: fix the mutation or skip the weak fact.\n- `conflict` or duplicate risk: resolve identity or use inbox.\n- `review_required`: ask for approval, then re-run\n `potpie --json graph propose --file mutation.json --approved-by `\n and commit with `--verify`, or commit the plan you have with\n `potpie --json graph commit --approved-by --verify`;\n `commit` without an approval answers `review_required` again.\n- `validated` / low-risk: commit with `--verify`.\n\n```bash\npotpie --json graph commit --verify\n```\n\n`commit --verify` prints the plan id, readback and quality status;\n`graph history --plan ` is for later inspection.\n\nFor large batches of agent-authored mutations, use `graph bulk apply` with\ndry-run, chunking, manifest, and verify. Bulk apply must only apply facts the\nharness already selected.\n\n## Phase 8: Verify And Quality Gate\n\n`graph commit --verify` reads back committed claims and checks quality. When it\nwarns or fails, drill down with affected reads and quality reports:\n\n```bash\npotpie graph read --subgraph features --view feature_context --scope anchor_entity_key: --limit 50\npotpie graph read --subgraph infra_topology --view service_neighborhood --scope service: --depth 2 --direction both --limit 50\npotpie graph read --subgraph recent_changes --view timeline --scope repo: --limit 50 --format table\npotpie --json graph quality duplicate-candidates --limit 20\npotpie --json graph quality low-confidence --limit 20\npotpie --json graph quality conflicting-claims --limit 20\npotpie --json graph quality orphan-entities --limit 20\n```\n\nVerify the selected representation as well as persistence: read each affected\nfamily and confirm the intended typed relationships and evidence. A valid plan\nor passing quality report cannot establish that factual prose belongs under\n`POLICY_APPLIES_TO`. If a fact is stored but absent from its intended read,\ninspect its type, relation, and scope before adding another claim.\nIf the verified commit misses expected facts, fix the mutation or record an inbox item.\nReport what was ingested, what was skipped, and what remains uncertain.\n\nReport it with the commands, not as prose alone: the `propose` and\n`commit --verify` you ran, the `plan_id` they returned, and the verify outcome.\nAn ingestion the reader cannot re-open with `graph history --plan ` is\none they have to take on trust, and the whole point of the verified gate is that\nthey do not have to. Name the reads that came back empty as well — they are why\na slice of the evidence matrix stayed thin.\n\nWhen the ingested source described a topology — a service map, a deploy shape, a\nset of dependencies — draw what you wrote as a mermaid ` ```mermaid ` /\n`flowchart LR` block, using the same entity keys and predicates that went into\nthe mutation, so the picture and the graph can be compared line by line. Nothing else here is a shape: counts, skipped\nsources, and open questions belong in a list.\n\n## Repository Baseline\n\nFor repository ingestion, run baseline before change history. Use\n`potpie-repo-baseline` in deep mode when the user asks to ingest or understand a\nrepo deeply. Record source-backed purpose, application type, features,\nservice/module map, API contracts, datastores, integrations, environments,\ndeploy shape, ownership, and explicit project preferences. Then use\n`potpie-change-timeline` for recent or historical activity. Do not infer\nbaseline architecture from PR titles or issue status.\n\nRepresent capabilities as `Feature` entities. Link repositories or services to\nfeatures with `PROVIDES`, and use `IMPLEMENTED_IN` only when a source locates\nthe implementation.\n\n## Document Payloads\n\nWhen a source is a document whose *content* must stay searchable and citable —\na PDF, a spreadsheet, a long markdown/HTML doc, an exported wiki page — do not\npaste its body into summaries, descriptions, or claims. Payloads never enter\nthe graph. Use the matching per-format skill (`potpie-resource-pdf`,\n`potpie-resource-spreadsheet`, `potpie-resource-markdown`): you write an\nextraction script, the script emits a chunk directory, and\n`potpie resource import` stores the bytes and writes the Document/section\nstructure to the graph. Agent-authored section summaries index each section\nfor graph context, and the resource index searches the chunk text. Then link\ncoverage with `DOCUMENTS` claims, and for structured data derive the durable\nfacts as ordinary claims citing `potpie://res/...` chunk ids as evidence. Facts\na document *states* (decisions, preferences, infra) are still recorded as\nnormal graph claims under the rules below — the resource store holds the\nevidence payload, not the conclusions.\n\nA document is not a registrable source: `source add` refuses a document kind\nwith `source_kind_is_a_document`. When only a pointer is wanted and the text\nneed not be searchable, a `doc_reference` record whose summary says what the\ndocument covers is enough.\n\n## Source Rules\n\n- Tickets and issues can record timeline events, bug patterns, decisions, and\n docs. They do not prove a fix unless tied to a merged PR, commit, deployment,\n or explicit shipped-resolution source.\n- Documents can record preferences, decisions, runbook notes, service notes, and\n infra facts only when they explicitly say them. Their payloads belong in the\n resource store (see Document Payloads above), never in graph properties.\n- Logs and transcripts can record diagnostic signals, investigations, fixes, and\n verifications. Keep raw logs out of descriptions except for short distinctive\n error text.\n\n## Protocol definitions and codecs\n\nWhen the source or question concerns telegrams, message layouts, field/value\nmeanings, revisions or decoder changes, check the catalog for\n`protocols.message_context` and, when it is advertised, follow\n[the shared protocol reference](../potpie-graph/references/protocols.md). The\nextension is opt-in (`potpie config set graph.protocols on`), so a catalog\nwithout it means protocol memory is off. Use explicit protocol reads alongside\nexisting Service/CodeAsset context. Preserve immutable source evidence and\npartial coverage; capabilities do not establish traffic.\n","potpie/cli/templates/agent_bundle/.agents/skills/potpie-infra-architecture/SKILL.md":"---\nname: potpie-infra-architecture\nversion: \"5\"\ndescription: \"Use for project infra and architecture context: environments, adapters, runtime configuration, deployments, service dependencies, datastores, API contracts, ownership, incidents, and dependency blast radius.\"\n---\n\n# Potpie Infra Architecture\n\nUse this skill when the task touches environments, adapters, deployment behavior,\nruntime config, service dependencies, production incidents, or architecture\nchanges.\n\n## Fast Path\n\nShare one discovery pass with other skills; reuse current reads and hook context\nfor the same task, pot, and scope. Run broad resolve and an untyped entity lookup\nconcurrently when the task names a service, environment, adapter, or dependency\nwhose canonical key is unknown. Skip the lookup when a key is already known.\nFor code changes, scoped preferences can run alongside both. Use a known\nexplicit pot selector; resolve ambiguous routing before scoped retrieval and\ncheck returned pot IDs before combining results.\n\nBroad context and conditional identity lookup:\n\n```bash\npotpie resolve \"\"\npotpie graph search-entities \"\" --limit 10\n```\n\nUse the returned canonical service key for a neighborhood when the task needs\nrelationships or resolve leaves a gap; do not guess an anchor. For a direct\nentity question, identity lookup then neighborhood can suffice without resolve.\nThe `service:` below stands for that returned key. Start with\n**no `--environment`**:\n\n```bash\npotpie graph read --subgraph infra_topology --view service_neighborhood --scope service: --depth 2 --direction both --limit 20\n```\n\nThe environment filter defaults to `qualified_only`: `--environment prod`\nalone drops every unqualified edge — `USES`, `DEFINED_IN`, `OWNED_BY` — and\nanswers \"talks to nothing\". To exclude other environments, keep them explicitly:\n\n```bash\npotpie graph read --subgraph infra_topology --view service_neighborhood --scope service:,include_unqualified_environment:true --environment --depth 2 --direction both --limit 20\n```\n\nAn empty neighborhood can mean missing relations, not a wrong key. Start with\n`--depth 2 --direction both`; `--direction` accepts `out`, `in` or `both`, and\nany other spelling is refused. A `--depth` past the view's maximum runs at the\nmaximum and says so. Alternatively, for\neverything the graph holds about one service — decisions, preferences, timeline\nand features beside the topology — use one flat list:\n\n```bash\npotpie graph neighborhood --entity service: --detail summary --limit 20\n```\n\nChoose the neighborhood that answers the question; do not automatically run\nboth. Fetch already-discovered document chunks with `potpie resource get`\nconcurrently with neighborhood reads, and stop expanding once the required\nevidence is covered. Pass `--pot ` once the pot is known.\n\n## Apply Results\n\nUse infra context for blast radius, where-to-look decisions, deployment changes,\nadapter selection, and incident debugging. Preserve environment qualifiers; a\nstaging dependency is not proof of a production dependency.\n\nLook for explicit topology facts: `DEFINED_IN`, `DEPLOYED_TO`, `DEPENDS_ON`,\n`USES`, `EXPOSES`, `HOSTED_ON`, and `OWNED_BY`.\n\n## Report Back\n\nShow the `graph read` you ran, including the `--depth`, `--limit`, and any\n`--environment` you chose. A neighborhood is only interpretable next to its\nbounds: \"nothing depends on it\" means one thing at `--depth 2` and another at\n`--depth 1`, and the reader cannot tell which you meant unless the command is on\nthe page.\n\nA neighborhood is the case a diagram was made for — draw it:\n\n```mermaid\nflowchart LR\n payments[\"payments-api (prod)\"] -->|DEPENDS_ON| ledger[\"ledger-api (prod)\"]\n payments -->|USES| pgdb[(\"payments-db\")]\n ledger -.->|USES, inferred| cache[(\"redis\")]\n```\n\nKeep the environment qualifier on the node, label every edge with its predicate,\nand dash any edge you inferred rather than read — a solid edge asserts the graph\nsays so. Blast radius is the same picture with the direction reversed. Do not\ndraw one dependency; say it in a sentence.\n\n## Record Architecture\n\nRecord only source-backed topology or carefully labeled agent inferences. Use\n`authoritative_fact` when evidence is an explicit source of truth such as\ndeployment config, service manifest, infra doc, ADR, or user statement. Use\n`agent_claim` for lower-authority interpretation.\n\nTopology edges are not a `potpie record` type; write them as a plan:\n\n```bash\npotpie graph mutation-template --kind infra-snapshot\npotpie --json graph propose --file mutation.json\npotpie --json graph commit --verify\n```\n\nReuse the keys your reads returned. Omit `graph_contract_version` from the\npayload. If `propose` answers `review_required`, ask the user, then re-run it\nwith `--approved-by ` and commit as above (or pass `--approved-by` to\nthe commit); `commit --verify` prints the plan id, readback and quality status.\n\nA decision *about* the architecture is one call:\n\n```bash\npotpie record --type decision --summary \"\" --detail rationale=\"\" --scope service:\n```\n\nEvery durable infra fact needs an environment when the fact differs by\nenvironment, evidence when available, and a retrieval-grade description.\n\nArchitecture capture is harness-led: inspect authoritative sources and write\nsemantic facts. Do not use scanner-driven graph updates or infer topology from\ndirectory names, imports, or package files alone.\n\n## Protocol definitions and codecs\n\nWhen the source or question concerns telegrams, message layouts, field/value\nmeanings, revisions or decoder changes, check the catalog for\n`protocols.message_context` and, when it is advertised, follow\n[the shared protocol reference](../potpie-graph/references/protocols.md). The\nextension is opt-in (`potpie config set graph.protocols on`), so a catalog\nwithout it means protocol memory is off. Use explicit protocol reads alongside\nexisting Service/CodeAsset context. Preserve immutable source evidence and\npartial coverage; capabilities do not establish traffic.\n","potpie/cli/templates/agent_bundle/.agents/skills/potpie-graph/SKILL.md":"# potpie-graph\n\nPath: `potpie/cli/templates/agent_bundle/.agents/skills/potpie-graph/SKILL.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/potpie-ai/potpie/HEAD/potpie/cli/templates/agent_bundle/.agents/skills/potpie-graph/SKILL.md)","potpie/cli/templates/agent_bundle/.agents/skills/potpie-debug-memory/SKILL.md":"# potpie-debug-memory\n\nPath: `potpie/cli/templates/agent_bundle/.agents/skills/potpie-debug-memory/SKILL.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/potpie-ai/potpie/HEAD/potpie/cli/templates/agent_bundle/.agents/skills/potpie-debug-memory/SKILL.md)","potpie/cli/templates/agent_bundle/.agents/skills/potpie-cli/SKILL.md":"# potpie-cli\n\nPath: `potpie/cli/templates/agent_bundle/.agents/skills/potpie-cli/SKILL.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/potpie-ai/potpie/HEAD/potpie/cli/templates/agent_bundle/.agents/skills/potpie-cli/SKILL.md)","potpie/cli/templates/agent_bundle/.agents/skills/potpie-change-timeline/SKILL.md":"# potpie-change-timeline\n\nPath: `potpie/cli/templates/agent_bundle/.agents/skills/potpie-change-timeline/SKILL.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/potpie-ai/potpie/HEAD/potpie/cli/templates/agent_bundle/.agents/skills/potpie-change-timeline/SKILL.md)","potpie/context-engine/src/potpie_context_engine/adapters/outbound/reconciliation/skills/graph-mutation-plan/SKILL.md":"# graph-mutation-plan\n\nPath: `potpie/context-engine/src/potpie_context_engine/adapters/outbound/reconciliation/skills/graph-mutation-plan/SKILL.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/potpie-ai/potpie/HEAD/potpie/context-engine/src/potpie_context_engine/adapters/outbound/reconciliation/skills/graph-mutation-plan/SKILL.md)","potpie/context-engine/src/potpie_context_engine/adapters/outbound/reconciliation/skills/backfill-enumerate-drain/SKILL.md":"# backfill-enumerate-drain\n\nPath: `potpie/context-engine/src/potpie_context_engine/adapters/outbound/reconciliation/skills/backfill-enumerate-drain/SKILL.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/potpie-ai/potpie/HEAD/potpie/context-engine/src/potpie_context_engine/adapters/outbound/reconciliation/skills/backfill-enumerate-drain/SKILL.md)","potpie/cli/templates/claude_plugin/commands/potpie-feature.md":"# Command: /potpie-feature\n\nPath: `potpie/cli/templates/claude_plugin/commands/potpie-feature.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/potpie-ai/potpie/HEAD/potpie/cli/templates/claude_plugin/commands/potpie-feature.md)","potpie/cli/templates/claude_plugin/commands/potpie-record.md":"# Command: /potpie-record\n\nPath: `potpie/cli/templates/claude_plugin/commands/potpie-record.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/potpie-ai/potpie/HEAD/potpie/cli/templates/claude_plugin/commands/potpie-record.md)","potpie/cli/templates/claude_plugin/.claude-plugin/marketplace.json":"# Claude Plugin Marketplace Catalog\n\nPath: `potpie/cli/templates/claude_plugin/.claude-plugin/marketplace.json`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/potpie-ai/potpie/HEAD/potpie/cli/templates/claude_plugin/.claude-plugin/marketplace.json)","potpie/cli/templates/claude_plugin/.claude-plugin/plugin.json":"# claude-plugin Plugin Manifest\n\nPath: `potpie/cli/templates/claude_plugin/.claude-plugin/plugin.json`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/potpie-ai/potpie/HEAD/potpie/cli/templates/claude_plugin/.claude-plugin/plugin.json)","potpie/cli/templates/claude_bundle/.claude/commands/potpie-feature.md":"# Command: /potpie-feature\n\nPath: `potpie/cli/templates/claude_bundle/.claude/commands/potpie-feature.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/potpie-ai/potpie/HEAD/potpie/cli/templates/claude_bundle/.claude/commands/potpie-feature.md)","potpie/cli/templates/claude_bundle/.claude/commands/potpie-record.md":"# Command: /potpie-record\n\nPath: `potpie/cli/templates/claude_bundle/.claude/commands/potpie-record.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/potpie-ai/potpie/HEAD/potpie/cli/templates/claude_bundle/.claude/commands/potpie-record.md)","potpie/cli/templates/agent_bundle/.agents/skills/potpie-graph/agents/openai.yaml":"# Agents Skill\n\nPath: `potpie/cli/templates/agent_bundle/.agents/skills/potpie-graph/agents/openai.yaml`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/potpie-ai/potpie/HEAD/potpie/cli/templates/agent_bundle/.agents/skills/potpie-graph/agents/openai.yaml)","potpie/cli/templates/agent_bundle/.agents/skills/potpie-cli/agents/openai.yaml":"# Agents Skill\n\nPath: `potpie/cli/templates/agent_bundle/.agents/skills/potpie-cli/agents/openai.yaml`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/potpie-ai/potpie/HEAD/potpie/cli/templates/agent_bundle/.agents/skills/potpie-cli/agents/openai.yaml)"},"items":[{"name":"SKILL.md","path":"potpie/cli/templates/agent_bundle/.agents/skills/potpie-change-timeline/SKILL.md","rawUrl":"https://raw.githubusercontent.com/potpie-ai/potpie/HEAD/potpie/cli/templates/agent_bundle/.agents/skills/potpie-change-timeline/SKILL.md","title":"potpie-change-timeline","category":"anthropic-skill","format":"markdown","content":"# potpie-change-timeline\n\nPath: `potpie/cli/templates/agent_bundle/.agents/skills/potpie-change-timeline/SKILL.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/potpie-ai/potpie/HEAD/potpie/cli/templates/agent_bundle/.agents/skills/potpie-change-timeline/SKILL.md)","tokens":300,"sizeBytes":282},{"name":"openai.yaml","path":"potpie/cli/templates/agent_bundle/.agents/skills/potpie-cli/agents/openai.yaml","rawUrl":"https://raw.githubusercontent.com/potpie-ai/potpie/HEAD/potpie/cli/templates/agent_bundle/.agents/skills/potpie-cli/agents/openai.yaml","title":"Agents Skill","category":"anthropic-skill","format":"yaml","content":"# Agents Skill\n\nPath: `potpie/cli/templates/agent_bundle/.agents/skills/potpie-cli/agents/openai.yaml`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/potpie-ai/potpie/HEAD/potpie/cli/templates/agent_bundle/.agents/skills/potpie-cli/agents/openai.yaml)","tokens":300,"sizeBytes":268},{"name":"SKILL.md","path":"potpie/cli/templates/agent_bundle/.agents/skills/potpie-cli/SKILL.md","rawUrl":"https://raw.githubusercontent.com/potpie-ai/potpie/HEAD/potpie/cli/templates/agent_bundle/.agents/skills/potpie-cli/SKILL.md","title":"potpie-cli","category":"anthropic-skill","format":"markdown","content":"# potpie-cli\n\nPath: `potpie/cli/templates/agent_bundle/.agents/skills/potpie-cli/SKILL.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/potpie-ai/potpie/HEAD/potpie/cli/templates/agent_bundle/.agents/skills/potpie-cli/SKILL.md)","tokens":300,"sizeBytes":246},{"name":"SKILL.md","path":"potpie/cli/templates/agent_bundle/.agents/skills/potpie-debug-memory/SKILL.md","rawUrl":"https://raw.githubusercontent.com/potpie-ai/potpie/HEAD/potpie/cli/templates/agent_bundle/.agents/skills/potpie-debug-memory/SKILL.md","title":"potpie-debug-memory","category":"anthropic-skill","format":"markdown","content":"# potpie-debug-memory\n\nPath: `potpie/cli/templates/agent_bundle/.agents/skills/potpie-debug-memory/SKILL.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/potpie-ai/potpie/HEAD/potpie/cli/templates/agent_bundle/.agents/skills/potpie-debug-memory/SKILL.md)","tokens":300,"sizeBytes":273},{"name":"openai.yaml","path":"potpie/cli/templates/agent_bundle/.agents/skills/potpie-graph/agents/openai.yaml","rawUrl":"https://raw.githubusercontent.com/potpie-ai/potpie/HEAD/potpie/cli/templates/agent_bundle/.agents/skills/potpie-graph/agents/openai.yaml","title":"Agents Skill","category":"anthropic-skill","format":"yaml","content":"# Agents Skill\n\nPath: `potpie/cli/templates/agent_bundle/.agents/skills/potpie-graph/agents/openai.yaml`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/potpie-ai/potpie/HEAD/potpie/cli/templates/agent_bundle/.agents/skills/potpie-graph/agents/openai.yaml)","tokens":300,"sizeBytes":272},{"name":"SKILL.md","path":"potpie/cli/templates/agent_bundle/.agents/skills/potpie-graph/SKILL.md","rawUrl":"https://raw.githubusercontent.com/potpie-ai/potpie/HEAD/potpie/cli/templates/agent_bundle/.agents/skills/potpie-graph/SKILL.md","title":"potpie-graph","category":"anthropic-skill","format":"markdown","content":"# potpie-graph\n\nPath: `potpie/cli/templates/agent_bundle/.agents/skills/potpie-graph/SKILL.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/potpie-ai/potpie/HEAD/potpie/cli/templates/agent_bundle/.agents/skills/potpie-graph/SKILL.md)","tokens":300,"sizeBytes":252},{"name":"SKILL.md","path":"potpie/cli/templates/agent_bundle/.agents/skills/potpie-infra-architecture/SKILL.md","rawUrl":"https://raw.githubusercontent.com/potpie-ai/potpie/HEAD/potpie/cli/templates/agent_bundle/.agents/skills/potpie-infra-architecture/SKILL.md","title":"potpie-infra-architecture","category":"anthropic-skill","format":"markdown","content":"---\nname: potpie-infra-architecture\nversion: \"5\"\ndescription: \"Use for project infra and architecture context: environments, adapters, runtime configuration, deployments, service dependencies, datastores, API contracts, ownership, incidents, and dependency blast radius.\"\n---\n\n# Potpie Infra Architecture\n\nUse this skill when the task touches environments, adapters, deployment behavior,\nruntime config, service dependencies, production incidents, or architecture\nchanges.\n\n## Fast Path\n\nShare one discovery pass with other skills; reuse current reads and hook context\nfor the same task, pot, and scope. Run broad resolve and an untyped entity lookup\nconcurrently when the task names a service, environment, adapter, or dependency\nwhose canonical key is unknown. Skip the lookup when a key is already known.\nFor code changes, scoped preferences can run alongside both. Use a known\nexplicit pot selector; resolve ambiguous routing before scoped retrieval and\ncheck returned pot IDs before combining results.\n\nBroad context and conditional identity lookup:\n\n```bash\npotpie resolve \"\"\npotpie graph search-entities \"\" --limit 10\n```\n\nUse the returned canonical service key for a neighborhood when the task needs\nrelationships or resolve leaves a gap; do not guess an anchor. For a direct\nentity question, identity lookup then neighborhood can suffice without resolve.\nThe `service:` below stands for that returned key. Start with\n**no `--environment`**:\n\n```bash\npotpie graph read --subgraph infra_topology --view service_neighborhood --scope service: --depth 2 --direction both --limit 20\n```\n\nThe environment filter defaults to `qualified_only`: `--environment prod`\nalone drops every unqualified edge — `USES`, `DEFINED_IN`, `OWNED_BY` — and\nanswers \"talks to nothing\". To exclude other environments, keep them explicitly:\n\n```bash\npotpie graph read --subgraph infra_topology --view service_neighborhood --scope service:,include_unqualified_environment:true --environment --depth 2 --direction both --limit 20\n```\n\nAn empty neighborhood can mean missing relations, not a wrong key. Start with\n`--depth 2 --direction both`; `--direction` accepts `out`, `in` or `both`, and\nany other spelling is refused. A `--depth` past the view's maximum runs at the\nmaximum and says so. Alternatively, for\neverything the graph holds about one service — decisions, preferences, timeline\nand features beside the topology — use one flat list:\n\n```bash\npotpie graph neighborhood --entity service: --detail summary --limit 20\n```\n\nChoose the neighborhood that answers the question; do not automatically run\nboth. Fetch already-discovered document chunks with `potpie resource get`\nconcurrently with neighborhood reads, and stop expanding once the required\nevidence is covered. Pass `--pot ` once the pot is known.\n\n## Apply Results\n\nUse infra context for blast radius, where-to-look decisions, deployment changes,\nadapter selection, and incident debugging. Preserve environment qualifiers; a\nstaging dependency is not proof of a production dependency.\n\nLook for explicit topology facts: `DEFINED_IN`, `DEPLOYED_TO`, `DEPENDS_ON`,\n`USES`, `EXPOSES`, `HOSTED_ON`, and `OWNED_BY`.\n\n## Report Back\n\nShow the `graph read` you ran, including the `--depth`, `--limit`, and any\n`--environment` you chose. A neighborhood is only interpretable next to its\nbounds: \"nothing depends on it\" means one thing at `--depth 2` and another at\n`--depth 1`, and the reader cannot tell which you meant unless the command is on\nthe page.\n\nA neighborhood is the case a diagram was made for — draw it:\n\n```mermaid\nflowchart LR\n payments[\"payments-api (prod)\"] -->|DEPENDS_ON| ledger[\"ledger-api (prod)\"]\n payments -->|USES| pgdb[(\"payments-db\")]\n ledger -.->|USES, inferred| cache[(\"redis\")]\n```\n\nKeep the environment qualifier on the node, label every edge with its predicate,\nand dash any edge you inferred rather than read — a solid edge asserts the graph\nsays so. Blast radius is the same picture with the direction reversed. Do not\ndraw one dependency; say it in a sentence.\n\n## Record Architecture\n\nRecord only source-backed topology or carefully labeled agent inferences. Use\n`authoritative_fact` when evidence is an explicit source of truth such as\ndeployment config, service manifest, infra doc, ADR, or user statement. Use\n`agent_claim` for lower-authority interpretation.\n\nTopology edges are not a `potpie record` type; write them as a plan:\n\n```bash\npotpie graph mutation-template --kind infra-snapshot\npotpie --json graph propose --file mutation.json\npotpie --json graph commit --verify\n```\n\nReuse the keys your reads returned. Omit `graph_contract_version` from the\npayload. If `propose` answers `review_required`, ask the user, then re-run it\nwith `--approved-by ` and commit as above (or pass `--approved-by` to\nthe commit); `commit --verify` prints the plan id, readback and quality status.\n\nA decision *about* the architecture is one call:\n\n```bash\npotpie record --type decision --summary \"\" --detail rationale=\"\" --scope service:\n```\n\nEvery durable infra fact needs an environment when the fact differs by\nenvironment, evidence when available, and a retrieval-grade description.\n\nArchitecture capture is harness-led: inspect authoritative sources and write\nsemantic facts. Do not use scanner-driven graph updates or infer topology from\ndirectory names, imports, or package files alone.\n\n## Protocol definitions and codecs\n\nWhen the source or question concerns telegrams, message layouts, field/value\nmeanings, revisions or decoder changes, check the catalog for\n`protocols.message_context` and, when it is advertised, follow\n[the shared protocol reference](../potpie-graph/references/protocols.md). The\nextension is opt-in (`potpie config set graph.protocols on`), so a catalog\nwithout it means protocol memory is off. Use explicit protocol reads alongside\nexisting Service/CodeAsset context. Preserve immutable source evidence and\npartial coverage; capabilities do not establish traffic.\n","frontmatter":{"name":"potpie-infra-architecture","version":"5","description":"Use for project infra and architecture context: environments, adapters, runtime configuration, deployments, service dependencies, datastores, API contracts, ownership, incidents, and dependency blast radius."},"isInternal":false,"tokens":1352,"sizeBytes":6172},{"name":"SKILL.md","path":"potpie/cli/templates/agent_bundle/.agents/skills/potpie-source-ingestion/SKILL.md","rawUrl":"https://raw.githubusercontent.com/potpie-ai/potpie/HEAD/potpie/cli/templates/agent_bundle/.agents/skills/potpie-source-ingestion/SKILL.md","title":"potpie-source-ingestion","category":"anthropic-skill","format":"markdown","content":"---\nname: potpie-source-ingestion\nversion: \"5\"\ndescription: \"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. Document payloads (PDF, spreadsheet, markdown/HTML) route through the per-format potpie-resource-* skills and `potpie resource import`.\"\n---\n\n# Potpie Source Ingestion\n\nUse this skill for explicit ingestion requests. The harness is the intelligence:\nit gathers source data, reads it, decides what is durable, resolves identity, and\nwrites semantic graph mutations with evidence. Potpie validates and stores; it\ndoes not decide what source material means.\n\n## Non-Negotiables\n\n- Use a todo/checklist for every repository or multi-source ingestion. Do not\n jump directly from a README to graph writes.\n- Local inspection is required for repo understanding. Scanner-driven graph\n updates are forbidden. Inspect files with `rg`, `rg --files`, `git`, and\n structured tooling; do not run legacy or deterministic ingestion/scanner\n commands that walk the tree and write graph facts.\n- Use subagents only for read-only discovery slices. The main agent owns source\n selection, identity resolution, mutation proposals, commits, and final\n synthesis.\n- Do not write until each required discovery lane is complete, explicitly\n unavailable, or intentionally scoped out by the user.\n- Every write needs source refs, source authority, truth class, confidence,\n compact summary, and retrieval-grade description.\n\n## Phase 0: Scope And Preflight\n\n1. Define source kind, pot/project, repo/path/URL, time window, and target memory\n shape: baseline, history, docs, infra, debug memory, preferences, or all.\n2. Verify Potpie scope and graph availability with one call:\n\n```bash\npotpie status\n```\n\nIt reports the daemon, the active pot, backend readiness and claim counts;\nevery later read names the pot it used in its header, so do not pre-read\n`pot info`, `source list` or `graph status`. Pass `--pot ` on later\ncalls once the pot is known.\n\n3. If the repo is not registered, register metadata only. Use explicit `--pot`\n when pot scope is ambiguous:\n\n```bash\npotpie source add repo . --pot \n```\n\n4. Inspect the full destination ontology before selecting mutation shapes:\n\n```bash\npotpie --json graph catalog --profile full --pot \n```\n\nRead the [ontology selection guidance](../potpie-graph/SKILL.md#ontology-selection)\nto distinguish facts, decisions, policies, events, and source material. Reuse\nthis catalog during the task; `--profile read` omits the ontology. Select from\nall supported entities and predicates, then use templates for payload shape.\nThe templates are examples, not an exhaustive list of relationships.\n`graph describe --examples` carries read examples only.\n\n```bash\npotpie graph mutation-template --kind repo-baseline\npotpie graph mutation-template --kind infra-snapshot\npotpie graph mutation-template --kind timeline-change\npotpie graph mutation-template --kind preference-policy\npotpie graph mutation-template --kind bug-fix\n```\n\n5. If the CLI is unavailable or broken, continue discovery, build the proposed\n evidence matrix, and stop before committing graph writes.\n\n## Phase 1: Todo Plan\n\nCreate and maintain todos with at least these lanes for repository ingestion:\n\n- Scope, pot, source registration, and graph contract preflight.\n- Product/docs: README, docs, ADRs, runbooks, public docs, linked websites.\n- Local repo map: manifests, packages/apps, entrypoints, route/API surfaces,\n tests, framework config, major modules, generated/API specs.\n- Runtime/deploy: Dockerfiles, compose, Kubernetes, Terraform, CI workflows,\n deploy scripts, environment templates, feature flags.\n- API/data/integrations: service clients, adapters, datastores, models,\n queues, auth providers, external APIs.\n- GitHub/history: repo metadata, topics, releases/tags, recent merged PRs, open\n issues, linked tickets/docs, CI/deploy records.\n- Preferences/workflows: explicit coding style, test commands, local dev setup,\n release/deploy/runbook workflows.\n- Synthesis: evidence matrix, candidate graph facts, identity resolution,\n proposal, verified commit, and gate-driven follow-up checks.\n\nUpdate todos as lanes finish. Preserve uncertain findings for the inbox instead\nof forcing them into canonical graph claims.\n\n## Phase 2: Parallel Discovery\n\nParallelize independent read-only slices when tools allow it. Recommended\nsubagent prompts:\n\n- Docs/product: \"Read README, docs, ADRs, runbooks, package metadata, and linked\n product pages. Return product purpose, features, explicit decisions,\n preferences, workflows, and source refs. Do not write mutations.\"\n- Local architecture: \"Inspect manifests, top-level apps/packages, entrypoints,\n route/API surfaces, tests, and framework config. Return service/module map,\n likely features, explicit source files, uncertainty, and no mutations.\"\n- Runtime/deploy: \"Inspect Docker/compose/Kubernetes/Terraform/CI/deploy/env\n templates. Return environments, deploy shape, config variables, workflows,\n datastores, and source refs. Do not write mutations.\"\n- API/data/integrations: \"Inspect route specs, client/adapters, models,\n datastores, queues, auth, and external integrations. Return candidate\n APIContract/DataStore/Adapter/Dependency facts with evidence. No mutations.\"\n- GitHub history: \"Use GitHub tools/CLI for repo metadata, releases, recent\n merged PRs, open issues, linked tickets/docs, and CI signal. Return timeline,\n fixes, decisions, bug patterns, and source refs. No mutations.\"\n- Preferences: \"Find explicit preferences in docs, config, tests, contribution\n guides, PR templates, and comments. Return only explicit reusable policies\n with evidence. No mutations.\"\n\nThe main agent should continue non-overlapping discovery while subagents run.\n\n## Phase 3: Local Repo Inspection Targets\n\nUse structured, bounded local inspection. Examples:\n\n```bash\nrg --files -g 'README*' -g 'docs/**' -g '*ADR*' -g 'package.json' -g 'pyproject.toml' -g 'Cargo.toml' -g 'go.mod'\nrg --files -g 'Dockerfile*' -g 'docker-compose*' -g '.github/workflows/**' -g '*.tf' -g 'k8s/**' -g '.env*'\nrg -n \"FastAPI|APIRouter|express\\\\(|router\\\\.|Django|Flask|NextResponse|route\\\\(\" .\nrg -n \"postgres|mysql|redis|mongo|s3|kafka|rabbit|queue|oauth|stripe|slack|github|linear|jira\" .\nrg -n \"pytest|vitest|jest|playwright|make test|npm test|uv run|cargo test\" README* docs .github pyproject.toml package.json Makefile\n```\n\nDo not infer durable facts from filenames alone. Use files to locate sources of\ntruth, then read the relevant snippets or authored docs.\n\n## Phase 4: Hosted/GitHub Hydration\n\nUse the agent's integration tools/connectors, including GitHub app/MCP/CLI\ntools when available, not Potpie queue ingestion commands. For GitHub-backed\nrepo ingestion, gather the items below. Do not use Potpie CLI queue ingestion.\n\n- Repository metadata: full name, default branch, description, topics,\n visibility, homepage, license, archived/fork status.\n- Documentation: README, contributing guide, CODEOWNERS, PR/issue templates,\n docs linked from the repo.\n- Releases/tags when they describe shipped behavior or deploy cadence.\n- Recent merged PRs: title, body, author, merged date, branch, labels, linked\n issues, changed filenames; fetch patches only when author text is insufficient.\n- Open/high-signal issues: title, body, labels, state, author, comments when\n available; issues can record requests/bugs but do not prove fixes.\n- CI/workflows: workflow files and failed/passing runs only when relevant to\n durable workflows, release process, or recurring failures.\n- Linked systems: Linear/Jira/Confluence/Slack/docs mentioned in repo, PRs, or\n issues when corresponding tools are available.\n\nRespect API limits and user scope. Prefer recent/high-signal items over\nexhaustive pagination unless the user explicitly asks for full history.\n\n## Phase 5: Evidence Matrix\n\nBefore writing, build a compact matrix:\n\n| Candidate | Entity types + predicate + direction | Source refs | Authority | Truth class | Confidence | Action |\n|---|---|---|---|---|---|---|\n| Worker uses Redis | Service → USES → DataStore | file/doc locator | authoritative_code | authoritative_fact | 0.95 | commit / inbox / skip |\n\nSelect type/predicate from the inspected catalog and record the intended read\nthat should retrieve the fact. Classify meaning independently of authority:\na source-backed behavior is not a preference, and `feature_note` is not a\nsubstitute for a `Feature` with its supported relations.\n\nGuidelines:\n\n- Use `authoritative_fact` for explicit docs/config/code ownership facts.\n- Use `source_observation` for observed source material that may not be policy.\n- Use `agent_claim` for lower-authority synthesis from multiple weak signals.\n- Use `preference` only for explicit reusable project preferences.\n- Use `timeline_event` for source-time activity from PRs, tickets, releases, or\n deployments.\n- Put uncertain but potentially useful findings into `graph inbox add`.\n\n## Phase 6: Identity Resolution\n\nResolve before linking — one untyped search per entity you intend to link and\nhave not already seen in a read (a wrong `--type` guess returns nothing);\nnarrow by `--source-ref` for tickets and PRs:\n\n```bash\npotpie graph search-entities \"\" --limit 10\npotpie graph search-entities \"\" --source-ref --limit 10\n```\n\nReuse canonical keys. If duplicate candidates appear, stop and use inbox or a\nreview-required correction flow; do not create near-duplicate entities.\n\n## Phase 7: Write\n\nAuthor semantic mutation JSON from the `graph mutation-template` skeletons\nprinted in Phase 0; `propose` validates against the live contract and names\nevery rejected operation by index. Omit `graph_contract_version` from the\npayload. Use the full catalog inspected in Phase 0 for relationships absent\nfrom the templates. Refresh it if the destination or contract changes.\n\n```bash\npotpie --json graph propose --file mutation.json\n```\n\nInspect proposal status, diff, warnings, rejected operations, conflicts, and\nreview flags:\n\n- `invalid` or rejected operations: fix the mutation or skip the weak fact.\n- `conflict` or duplicate risk: resolve identity or use inbox.\n- `review_required`: ask for approval, then re-run\n `potpie --json graph propose --file mutation.json --approved-by `\n and commit with `--verify`, or commit the plan you have with\n `potpie --json graph commit --approved-by --verify`;\n `commit` without an approval answers `review_required` again.\n- `validated` / low-risk: commit with `--verify`.\n\n```bash\npotpie --json graph commit --verify\n```\n\n`commit --verify` prints the plan id, readback and quality status;\n`graph history --plan ` is for later inspection.\n\nFor large batches of agent-authored mutations, use `graph bulk apply` with\ndry-run, chunking, manifest, and verify. Bulk apply must only apply facts the\nharness already selected.\n\n## Phase 8: Verify And Quality Gate\n\n`graph commit --verify` reads back committed claims and checks quality. When it\nwarns or fails, drill down with affected reads and quality reports:\n\n```bash\npotpie graph read --subgraph features --view feature_context --scope anchor_entity_key: --limit 50\npotpie graph read --subgraph infra_topology --view service_neighborhood --scope service: --depth 2 --direction both --limit 50\npotpie graph read --subgraph recent_changes --view timeline --scope repo: --limit 50 --format table\npotpie --json graph quality duplicate-candidates --limit 20\npotpie --json graph quality low-confidence --limit 20\npotpie --json graph quality conflicting-claims --limit 20\npotpie --json graph quality orphan-entities --limit 20\n```\n\nVerify the selected representation as well as persistence: read each affected\nfamily and confirm the intended typed relationships and evidence. A valid plan\nor passing quality report cannot establish that factual prose belongs under\n`POLICY_APPLIES_TO`. If a fact is stored but absent from its intended read,\ninspect its type, relation, and scope before adding another claim.\nIf the verified commit misses expected facts, fix the mutation or record an inbox item.\nReport what was ingested, what was skipped, and what remains uncertain.\n\nReport it with the commands, not as prose alone: the `propose` and\n`commit --verify` you ran, the `plan_id` they returned, and the verify outcome.\nAn ingestion the reader cannot re-open with `graph history --plan ` is\none they have to take on trust, and the whole point of the verified gate is that\nthey do not have to. Name the reads that came back empty as well — they are why\na slice of the evidence matrix stayed thin.\n\nWhen the ingested source described a topology — a service map, a deploy shape, a\nset of dependencies — draw what you wrote as a mermaid ` ```mermaid ` /\n`flowchart LR` block, using the same entity keys and predicates that went into\nthe mutation, so the picture and the graph can be compared line by line. Nothing else here is a shape: counts, skipped\nsources, and open questions belong in a list.\n\n## Repository Baseline\n\nFor repository ingestion, run baseline before change history. Use\n`potpie-repo-baseline` in deep mode when the user asks to ingest or understand a\nrepo deeply. Record source-backed purpose, application type, features,\nservice/module map, API contracts, datastores, integrations, environments,\ndeploy shape, ownership, and explicit project preferences. Then use\n`potpie-change-timeline` for recent or historical activity. Do not infer\nbaseline architecture from PR titles or issue status.\n\nRepresent capabilities as `Feature` entities. Link repositories or services to\nfeatures with `PROVIDES`, and use `IMPLEMENTED_IN` only when a source locates\nthe implementation.\n\n## Document Payloads\n\nWhen a source is a document whose *content* must stay searchable and citable —\na PDF, a spreadsheet, a long markdown/HTML doc, an exported wiki page — do not\npaste its body into summaries, descriptions, or claims. Payloads never enter\nthe graph. Use the matching per-format skill (`potpie-resource-pdf`,\n`potpie-resource-spreadsheet`, `potpie-resource-markdown`): you write an\nextraction script, the script emits a chunk directory, and\n`potpie resource import` stores the bytes and writes the Document/section\nstructure to the graph. Agent-authored section summaries index each section\nfor graph context, and the resource index searches the chunk text. Then link\ncoverage with `DOCUMENTS` claims, and for structured data derive the durable\nfacts as ordinary claims citing `potpie://res/...` chunk ids as evidence. Facts\na document *states* (decisions, preferences, infra) are still recorded as\nnormal graph claims under the rules below — the resource store holds the\nevidence payload, not the conclusions.\n\nA document is not a registrable source: `source add` refuses a document kind\nwith `source_kind_is_a_document`. When only a pointer is wanted and the text\nneed not be searchable, a `doc_reference` record whose summary says what the\ndocument covers is enough.\n\n## Source Rules\n\n- Tickets and issues can record timeline events, bug patterns, decisions, and\n docs. They do not prove a fix unless tied to a merged PR, commit, deployment,\n or explicit shipped-resolution source.\n- Documents can record preferences, decisions, runbook notes, service notes, and\n infra facts only when they explicitly say them. Their payloads belong in the\n resource store (see Document Payloads above), never in graph properties.\n- Logs and transcripts can record diagnostic signals, investigations, fixes, and\n verifications. Keep raw logs out of descriptions except for short distinctive\n error text.\n\n## Protocol definitions and codecs\n\nWhen the source or question concerns telegrams, message layouts, field/value\nmeanings, revisions or decoder changes, check the catalog for\n`protocols.message_context` and, when it is advertised, follow\n[the shared protocol reference](../potpie-graph/references/protocols.md). The\nextension is opt-in (`potpie config set graph.protocols on`), so a catalog\nwithout it means protocol memory is off. Use explicit protocol reads alongside\nexisting Service/CodeAsset context. Preserve immutable source evidence and\npartial coverage; capabilities do not establish traffic.\n","frontmatter":{"name":"potpie-source-ingestion","version":"5","description":"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. Document payloads (PDF, spreadsheet, markdown/HTML) route through the per-format potpie-resource-* skills and `potpie resource import`."},"isInternal":false,"tokens":3728,"sizeBytes":16676},{"name":"SKILL.md","path":"potpie/context-engine/src/potpie_context_engine/adapters/outbound/reconciliation/skills/backfill-enumerate-drain/SKILL.md","rawUrl":"https://raw.githubusercontent.com/potpie-ai/potpie/HEAD/potpie/context-engine/src/potpie_context_engine/adapters/outbound/reconciliation/skills/backfill-enumerate-drain/SKILL.md","title":"backfill-enumerate-drain","category":"anthropic-skill","format":"markdown","content":"# backfill-enumerate-drain\n\nPath: `potpie/context-engine/src/potpie_context_engine/adapters/outbound/reconciliation/skills/backfill-enumerate-drain/SKILL.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/potpie-ai/potpie/HEAD/potpie/context-engine/src/potpie_context_engine/adapters/outbound/reconciliation/skills/backfill-enumerate-drain/SKILL.md)","tokens":300,"sizeBytes":366},{"name":"SKILL.md","path":"potpie/context-engine/src/potpie_context_engine/adapters/outbound/reconciliation/skills/graph-mutation-plan/SKILL.md","rawUrl":"https://raw.githubusercontent.com/potpie-ai/potpie/HEAD/potpie/context-engine/src/potpie_context_engine/adapters/outbound/reconciliation/skills/graph-mutation-plan/SKILL.md","title":"graph-mutation-plan","category":"anthropic-skill","format":"markdown","content":"# graph-mutation-plan\n\nPath: `potpie/context-engine/src/potpie_context_engine/adapters/outbound/reconciliation/skills/graph-mutation-plan/SKILL.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/potpie-ai/potpie/HEAD/potpie/context-engine/src/potpie_context_engine/adapters/outbound/reconciliation/skills/graph-mutation-plan/SKILL.md)","tokens":300,"sizeBytes":351},{"name":"marketplace.json","path":"potpie/cli/templates/claude_plugin/.claude-plugin/marketplace.json","rawUrl":"https://raw.githubusercontent.com/potpie-ai/potpie/HEAD/potpie/cli/templates/claude_plugin/.claude-plugin/marketplace.json","title":"Claude Plugin Marketplace Catalog","category":"marketplace","format":"json","content":"# Claude Plugin Marketplace Catalog\n\nPath: `potpie/cli/templates/claude_plugin/.claude-plugin/marketplace.json`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/potpie-ai/potpie/HEAD/potpie/cli/templates/claude_plugin/.claude-plugin/marketplace.json)","tokens":300,"sizeBytes":265},{"name":"plugin.json","path":"potpie/cli/templates/claude_plugin/.claude-plugin/plugin.json","rawUrl":"https://raw.githubusercontent.com/potpie-ai/potpie/HEAD/potpie/cli/templates/claude_plugin/.claude-plugin/plugin.json","title":"claude-plugin Plugin Manifest","category":"plugin-manifest","format":"json","content":"# claude-plugin Plugin Manifest\n\nPath: `potpie/cli/templates/claude_plugin/.claude-plugin/plugin.json`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/potpie-ai/potpie/HEAD/potpie/cli/templates/claude_plugin/.claude-plugin/plugin.json)","tokens":300,"sizeBytes":251},{"name":"potpie-feature.md","path":"potpie/cli/templates/claude_bundle/.claude/commands/potpie-feature.md","rawUrl":"https://raw.githubusercontent.com/potpie-ai/potpie/HEAD/potpie/cli/templates/claude_bundle/.claude/commands/potpie-feature.md","title":"Command: /potpie-feature","category":"command-prompt","format":"markdown","content":"# Command: /potpie-feature\n\nPath: `potpie/cli/templates/claude_bundle/.claude/commands/potpie-feature.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/potpie-ai/potpie/HEAD/potpie/cli/templates/claude_bundle/.claude/commands/potpie-feature.md)","tokens":300,"sizeBytes":262},{"name":"potpie-record.md","path":"potpie/cli/templates/claude_bundle/.claude/commands/potpie-record.md","rawUrl":"https://raw.githubusercontent.com/potpie-ai/potpie/HEAD/potpie/cli/templates/claude_bundle/.claude/commands/potpie-record.md","title":"Command: /potpie-record","category":"command-prompt","format":"markdown","content":"# Command: /potpie-record\n\nPath: `potpie/cli/templates/claude_bundle/.claude/commands/potpie-record.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/potpie-ai/potpie/HEAD/potpie/cli/templates/claude_bundle/.claude/commands/potpie-record.md)","tokens":300,"sizeBytes":259},{"name":"potpie-feature.md","path":"potpie/cli/templates/claude_plugin/commands/potpie-feature.md","rawUrl":"https://raw.githubusercontent.com/potpie-ai/potpie/HEAD/potpie/cli/templates/claude_plugin/commands/potpie-feature.md","title":"Command: /potpie-feature","category":"command-prompt","format":"markdown","content":"# Command: /potpie-feature\n\nPath: `potpie/cli/templates/claude_plugin/commands/potpie-feature.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/potpie-ai/potpie/HEAD/potpie/cli/templates/claude_plugin/commands/potpie-feature.md)","tokens":300,"sizeBytes":246},{"name":"potpie-record.md","path":"potpie/cli/templates/claude_plugin/commands/potpie-record.md","rawUrl":"https://raw.githubusercontent.com/potpie-ai/potpie/HEAD/potpie/cli/templates/claude_plugin/commands/potpie-record.md","title":"Command: /potpie-record","category":"command-prompt","format":"markdown","content":"# Command: /potpie-record\n\nPath: `potpie/cli/templates/claude_plugin/commands/potpie-record.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/potpie-ai/potpie/HEAD/potpie/cli/templates/claude_plugin/commands/potpie-record.md)","tokens":300,"sizeBytes":243}],"systemPromptSnippet":"\n\n# potpie-change-timeline\n\nPath: `potpie/cli/templates/agent_bundle/.agents/skills/potpie-change-timeline/SKILL.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/potpie-ai/potpie/HEAD/potpie/cli/templates/agent_bundle/.agents/skills/potpie-change-timeline/SKILL.md)\n\n\n# Agents Skill\n\nPath: `potpie/cli/templates/agent_bundle/.agents/skills/potpie-cli/agents/openai.yaml`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/potpie-ai/potpie/HEAD/potpie/cli/templates/agent_bundle/.agents/skills/potpie-cli/agents/openai.yaml)\n\n\n# potpie-cli\n\nPath: `potpie/cli/templates/agent_bundle/.agents/skills/potpie-cli/SKILL.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/potpie-ai/potpie/HEAD/potpie/cli/templates/agent_bundle/.agents/skills/potpie-cli/SKILL.md)\n\n\n# potpie-debug-memory\n\nPath: `potpie/cli/templates/agent_bundle/.agents/skills/potpie-debug-memory/SKILL.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/potpie-ai/potpie/HEAD/potpie/cli/templates/agent_bundle/.agents/skills/potpie-debug-memory/SKILL.md)\n\n\n# Agents Skill\n\nPath: `potpie/cli/templates/agent_bundle/.agents/skills/potpie-graph/agents/openai.yaml`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/potpie-ai/potpie/HEAD/potpie/cli/templates/agent_bundle/.agents/skills/potpie-graph/agents/openai.yaml)\n\n\n# potpie-graph\n\nPath: `potpie/cli/templates/agent_bundle/.agents/skills/potpie-graph/SKILL.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/potpie-ai/potpie/HEAD/potpie/cli/templates/agent_bundle/.agents/skills/potpie-graph/SKILL.md)\n\n\n---\nname: potpie-infra-architecture\nversion: \"5\"\ndescription: \"Use for project infra and architecture context: environments, adapters, runtime configuration, deployments, service dependencies, datastores, API contracts, ownership, incidents, and dependency blast radius.\"\n---\n\n# Potpie Infra Architecture\n\nUse this skill when the task touches environments, adapters, deployment behavior,\nruntime config, service dependencies, production incidents, or architecture\nchanges.\n\n## Fast Path\n\nShare one discovery pass with other skills; reuse current reads and hook context\nfor the same task, pot, and scope. Run broad resolve and an untyped entity lookup\nconcurrently when the task names a service, environment, adapter, or dependency\nwhose canonical key is unknown. Skip the lookup when a key is already known.\nFor code changes, scoped preferences can run alongside both. Use a known\nexplicit pot selector; resolve ambiguous routing before scoped retrieval and\ncheck returned pot IDs before combining results.\n\nBroad context and conditional identity lookup:\n\n```bash\npotpie resolve \"\"\npotpie graph search-entities \"\" --limit 10\n```\n\nUse the returned canonical service key for a neighborhood when the task needs\nrelationships or resolve leaves a gap; do not guess an anchor. For a direct\nentity question, identity lookup then neighborhood can suffice without resolve.\nThe `service:` below stands for that returned key. Start with\n**no `--environment`**:\n\n```bash\npotpie graph read --subgraph infra_topology --view service_neighborhood --scope service: --depth 2 --direction both --limit 20\n```\n\nThe environment filter defaults to `qualified_only`: `--environment prod`\nalone drops every unqualified edge — `USES`, `DEFINED_IN`, `OWNED_BY` — and\nanswers \"talks to nothing\". To exclude other environments, keep them explicitly:\n\n```bash\npotpie graph read --subgraph infra_topology --view service_neighborhood --scope service:,include_unqualified_environment:true --environment --depth 2 --direction both --limit 20\n```\n\nAn empty neighborhood can mean missing relations, not a wrong key. Start with\n`--depth 2 --direction both`; `--direction` accepts `out`, `in` or `both`, and\nany other spelling is refused. A `--depth` past the view's maximum runs at the\nmaximum and says so. Alternatively, for\neverything the graph holds about one service — decisions, preferences, timeline\nand features beside the topology — use one flat list:\n\n```bash\npotpie graph neighborhood --entity service: --detail summary --limit 20\n```\n\nChoose the neighborhood that answers the question; do not automatically run\nboth. Fetch already-discovered document chunks with `potpie resource get`\nconcurrently with neighborhood reads, and stop expanding once the required\nevidence is covered. Pass `--pot ` once the pot is known.\n\n## Apply Results\n\nUse infra context for blast radius, where-to-look decisions, deployment changes,\nadapter selection, and incident debugging. Preserve environment qualifiers; a\nstaging dependency is not proof of a production dependency.\n\nLook for explicit topology facts: `DEFINED_IN`, `DEPLOYED_TO`, `DEPENDS_ON`,\n`USES`, `EXPOSES`, `HOSTED_ON`, and `OWNED_BY`.\n\n## Report Back\n\nShow the `graph read` you ran, including the `--depth`, `--limit`, and any\n`--environment` you chose. A neighborhood is only interpretable next to its\nbounds: \"nothing depends on it\" means one thing at `--depth 2` and another at\n`--depth 1`, and the reader cannot tell which you meant unless the command is on\nthe page.\n\nA neighborhood is the case a diagram was made for — draw it:\n\n```mermaid\nflowchart LR\n payments[\"payments-api (prod)\"] -->|DEPENDS_ON| ledger[\"ledger-api (prod)\"]\n payments -->|USES| pgdb[(\"payments-db\")]\n ledger -.->|USES, inferred| cache[(\"redis\")]\n```\n\nKeep the environment qualifier on the node, label every edge with its predicate,\nand dash any edge you inferred rather than read — a solid edge asserts the graph\nsays so. Blast radius is the same picture with the direction reversed. Do not\ndraw one dependency; say it in a sentence.\n\n## Record Architecture\n\nRecord only source-backed topology or carefully labeled agent inferences. Use\n`authoritative_fact` when evidence is an explicit source of truth such as\ndeployment config, service manifest, infra doc, ADR, or user statement. Use\n`agent_claim` for lower-authority interpretation.\n\nTopology edges are not a `potpie record` type; write them as a plan:\n\n```bash\npotpie graph mutation-template --kind infra-snapshot\npotpie --json graph propose --file mutation.json\npotpie --json graph commit --verify\n```\n\nReuse the keys your reads returned. Omit `graph_contract_version` from the\npayload. If `propose` answers `review_required`, ask the user, then re-run it\nwith `--approved-by ` and commit as above (or pass `--approved-by` to\nthe commit); `commit --verify` prints the plan id, readback and quality status.\n\nA decision *about* the architecture is one call:\n\n```bash\npotpie record --type decision --summary \"\" --detail rationale=\"\" --scope service:\n```\n\nEvery durable infra fact needs an environment when the fact differs by\nenvironment, evidence when available, and a retrieval-grade description.\n\nArchitecture capture is harness-led: inspect authoritative sources and write\nsemantic facts. Do not use scanner-driven graph updates or infer topology from\ndirectory names, imports, or package files alone.\n\n## Protocol definitions and codecs\n\nWhen the source or question concerns telegrams, message layouts, field/value\nmeanings, revisions or decoder changes, check the catalog for\n`protocols.message_context` and, when it is advertised, follow\n[the shared protocol reference](../potpie-graph/references/protocols.md). The\nextension is opt-in (`potpie config set graph.protocols on`), so a catalog\nwithout it means protocol memory is off. Use explicit protocol reads alongside\nexisting Service/CodeAsset context. Preserve immutable source evidence and\npartial coverage; capabilities do not establish traffic.\n\n\n---\nname: potpie-source-ingestion\nversion: \"5\"\ndescription: \"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. Document payloads (PDF, spreadsheet, markdown/HTML) route through the per-format potpie-resource-* skills and `potpie resource import`.\"\n---\n\n# Potpie Source Ingestion\n\nUse this skill for explicit ingestion requests. The harness is the intelligence:\nit gathers source data, reads it, decides what is durable, resolves identity, and\nwrites semantic graph mutations with evidence. Potpie validates and stores; it\ndoes not decide what source material means.\n\n## Non-Negotiables\n\n- Use a todo/checklist for every repository or multi-source ingestion. Do not\n jump directly from a README to graph writes.\n- Local inspection is required for repo understanding. Scanner-driven graph\n updates are forbidden. Inspect files with `rg`, `rg --files`, `git`, and\n structured tooling; do not run legacy or deterministic ingestion/scanner\n commands that walk the tree and write graph facts.\n- Use subagents only for read-only discovery slices. The main agent owns source\n selection, identity resolution, mutation proposals, commits, and final\n synthesis.\n- Do not write until each required discovery lane is complete, explicitly\n unavailable, or intentionally scoped out by the user.\n- Every write needs source refs, source authority, truth class, confidence,\n compact summary, and retrieval-grade description.\n\n## Phase 0: Scope And Preflight\n\n1. Define source kind, pot/project, repo/path/URL, time window, and target memory\n shape: baseline, history, docs, infra, debug memory, preferences, or all.\n2. Verify Potpie scope and graph availability with one call:\n\n```bash\npotpie status\n```\n\nIt reports the daemon, the active pot, backend readiness and claim counts;\nevery later read names the pot it used in its header, so do not pre-read\n`pot info`, `source list` or `graph status`. Pass `--pot ` on later\ncalls once the pot is known.\n\n3. If the repo is not registered, register metadata only. Use explicit `--pot`\n when pot scope is ambiguous:\n\n```bash\npotpie source add repo . --pot \n```\n\n4. Inspect the full destination ontology before selecting mutation shapes:\n\n```bash\npotpie --json graph catalog --profile full --pot \n```\n\nRead the [ontology selection guidance](../potpie-graph/SKILL.md#ontology-selection)\nto distinguish facts, decisions, policies, events, and source material. Reuse\nthis catalog during the task; `--profile read` omits the ontology. Select from\nall supported entities and predicates, then use templates for payload shape.\nThe templates are examples, not an exhaustive list of relationships.\n`graph describe --examples` carries read examples only.\n\n```bash\npotpie graph mutation-template --kind repo-baseline\npotpie graph mutation-template --kind infra-snapshot\npotpie graph mutation-template --kind timeline-change\npotpie graph mutation-template --kind preference-policy\npotpie graph mutation-template --kind bug-fix\n```\n\n5. If the CLI is unavailable or broken, continue discovery, build the proposed\n evidence matrix, and stop before committing graph writes.\n\n## Phase 1: Todo Plan\n\nCreate and maintain todos with at least these lanes for repository ingestion:\n\n- Scope, pot, source registration, and graph contract preflight.\n- Product/docs: README, docs, ADRs, runbooks, public docs, linked websites.\n- Local repo map: manifests, packages/apps, entrypoints, route/API surfaces,\n tests, framework config, major modules, generated/API specs.\n- Runtime/deploy: Dockerfiles, compose, Kubernetes, Terraform, CI workflows,\n deploy scripts, environment templates, feature flags.\n- API/data/integrations: service clients, adapters, datastores, models,\n queues, auth providers, external APIs.\n- GitHub/history: repo metadata, topics, releases/tags, recent merged PRs, open\n issues, linked tickets/docs, CI/deploy records.\n- Preferences/workflows: explicit coding style, test commands, local dev setup,\n release/deploy/runbook workflows.\n- Synthesis: evidence matrix, candidate graph facts, identity resolution,\n proposal, verified commit, and gate-driven follow-up checks.\n\nUpdate todos as lanes finish. Preserve uncertain findings for the inbox instead\nof forcing them into canonical graph claims.\n\n## Phase 2: Parallel Discovery\n\nParallelize independent read-only slices when tools allow it. Recommended\nsubagent prompts:\n\n- Docs/product: \"Read README, docs, ADRs, runbooks, package metadata, and linked\n product pages. Return product purpose, features, explicit decisions,\n preferences, workflows, and source refs. Do not write mutations.\"\n- Local architecture: \"Inspect manifests, top-level apps/packages, entrypoints,\n route/API surfaces, tests, and framework config. Return service/module map,\n likely features, explicit source files, uncertainty, and no mutations.\"\n- Runtime/deploy: \"Inspect Docker/compose/Kubernetes/Terraform/CI/deploy/env\n templates. Return environments, deploy shape, config variables, workflows,\n datastores, and source refs. Do not write mutations.\"\n- API/data/integrations: \"Inspect route specs, client/adapters, models,\n datastores, queues, auth, and external integrations. Return candidate\n APIContract/DataStore/Adapter/Dependency facts with evidence. No mutations.\"\n- GitHub history: \"Use GitHub tools/CLI for repo metadata, releases, recent\n merged PRs, open issues, linked tickets/docs, and CI signal. Return timeline,\n fixes, decisions, bug patterns, and source refs. No mutations.\"\n- Preferences: \"Find explicit preferences in docs, config, tests, contribution\n guides, PR templates, and comments. Return only explicit reusable policies\n with evidence. No mutations.\"\n\nThe main agent should continue non-overlapping discovery while subagents run.\n\n## Phase 3: Local Repo Inspection Targets\n\nUse structured, bounded local inspection. Examples:\n\n```bash\nrg --files -g 'README*' -g 'docs/**' -g '*ADR*' -g 'package.json' -g 'pyproject.toml' -g 'Cargo.toml' -g 'go.mod'\nrg --files -g 'Dockerfile*' -g 'docker-compose*' -g '.github/workflows/**' -g '*.tf' -g 'k8s/**' -g '.env*'\nrg -n \"FastAPI|APIRouter|express\\\\(|router\\\\.|Django|Flask|NextResponse|route\\\\(\" .\nrg -n \"postgres|mysql|redis|mongo|s3|kafka|rabbit|queue|oauth|stripe|slack|github|linear|jira\" .\nrg -n \"pytest|vitest|jest|playwright|make test|npm test|uv run|cargo test\" README* docs .github pyproject.toml package.json Makefile\n```\n\nDo not infer durable facts from filenames alone. Use files to locate sources of\ntruth, then read the relevant snippets or authored docs.\n\n## Phase 4: Hosted/GitHub Hydration\n\nUse the agent's integration tools/connectors, including GitHub app/MCP/CLI\ntools when available, not Potpie queue ingestion commands. For GitHub-backed\nrepo ingestion, gather the items below. Do not use Potpie CLI queue ingestion.\n\n- Repository metadata: full name, default branch, description, topics,\n visibility, homepage, license, archived/fork status.\n- Documentation: README, contributing guide, CODEOWNERS, PR/issue templates,\n docs linked from the repo.\n- Releases/tags when they describe shipped behavior or deploy cadence.\n- Recent merged PRs: title, body, author, merged date, branch, labels, linked\n issues, changed filenames; fetch patches only when author text is insufficient.\n- Open/high-signal issues: title, body, labels, state, author, comments when\n available; issues can record requests/bugs but do not prove fixes.\n- CI/workflows: workflow files and failed/passing runs only when relevant to\n durable workflows, release process, or recurring failures.\n- Linked systems: Linear/Jira/Confluence/Slack/docs mentioned in repo, PRs, or\n issues when corresponding tools are available.\n\nRespect API limits and user scope. Prefer recent/high-signal items over\nexhaustive pagination unless the user explicitly asks for full history.\n\n## Phase 5: Evidence Matrix\n\nBefore writing, build a compact matrix:\n\n| Candidate | Entity types + predicate + direction | Source refs | Authority | Truth class | Confidence | Action |\n|---|---|---|---|---|---|---|\n| Worker uses Redis | Service → USES → DataStore | file/doc locator | authoritative_code | authoritative_fact | 0.95 | commit / inbox / skip |\n\nSelect type/predicate from the inspected catalog and record the intended read\nthat should retrieve the fact. Classify meaning independently of authority:\na source-backed behavior is not a preference, and `feature_note` is not a\nsubstitute for a `Feature` with its supported relations.\n\nGuidelines:\n\n- Use `authoritative_fact` for explicit docs/config/code ownership facts.\n- Use `source_observation` for observed source material that may not be policy.\n- Use `agent_claim` for lower-authority synthesis from multiple weak signals.\n- Use `preference` only for explicit reusable project preferences.\n- Use `timeline_event` for source-time activity from PRs, tickets, releases, or\n deployments.\n- Put uncertain but potentially useful findings into `graph inbox add`.\n\n## Phase 6: Identity Resolution\n\nResolve before linking — one untyped search per entity you intend to link and\nhave not already seen in a read (a wrong `--type` guess returns nothing);\nnarrow by `--source-ref` for tickets and PRs:\n\n```bash\npotpie graph search-entities \"\" --limit 10\npotpie graph search-entities \"\" --source-ref --limit 10\n```\n\nReuse canonical keys. If duplicate candidates appear, stop and use inbox or a\nreview-required correction flow; do not create near-duplicate entities.\n\n## Phase 7: Write\n\nAuthor semantic mutation JSON from the `graph mutation-template` skeletons\nprinted in Phase 0; `propose` validates against the live contract and names\nevery rejected operation by index. Omit `graph_contract_version` from the\npayload. Use the full catalog inspected in Phase 0 for relationships absent\nfrom the templates. Refresh it if the destination or contract changes.\n\n```bash\npotpie --json graph propose --file mutation.json\n```\n\nInspect proposal status, diff, warnings, rejected operations, conflicts, and\nreview flags:\n\n- `invalid` or rejected operations: fix the mutation or skip the weak fact.\n- `conflict` or duplicate risk: resolve identity or use inbox.\n- `review_required`: ask for approval, then re-run\n `potpie --json graph propose --file mutation.json --approved-by `\n and commit with `--verify`, or commit the plan you have with\n `potpie --json graph commit --approved-by --verify`;\n `commit` without an approval answers `review_required` again.\n- `validated` / low-risk: commit with `--verify`.\n\n```bash\npotpie --json graph commit --verify\n```\n\n`commit --verify` prints the plan id, readback and quality status;\n`graph history --plan ` is for later inspection.\n\nFor large batches of agent-authored mutations, use `graph bulk apply` with\ndry-run, chunking, manifest, and verify. Bulk apply must only apply facts the\nharness already selected.\n\n## Phase 8: Verify And Quality Gate\n\n`graph commit --verify` reads back committed claims and checks quality. When it\nwarns or fails, drill down with affected reads and quality reports:\n\n```bash\npotpie graph read --subgraph features --view feature_context --scope anchor_entity_key: --limit 50\npotpie graph read --subgraph infra_topology --view service_neighborhood --scope service: --depth 2 --direction both --limit 50\npotpie graph read --subgraph recent_changes --view timeline --scope repo: --limit 50 --format table\npotpie --json graph quality duplicate-candidates --limit 20\npotpie --json graph quality low-confidence --limit 20\npotpie --json graph quality conflicting-claims --limit 20\npotpie --json graph quality orphan-entities --limit 20\n```\n\nVerify the selected representation as well as persistence: read each affected\nfamily and confirm the intended typed relationships and evidence. A valid plan\nor passing quality report cannot establish that factual prose belongs under\n`POLICY_APPLIES_TO`. If a fact is stored but absent from its intended read,\ninspect its type, relation, and scope before adding another claim.\nIf the verified commit misses expected facts, fix the mutation or record an inbox item.\nReport what was ingested, what was skipped, and what remains uncertain.\n\nReport it with the commands, not as prose alone: the `propose` and\n`commit --verify` you ran, the `plan_id` they returned, and the verify outcome.\nAn ingestion the reader cannot re-open with `graph history --plan ` is\none they have to take on trust, and the whole point of the verified gate is that\nthey do not have to. Name the reads that came back empty as well — they are why\na slice of the evidence matrix stayed thin.\n\nWhen the ingested source described a topology — a service map, a deploy shape, a\nset of dependencies — draw what you wrote as a mermaid ` ```mermaid ` /\n`flowchart LR` block, using the same entity keys and predicates that went into\nthe mutation, so the picture and the graph can be compared line by line. Nothing else here is a shape: counts, skipped\nsources, and open questions belong in a list.\n\n## Repository Baseline\n\nFor repository ingestion, run baseline before change history. Use\n`potpie-repo-baseline` in deep mode when the user asks to ingest or understand a\nrepo deeply. Record source-backed purpose, application type, features,\nservice/module map, API contracts, datastores, integrations, environments,\ndeploy shape, ownership, and explicit project preferences. Then use\n`potpie-change-timeline` for recent or historical activity. Do not infer\nbaseline architecture from PR titles or issue status.\n\nRepresent capabilities as `Feature` entities. Link repositories or services to\nfeatures with `PROVIDES`, and use `IMPLEMENTED_IN` only when a source locates\nthe implementation.\n\n## Document Payloads\n\nWhen a source is a document whose *content* must stay searchable and citable —\na PDF, a spreadsheet, a long markdown/HTML doc, an exported wiki page — do not\npaste its body into summaries, descriptions, or claims. Payloads never enter\nthe graph. Use the matching per-format skill (`potpie-resource-pdf`,\n`potpie-resource-spreadsheet`, `potpie-resource-markdown`): you write an\nextraction script, the script emits a chunk directory, and\n`potpie resource import` stores the bytes and writes the Document/section\nstructure to the graph. Agent-authored section summaries index each section\nfor graph context, and the resource index searches the chunk text. Then link\ncoverage with `DOCUMENTS` claims, and for structured data derive the durable\nfacts as ordinary claims citing `potpie://res/...` chunk ids as evidence. Facts\na document *states* (decisions, preferences, infra) are still recorded as\nnormal graph claims under the rules below — the resource store holds the\nevidence payload, not the conclusions.\n\nA document is not a registrable source: `source add` refuses a document kind\nwith `source_kind_is_a_document`. When only a pointer is wanted and the text\nneed not be searchable, a `doc_reference` record whose summary says what the\ndocument covers is enough.\n\n## Source Rules\n\n- Tickets and issues can record timeline events, bug patterns, decisions, and\n docs. They do not prove a fix unless tied to a merged PR, commit, deployment,\n or explicit shipped-resolution source.\n- Documents can record preferences, decisions, runbook notes, service notes, and\n infra facts only when they explicitly say them. Their payloads belong in the\n resource store (see Document Payloads above), never in graph properties.\n- Logs and transcripts can record diagnostic signals, investigations, fixes, and\n verifications. Keep raw logs out of descriptions except for short distinctive\n error text.\n\n## Protocol definitions and codecs\n\nWhen the source or question concerns telegrams, message layouts, field/value\nmeanings, revisions or decoder changes, check the catalog for\n`protocols.message_context` and, when it is advertised, follow\n[the shared protocol reference](../potpie-graph/references/protocols.md). The\nextension is opt-in (`potpie config set graph.protocols on`), so a catalog\nwithout it means protocol memory is off. Use explicit protocol reads alongside\nexisting Service/CodeAsset context. Preserve immutable source evidence and\npartial coverage; capabilities do not establish traffic.\n\n\n# backfill-enumerate-drain\n\nPath: `potpie/context-engine/src/potpie_context_engine/adapters/outbound/reconciliation/skills/backfill-enumerate-drain/SKILL.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/potpie-ai/potpie/HEAD/potpie/context-engine/src/potpie_context_engine/adapters/outbound/reconciliation/skills/backfill-enumerate-drain/SKILL.md)\n\n\n# graph-mutation-plan\n\nPath: `potpie/context-engine/src/potpie_context_engine/adapters/outbound/reconciliation/skills/graph-mutation-plan/SKILL.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/potpie-ai/potpie/HEAD/potpie/context-engine/src/potpie_context_engine/adapters/outbound/reconciliation/skills/graph-mutation-plan/SKILL.md)\n\n\n# Claude Plugin Marketplace Catalog\n\nPath: `potpie/cli/templates/claude_plugin/.claude-plugin/marketplace.json`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/potpie-ai/potpie/HEAD/potpie/cli/templates/claude_plugin/.claude-plugin/marketplace.json)\n\n\n# claude-plugin Plugin Manifest\n\nPath: `potpie/cli/templates/claude_plugin/.claude-plugin/plugin.json`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/potpie-ai/potpie/HEAD/potpie/cli/templates/claude_plugin/.claude-plugin/plugin.json)\n\n\n# Command: /potpie-feature\n\nPath: `potpie/cli/templates/claude_bundle/.claude/commands/potpie-feature.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/potpie-ai/potpie/HEAD/potpie/cli/templates/claude_bundle/.claude/commands/potpie-feature.md)\n\n\n# Command: /potpie-record\n\nPath: `potpie/cli/templates/claude_bundle/.claude/commands/potpie-record.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/potpie-ai/potpie/HEAD/potpie/cli/templates/claude_bundle/.claude/commands/potpie-record.md)\n\n\n# Command: /potpie-feature\n\nPath: `potpie/cli/templates/claude_plugin/commands/potpie-feature.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/potpie-ai/potpie/HEAD/potpie/cli/templates/claude_plugin/commands/potpie-feature.md)\n\n\n# Command: /potpie-record\n\nPath: `potpie/cli/templates/claude_plugin/commands/potpie-record.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/potpie-ai/potpie/HEAD/potpie/cli/templates/claude_plugin/commands/potpie-record.md)\n"}