Skip to content

AGENTS.md

Latest commit

 

History

History
176 lines (124 loc) · 13 KB

AGENTS.md

File metadata and controls

176 lines (124 loc) · 13 KB
Raw

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 behavior 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 behavior in extensions/models/ as a last resort. Use the swamp skill for guidance. The command/shell behavior 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 behavior 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 behavior type describe <type> --json to check available methods.
  3. Use the data model. Once data exists in a behavior (via lookup, start, sync, etc.), reference it with CEL expressions. Don't re-fetch data that's already available.
  4. CEL expressions everywhere. Wire behaviors 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 behavior 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 behavior run calls against the same behavior. Multiple parallel calls against the same behavior contend on the per-behavior lock, causing timeouts. A single fan-out method acquires the lock once and produces all outputs in one execution. Check swamp behavior type describe for methods that accept filters or produce multiple outputs.
  7. Extension npm deps are bundled; pin them. Swamp's bundler inlines all npm packages (except zod) into extension bundles at bundle time. When the extension has a deno.json, the deno.lock beside it decides which versions are bundled; otherwise the registry's current release does. Always pin explicit versions in npm: and jsr: import specifiers (e.g., npm:lodash-es@4.17.21) — swamp extension push warns on unpinned and range specifiers.
  8. Reports for reusable data pipelines. When the task involves building a repeatable pipeline to transform, aggregate, or analyze behavior 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 behavior-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 behavior methods to interact with resources, not curl/aws/gcloud/kubectl when a behavior type already wraps that API — check with swamp behavior 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.
  11. Inspect reports after failures. When a behavior method or workflow run fails, inspect its generated reports before retrying or changing definitions. Reports run even on failure and capture structured diagnostics — error messages, execution status, arguments, and data output pointers. Use swamp report get @swamp/method-summary --model <model> --json for method failures or swamp report get @swamp/workflow-summary --workflow <workflow> --json for workflow failures. Run swamp help report get to confirm current retrieval syntax.

Skills

IMPORTANT: Always load swamp skills, even when in plan mode. The skills provide essential context for working with this repository.

  • swamp - Swamp CLI — behaviors, workflows, data, vaults, extensions, publishing, repos, reports, issues, and troubleshooting
  • swamp-getting-started - Interactive onboarding for new swamp users

Getting Started

If you were asked to read a task brief under tasks/ (a file whose first line is <!-- swamp start brief v1 -->), read that brief, then invoke the swamp-getting-started skill and follow it from its brief entry point.

If the user is new to swamp or asks to get started, or a swamp command you run shows this repository has no behaviors yet, invoke the swamp-getting-started skill. It checks for existing behaviors itself and walks new users through an interactive onboarding tutorial.

Otherwise, use the swamp skill to work with swamp behaviors.

Commands

Use swamp --help to see available commands. For a machine-readable JSON schema of the CLI (commands, options, arguments) intended for agent consumption, run swamp help [<command>...] — e.g. swamp help returns the full tree, and swamp help behavior run scopes to a subtree.

Behaviors (formerly models) are managed with swamp behavior — e.g. swamp behavior run <name> <method> (or swamp behavior run @<type> <method> <name> to run against a type directly). Every swamp model … spelling remains supported.

Repository Guidelines

Project Structure & Module Organization

This repository is a utility-script collection, not a single packaged application. Top-level directories group scripts by domain:

  • gis/: GIS, ArcGIS, GDAL, QGIS, DEM, and geospatial conversion tools.
  • arcplus/: ArcGIS helper modules and toolbox scripts.
  • tools/: ready-to-run general utilities; see tools/Readme.md.
  • register-python/: Windows Python registry inspection and registration helpers.
  • other/: assorted Windows, shell, PDF, media, and admin scripts.
  • video/: video-processing helpers such as poster-frame extraction.
  • Lib/: reusable Python helpers.

Keep new scripts near related tools. If a script needs sample data, fixtures, or screenshots, place them in a local samples/, assets/, or clearly named sibling directory.

Build, Test, and Development Commands

There is no repository-wide build or test command. Run tools directly from their directory and document any new dependencies beside the script.

  • uv run tools/gitignore_to_fossil.py: run a Python utility with uv.
  • python video/extract_poster_frames.py --help: inspect script usage.
  • powershell -File win-remote-reboot.ps1: run a PowerShell script.
  • cmd /c other\bats\search-path.bat: run a Windows batch helper.
  • pip install -r other/pdf-extract/requirements.txt: install dependencies for the PDF extraction tools.

