pkgxray: Instructions file for Claude Code

Project

This repository is managed with swamp.

Rules

1. Search before you build. When automating AWS, APIs, or any external service: (a) search community extensions with swamp extension search <query> — prefer @swamp/* official extensions first, (b) search local/installed types with swamp model type search <query>, (c) if a community extension exists, install it with swamp extension pull <package> instead of building from scratch, (d) extend an existing type if it covers the domain but lacks the method you need, (e) only create a custom extension model in extensions/models/ as a last resort. Use the swamp skill for guidance. The command/shell model is ONLY for ad-hoc one-off shell commands, NEVER for wrapping CLI tools or building integrations.
2. Extend, don't be clever. When a model covers the domain but lacks the method you need, extend it with export const extension — don't bypass it with shell scripts, CLI tools, or multi-step hacks. One method, one purpose. Use swamp model type describe <type> --json to check available methods.
3. Use the data model. Once data exists in a model (via lookup, start, sync, etc.), reference it with CEL expressions. Don't re-fetch data that's already available.
4. CEL expressions everywhere. Wire models together with CEL expressions. Always prefer data.latest("<name>", "<dataName>").attributes.<field> over the deprecated model.<name>.resource.<spec>.<instance>.attributes.<field> pattern.
5. Verify before destructive operations. Always swamp model get <name> --json and verify resource IDs before running delete/stop/destroy methods.
6. Prefer fan-out methods over loops. When operating on multiple targets, use a single method that handles all targets internally (factory pattern) rather than looping N separate swamp model method run calls against the same model. Multiple parallel calls against the same model contend on the per-model lock, causing timeouts. A single fan-out method acquires the lock once and produces all outputs in one execution. Check swamp model type describe for methods that accept filters or produce multiple outputs.
7. Extension npm deps are bundled, not lockfile-tracked. Swamp's bundler inlines all npm packages (except zod) into extension bundles at bundle time. deno.lock and package.json do NOT cover extension model dependencies — this is by design. Always pin explicit versions in npm: import specifiers (e.g., npm:[email protected]).
8. Reports for reusable data pipelines. When the task involves building a repeatable pipeline to transform, aggregate, or analyze model output (security reports, cost analysis, compliance checks, summaries), create a report extension. Use the swamp skill for guidance.
9. "Workflow" means a swamp workflow. In this repository the word "workflow" (and "create/run/execute/validate/debug workflow", "automate", "orchestrate", "automated/nightly job") refers to a swamp workflow — a declarative YAML DAG of model-method steps authored via swamp workflow create. Load and follow the swamp skill for these requests. Do NOT interpret these as a request to build an agent task list, spin up worktrees, or schedule a cron/remote agent. Only use those orchestration mechanisms when the user explicitly names one (e.g. "task list", "subagent", "worktree", "cron", "remote agent") or explicitly asks you to do the work yourself step by step rather than author a swamp workflow.
10. Use swamp, don't bypass it. Always work through swamp commands — don't go around them with raw shell tools. Use swamp data query to find data, not grep/find on .swamp/ files. Use model methods to interact with resources, not curl/aws/gcloud/kubectl when a model type already wraps that API — check with swamp model type search. Use swamp help for CLI discovery, not guesswork. Composing with swamp output is fine (e.g. piping --json through jq) — the anti-pattern is bypassing swamp entirely.