Cosmos

Use This Skill When

• Modifying cosmos/cli/*, cosmos/sdk/*, cosmos/ffmpeg/*, cosmos/crop/*, cosmos/ingest/*, or provenance schemas/emitters.
• Designing or reviewing CLI surfaces (--json/--plain, exit mapping, prompt behavior, flag naming).
• Planning release choreography, skill freshness audits, or agent-facing workflows.
• Investigating downstream compatibility and provenance joins.

Intent Router (Progressive Disclosure)

Load only what you need for the request:

1. Command/API contract questions -> references/api-surfaces.md
2. Module ownership/runtime behavior questions -> references/architecture.md
3. "How do I run this end-to-end?" -> references/workflows.md
4. Cross-repo compatibility or migration risk -> references/integration-notes.md
5. Release prep/skill freshness audit -> references/maintenance-ritual.md

First Steps

1. Read AGENTS.md in this repo.
2. Read CONTRIBUTING.md for contributor setup, bootstrap, and canonical quality-gate commands.
3. Use the router above and open only the minimum relevant reference file(s).
4. Capture command-surface receipts for touched surfaces with uv run cosmos ... --help.
5. Run the canonical quality gate before handoff: make check.

Working Rules

• Route contributors to CONTRIBUTING.md and dev/scripts/bootstrap-dev.sh instead of repeating setup steps in ad hoc notes.
• Keep one CLI (cosmos) and one SDK (cosmos.sdk) mental model; route business logic through SDK layers.
• Use cosmos process as the canonical ingest -> optional crop workflow surface.
• Preserve create-cli contracts: stable flag naming, explicit --json/--plain, and non-interactive safety flags (--yes/--no-input) on commands that expose prompts.
• Keep explicit user overrides authoritative (for example forced encoder should fail loudly, not silently degrade).
• Preserve crop semantics (offset_x/offset_y in [-1, 1]; rect clamp/even-round behavior).
• Keep provenance contracts and join key stable (view.source.sha256 == clip.output.sha256).
• Use shared ffmpeg helpers in cosmos/ffmpeg/* rather than shelling ad hoc ffmpeg/ffprobe commands.
• Use make check as the canonical local gate, and refresh uv.lock with uv lock whenever dependency metadata changes.

Current Scope Snapshot

• M1 adapter architecture: IngestAdapter contract + cosm/generic-media adapters + auto-detect/override flow.
• M2 lineage graph surfaces: SDK index traversal + CLI query commands for upstream/downstream/chain/tree.
• M3 determinism policy: profile model (strict|balanced|throughput) threaded through ingest/crop/optimize and provenance.

References

• references/workflows.md -- canonical agent workflows and copy/paste command recipes.
• references/api-surfaces.md -- CLI + SDK contract surfaces and compatibility expectations.
• references/architecture.md -- module map and runtime flow.
• references/integration-notes.md -- downstream integration and compatibility constraints.
• references/maintenance-ritual.md -- required skill freshness process for feature/release work.
• references/follow-on-issue-drafts.md -- backlog-ready issue scopes for larger follow-ons.