Avoid adding root-level package tooling unless it applies to the whole repository.

Coding Style & Naming Conventions

Match the style of the directory you edit. Python scripts generally use 4-space indentation, descriptive snake_case names, and standard-library-first imports. PowerShell scripts use verb-noun names where practical, such as Install-* or Update-*. Batch and shell scripts should keep command side effects explicit and include short usage comments when arguments are not obvious.

Prefer portable paths in documentation, but preserve Windows-specific behavior in scripts that target Windows administration or ArcGIS Desktop workflows.

Testing Guidelines

No shared test framework is configured. For changes, perform the smallest safe verification: run --help, execute against sample input, or dry-run the external command where supported. For GIS and registry tools, document required software, privileges, and manual verification steps in the script header or local README.

Commit & Pull Request Guidelines

Recent history uses short imperative or scoped messages, for example script: Install GDAL..., refactor: replace VPN toggle..., and wip: extract stills from video. Prefer concise commit subjects that name the affected tool or intent.

Pull requests should describe the changed script, expected environment, verification performed, and any required external tools such as ArcGIS, GDAL, QGIS, uv, or Windows PowerShell. Include screenshots only for visual GIS or UI-facing documentation changes.

Beads Issue Tracker

This project uses bd (beads) for issue tracking. Run bd prime to see full workflow context and commands.

Quick Reference

bd ready              # Find available work
bd show <id>          # View issue details
bd update <id> --claim  # Claim work
bd close <id>         # Complete work

Rules

  • Use bd for ALL task tracking — do NOT use TodoWrite, TaskCreate, or markdown TODO lists
  • Run bd prime for detailed command reference and session close protocol
  • Use bd remember for persistent knowledge — do NOT use MEMORY.md files

Architecture in one line: issues live in a local Dolt DB; sync uses refs/dolt/data on your git remote; .beads/issues.jsonl is a passive export. See https://github.com/gastownhall/beads/blob/main/docs/SYNC_CONCEPTS.md for details and anti-patterns.

Agent Context Profiles

The managed Beads block is task-tracking guidance, not permission to override repository, user, or orchestrator instructions.

  • Conservative (default): Use bd for task tracking. Do not run git commits, git pushes, or Dolt remote sync unless explicitly asked. At handoff, report changed files, validation, and suggested next commands.
  • Minimal: Keep tool instruction files as pointers to bd prime; use the same conservative git policy unless active instructions say otherwise.
  • Team-maintainer: Only when the repository explicitly opts in, agents may close beads, run quality gates, commit, and push as part of session close. A current "do not commit" or "do not push" instruction still wins.

Session Completion

This protocol applies when ending a Beads implementation workflow. It is subordinate to explicit user, repository, and orchestrator instructions.

  1. File issues for remaining work - Create beads for anything that needs follow-up
  2. Run quality gates (if code changed) - Tests, linters, builds
  3. Update issue status - Close finished work, update in-progress items
  4. Handle git/sync by active profile: 
    # Conservative/minimal/default: report status and proposed commands; wait for approval.
git status

# Team-maintainer opt-in only, unless current instructions forbid it:
git pull --rebase
bd dolt push
git push
git status
  5. Hand off - Summarize changes, validation, issue status, and any blocked sync/commit/push step

Critical rules:

  • Explicit user or orchestrator instructions override this Beads block.
  • Do not commit or push without clear authority from the active profile or the current user request.
  • If a required sync or push is blocked, stop and report the exact command and error.

Beads Issue Tracker

Use Beads (bd) for durable task tracking in repositories that include it. Use the beads skill at .agents/skills/beads/SKILL.md (project install) or ~/.agents/skills/beads/SKILL.md (global install) for Beads workflow guidance, then use the bd CLI for issue operations.

Quick Reference

bd ready                # Find available work
bd show <id>            # View issue details
bd update <id> --claim  # Claim work
bd close <id>           # Complete work
bd prime                # Refresh Beads context

Rules

  • Use bd for all task tracking; do not create markdown TODO lists.
  • Run bd prime when Beads context is missing or stale. Codex 0.129.0+ can load Beads context automatically through native hooks; use /hooks to inspect or toggle them.
  • Keep persistent project memory in Beads via bd remember; do not create ad hoc memory files.

Architecture in one line: issues live in a local Dolt DB; sync uses refs/dolt/data on your git remote; .beads/issues.jsonl is a passive export. See https://github.com/gastownhall/beads/blob/main/docs/SYNC_CONCEPTS.md for details and anti-patterns.