Skip to content

AGENTS.md

Latest commit

 

History

History
120 lines (86 loc) · 4.58 KB

AGENTS.md

File metadata and controls

120 lines (86 loc) · 4.58 KB
Raw

CloudScope Data — Agent Instructions

Repository role

cloudscope-data is an independent Git repository holding sample datasets and a catalog for AcqStore and CloudScope. It is a data/catalog repository, not a Python product package (there is no pyproject.toml and no installable source).

  • Catalog: catalog.json (source of truth for available samples)
  • Helper scripts: scripts/ (build_sample_archive.py, validate_catalog.py)
  • Local sample folders: data/, data-samples/
  • Generated archives: dist/ (ignored)

AcqStore discovers samples from catalog.json on the main branch. Large sample ZIPs are published as GitHub Release assets, not committed here. CloudScope uses the AcqStore sample-data API and does not maintain its own dataset registry.

Coexistence note: This file is the primary instruction file when this repo is the working root (e.g. a Codex project with cloudscope-data/ primary). When this repo is opened as part of the outer cs_project/ workspace (e.g. in Cursor), the outer cs_project/AGENTS.md provides workspace-wide guidance and takes precedence for cross-repo scope; this file stays repo-local and must not contradict it. cloudscope-data is sample/catalog data, not product source.

Attached sibling repositories

Repository Local path Relationship
AcqStore ../acqstore/ Consumes samples via the sample-data API / catalog URL
CloudScope App ../cloudscope-app/ Uses AcqStore's sample-data API

Do not add Python package dependencies here, and do not import this repo as a package. Coordination with acqstore is via catalog.json and release assets, not code imports.

What lives here (and what does not)

Put here:

  • catalog entries in catalog.json;
  • small, reviewable helper scripts under scripts/;
  • documentation of the catalog format in README.md (when explicitly requested).

Do not put here:

  • application, backend, widget, or server source code;
  • large binary datasets committed to git (use Release assets instead).

Catalog discipline (source of truth)

catalog.json is an ordered JSON list; list order is the client display order.

  • Preserve valid JSON and the existing entry shape (id, label, description, url, sha256, and folder/file fields as already used).
  • When adding or changing an entry, keep url pointing at a published Release asset and set the correct sha256 for that asset.
  • Do not reorder entries unless the task asks (order is user-visible).
  • After editing the catalog, validate it:
python scripts/validate_catalog.py
  • To (re)build a sample archive, use:
python scripts/build_sample_archive.py

Generated ZIPs go to the ignored dist/. If a script needs dependencies, ask before adding a tool/environment; there is no uv project here by default.

Default task scope

Work only in cloudscope-data unless the task explicitly includes another repository.

  • Make the smallest change that satisfies the request.
  • Do not commit large data files to git; prefer Release assets.
  • Do not add or change tooling/dependencies without asking first.
  • Ask a focused question, with a recommended answer, when a material decision (dataset identity, checksum source, URL target) is ambiguous.

Verification

  • Catalog changes: run scripts/validate_catalog.py and confirm it passes.
  • Checksums: confirm sha256 matches the actual published asset; do not guess a hash. If you cannot compute it against the real asset, say so and stop.
  • Script changes: run the script on a small sample and report output; do not claim success for asset publishing you did not perform.

Documentation and ticket reports

Do not update README.md unless the task explicitly requests a README change.

This repo has no docs-dev/cursor_tickets/ by default. Do not create ticket reports here unless the user explicitly asks; tracked implementation work is normally reported in the product repo it affects (e.g. acqstore).

Search exclusions

Unless the task explicitly requires them, do not inspect or search:

  • __pycache__/ and tool caches;
  • dist/ and tmp/ (generated / ignored);
  • committed sample archives and large binary data under data/ and data-samples/ (edit catalog metadata, not the binaries, unless asked);
  • .git/.

Git discipline

This directory is an independent Git repository.

  • Check git status before and after material work.
  • Preserve unrelated user changes.
  • Do not commit, push, create branches, tags, or Releases unless explicitly requested.
  • Never commit large datasets; keep them as Release assets referenced from catalog.json.