opencode-skills-collection 4.0.66 → 4.0.68

package/bundled-skills/resumable-implementation-contracts/SKILL.md

@@ -0,0 +1,254 @@
+---
+name: resumable-implementation-contracts
+description: "Create repository-based execution contracts for multi-session implementation work, with stable task IDs, evidence, checkpoints, and exact resume state."
+category: project-management
+risk: safe
+source: self
+source_type: self
+date_added: "2026-09-19"
+author: ShianMike
+tags: [project-management, execution-contracts, checkpoints, verification, agent-workflows]
+tools: [claude, cursor, gemini, codex, antigravity]
+---
+
+# Resumable Implementation Contracts
+
+## Overview
+
+Turn a large, mostly defined implementation request into a repository contract
+that a fresh agent can read, update, verify, and resume without reconstructing
+the project from chat history. Keep stable intent separate from mutable
+execution state, and require evidence before any task is called complete.
+
+This is a tool-neutral document pattern. It does not depend on, replace, or
+configure any agent platform's built-in goal, task, plan, or project feature.
+
+This skill fills the layer between planning and execution. It does not replace
+product discovery, detailed technical design, project-wide state governance,
+or retrospective auditing.
+
+## When to Use This Skill
+
+Use it when work:
+
+- spans multiple sessions, agents, branches, or context windows;
+- has dependencies or acceptance criteria that must survive interruption;
+- needs an exact resume point rather than a narrative handoff;
+- can appear complete before runtime, artifact, UI, or test evidence exists;
+- must preserve partial work and unrelated repository changes.
+
+Skip it for a small task that can be completed and verified in one session.
+If requirements are still unsettled, resolve them before freezing the
+implementation contract.
+
+## Reuse Existing Project Documents
+
+Inspect the repository before creating files. Reuse equivalent documents and
+the project's established names when their ownership is clear. For substantial
+multi-session work, the minimum logical document set is:
+
+| Document | Owns | Must not become |
+| --- | --- | --- |
+| `IMPLEMENTATION_CONTRACT.md` | stable intent, scope, tasks, acceptance, definition of done | a live activity log |
+| `TASKS.md` | current task/subtask status, dependencies, evidence links | a second copy of the contract |
+| `CHECKPOINT.md` | authoritative current position and exact next action | a vague progress summary |
+| `DECISIONS.md` | material decisions, alternatives, and reasons | a transcript |
+| `VALIDATION.md` | checks actually run, results, evidence, and unresolved gates | a list of planned tests |
+
+These may live together under `docs/<contract-slug>/` or follow an existing
+repo layout. An existing `GOAL.md`, specification, or execution brief may own
+the contract role; do not rename it or create parallel files solely to match
+this skill.
+
+## Define Document Authority
+
+- Current owner instructions and applicable repository instructions govern
+  authorization and scope.
+- `IMPLEMENTATION_CONTRACT.md`, or its existing repository equivalent, owns
+  the implementation contract. Do not silently change it to fit the current
+  code.
+- The working tree, branch, commit, produced artifacts, and executed checks are
+  truth for implementation state.
+- The tracker files summarize that state; they do not override contrary
+  evidence on disk.
+
+When documents and reality disagree, reconcile status from evidence while
+preserving the contract's intent. Escalate any conflict that would materially
+change scope, behavior, or acceptance.
+
+## Write a Self-Contained Contract
+
+A new agent should be able to understand the work from the contract without
+the original conversation. Include only what is needed to execute correctly:
+
+1. objective and observable outcomes;
+2. current baseline and important constraints;
+3. in-scope work, exclusions, and authorization boundaries;
+4. operating rules, including interruption and validation policy;
+5. tasks with stable IDs, dependencies, acceptance, and breakpoints;
+6. final definition of done and handoff requirements.
+
+Use stable task and subtask IDs such as `T03` and `T03.2`. Never renumber them
+after execution starts; add new IDs or mark obsolete work explicitly.
+
+Each task should use this compact form:
+
+```markdown
+### T03 - <observable task outcome>
+
+- [ ] T03.1 <first implementation slice>
+- [ ] T03.2 <second implementation slice>
+
+Dependencies: T01
+
+Acceptance:
+- <observable behavior or artifact>
+- <required focused check and evidence>
+
+Breakpoint:
+- Update TASKS.md, VALIDATION.md, and CHECKPOINT.md after the accepted slice.
+```
+
+Write acceptance in pass/fail terms. File creation, code presence, or an
+agent's completion claim is not acceptance unless that is genuinely the whole
+requirement.
+
+## Read Before Acting
+
+At the start of a session or after interruption, read in this order:
+
+1. applicable repository instructions;
+2. the implementation contract;
+3. `TASKS.md`, `CHECKPOINT.md`, `DECISIONS.md`, and `VALIDATION.md`;
+4. current branch, `HEAD`, status, and relevant diff;
+5. only the code, tests, and artifacts needed for the active task.
+
+Reconcile the checkpoint with the working tree before editing. Preserve partial
+and unrelated changes. Resume the exact unfinished subtask when it is still
+valid; otherwise record why the next action changed.
+
+## Keep Writes Narrow and Durable
+
+- Change the implementation contract only when the owner changes intent or an
+  ambiguity is deliberately resolved.
+- Update `TASKS.md` when work starts, blocks, or becomes evidence-backed done.
+- Replace `CHECKPOINT.md` with the latest authoritative resume state; Git owns
+  its detailed history.
+- Add to `DECISIONS.md` only for choices that constrain later work.
+- Add to `VALIDATION.md` only after a check is actually run or explicitly
+  recorded as not run.
+- Update the checkpoint after a meaningful increment and before stopping.
+
+Do not duplicate the same mutable status across every document. Link to the
+owning record instead.
+
+## Use Evidence-Gated Status
+
+Use a small status vocabulary: `pending`, `in_progress`, `blocked`, and `done`.
+A task may become `done` only when its acceptance criteria have supporting
+evidence.
+
+For each validation record, capture:
+
+- timestamp and relevant commit or working-tree state;
+- exact command or manual procedure;
+- environment when it affects the result;
+- result, including failures and skipped checks;
+- artifact, log, screenshot, route, or report path when applicable;
+- unresolved caveats or gates.
+
+Run the smallest check that proves the current slice during implementation.
+Run broader integration or release suites at defined milestones or when the
+change's risk requires them. Never present a planned, mocked, or nominally
+successful check as observed behavior.
+
+## Make the Checkpoint Executable
+
+`CHECKPOINT.md` must let another agent continue immediately. Record:
+
+```markdown
+# Checkpoint
+
+Updated: <UTC timestamp>
+Branch / HEAD: <branch> / <commit>
+Active task: T03
+Active subtask: T03.2
+Status: in_progress
+
+Completed behavior:
+- <verified result and evidence link>
+
+Work in progress:
+- <files and partial state that must be preserved>
+
+Validation performed:
+- `<exact command>` -> <result>
+
+Blockers or uncertainties:
+- <blocker, owner, and condition for clearing it>
+
+Pre-existing or unrelated changes:
+- <paths or explicit none observed>
+
+Next exact action:
+- <one concrete edit, inspection, or command>
+
+Next verification:
+- <focused check that should follow that action>
+```
+
+Avoid next steps such as "continue implementation" or "finish tests." If the
+next agent must decide what those words mean, the checkpoint is incomplete.
+
+## Execution Loop
+
+1. Select the smallest dependency-ready task.
+2. Mark it `in_progress` and state the intended slice.
+3. Inspect the real path that owns the behavior.
+4. Make the minimum scoped change.
+5. Run focused verification and record the actual outcome.
+6. Update task status only from that evidence.
+7. Refresh the checkpoint with one exact next action.
+8. Repeat until every definition-of-done item is verified or explicitly
+  blocked.
+
+At final handoff, report completed outcomes, evidence, unresolved blockers,
+branch and commit state, and the exact next action if anything remains. Do not
+promote partial task completion into overall contract completion.
+
+## Limitations
+
+- This structure preserves execution state but cannot resolve unclear product
+  intent or choose among materially different outcomes for the owner.
+- Evidence quality depends on running checks that exercise the real behavior;
+  complete-looking documents do not prove implementation correctness.
+- Concurrent writers still need repository-level coordination to avoid
+  conflicting checkpoints and status updates.
+- The five-document layout is unnecessary overhead for small, single-session
+  tasks; reuse fewer existing documents when they provide the same ownership.
+
+## Common Failure Modes
+
+- Rewriting or renumbering task IDs after work has begun.
+- Treating checked boxes as evidence instead of linking the proof.
+- Recording only happy-path checks and losing failed attempts that constrain
+  the next decision.
+- Replaying all history instead of loading the authoritative current state.
+- Allowing implementation discoveries to silently expand the contract.
+- Running an expensive full suite after every small edit while skipping the
+  focused check that would isolate the defect.
+- Persisting credentials, tokens, private data, or sensitive command output in
+  tracking documents.
+
+## Relationship to Other Skills
+
+- Use `spec-driven-loop` when product requirements and technical design still
+  need structured discovery, freezing, and approval.
+- Use `planning-and-task-breakdown` when only an executable plan is needed.
+- Use `project-state-governor` when the need is canonical state across the
+  whole project rather than one scoped implementation effort.
+- Use `audit-agent-run-evidence` for a read-only retrospective audit of an
+  already completed run.
+
+This skill owns the compact execution contract that connects those concerns:
+stable intent, mutable progress, verification evidence, and exact resume state.

package/bundled-skills/understand-project-yylo/SKILL.md

@@ -0,0 +1,62 @@
+---
+name: understand-project-yylo
+description: Inspect the current product architecture, dependencies, and validation
+  loops before planning or implementing a requested change.
+category: project-management
+risk: safe
+source: https://github.com/yylo-dev/yylo-skills
+source_repo: yylo-dev/yylo-skills
+source_type: community
+date_added: '2026-09-19'
+license: MIT
+license_source: https://github.com/yylo-dev/yylo-skills/blob/main/LICENSE
+compatibility: Requires read access to the product worktree and the `yy` CLI for task/spec
+  reads through the canonical controller. Read-only inspection; no mutations.
+argument-hint: '[Main Task] [Constraints] [Ultimate Goal]'
+enable-shell-directives: true
+---
+
+# Understand the project
+
+1. Read `AGENTS.md`/`CLAUDE.md`, repository status, relevant source, tests, and existing product documentation in the integration or assigned feature worktree.
+2. Read related Kanban tasks and durable specs through the canonical metadata controller. Do not assume `.juno_task/plan.md` exists and do not materialize controller-private metadata in a product worktree.
+3. Trace only the dependencies and runtime paths needed for the requested goal. Use bounded parallel investigation when independent questions justify it.
+4. Report current behavior, sources of truth, affected components, risks, unknowns, and the smallest useful validation loop.
+5. If the user requested planning, hand the findings to `plan-ledger-tasks-yylo`. If implementation was requested, work only in the task worktree returned by `yy task start TASK_ID`.
+6. Write a durable operational spec only when requested or materially useful. Draft it externally, preflight the installed `yy ledger artifact` API, capture it as an immutable `report` Artifact Record with provenance/retention, and verify retrieval, digest, and history. If that API is unavailable, stop with the external draft intact; never fall back to product `docs/`, task bodies/responses, new `.juno_task/specs`, or direct controller-store edits. Product `docs/` remains reserved for documentation shipped with the product. Do not update root instructions with transient status.
+
+## Invocation contract
+
+The structured views below intentionally alias parts of the complete request; they are not additional user arguments.
+
+### Main task
+
+$1
+
+### Constraints and context
+
+$2
+
+### Complete raw request
+
+$ARGUMENTS
+
+## When to Use
+
+- Before planning or implementing a requested change, when you need current architecture, dependencies, and validation loops.
+- To hand grounded findings to `plan-ledger-tasks-yylo` (planning) or a task worktree (implementation).
+
+## Limitations
+
+- Read-only: reports current behavior, sources of truth, affected components, risks, unknowns, and the smallest validation loop - does not implement.
+- Bounded investigation only; do not materialize controller-private metadata in a product worktree.
+- Durable specs are captured as immutable Artifact Records only when the installed `yy ledger artifact` API supports it; otherwise stop with the external draft intact.
+
+### Example
+
+```bash
+yy ledger search --status todo --limit 5
+yy ledger get TASK_ID
+```
+
+> Adapted from [yylo-dev/yylo-skills](https://github.com/yylo-dev/yylo-skills) (MIT) - v2.0.1; frontmatter, When to Use/Limitations, and safety boundaries added for upstream compliance.

package/bundled-skills/weather-model-data-fetching/SKILL.md

@@ -0,0 +1,277 @@
+---
+name: weather-model-data-fetching
+description: "Retrieve numerical weather prediction data from public AWS S3 and HTTP archives using GRIB2 inventories, byte ranges, Herbie, provider fallbacks, and verified caching."
+category: data
+risk: safe
+source: self
+source_type: self
+date_added: "2026-09-18"
+author: ShianMike
+tags: [weather, grib2, aws-s3, herbie, noaa, nwp]
+tools: [claude, cursor, gemini, codex]
+---
+
+# Weather Model Data Fetching
+
+## Overview
+
+Fetch numerical weather prediction data without treating a multi-gigabyte GRIB2
+file as one indivisible download. Prefer an existing project adapter or Herbie;
+use direct object-store byte ranges only when the supported path cannot express
+the request.
+
+This skill covers transport, inventory selection, caching, and verification. It
+does not interpret the forecast or decide whether a model is meteorologically
+appropriate.
+
+## When to Use This Skill
+
+- A task needs GFS, GEFS, HRRR, RAP, NAM, IFS, or similar model output.
+- Data lives in a public AWS S3 bucket, NOMADS, or a public cloud mirror.
+- The input is GRIB2 and only selected variables or levels are needed.
+- A point, sounding, time series, map, or batch job needs a reliable fetch path.
+- A download is missing, partial, unexpectedly large, slow, or hard to resume.
+
+Do not activate this skill for ordinary weather-forecast questions that do not
+require model files.
+
+## Define the Request First
+
+Resolve these values before downloading:
+
+- model and product;
+- initialization cycle in UTC;
+- forecast hour and therefore valid time (`valid = initialization + lead`);
+- ensemble member when applicable;
+- variables, vertical levels, and surface fields;
+- point, region, or full-grid output;
+- cache location and when the downloaded data may be deleted.
+
+Confirm that the cycle is complete, the forecast hour exists for that cycle,
+and the requested location is inside the model domain. A recent `404` often
+means the cycle is not published yet; step back to a completed cycle instead of
+retrying indefinitely.
+
+## Choose the Smallest Retrieval Route
+
+1. Reuse the project's existing fetch/cache abstraction when it already handles
+   the model.
+2. Use Herbie for a supported GRIB2 model. It discovers AWS, NOMADS, Google,
+   Azure, and other configured sources and understands their key layouts.
+3. Use a provider-native point or Zarr endpoint when the task needs a tiny
+   spatial slice from many times or members.
+4. Use direct S3 or HTTPS object access when the key is known and no suitable
+   adapter exists.
+
+Do not recursively list a large public bucket to discover one run. Build the
+documented prefix for the model, cycle, product, forecast hour, and member, then
+probe that exact object and its inventory.
+
+Use an explicit provider priority and record the provider that succeeded. A
+fallback must refer to the same model run, product, member, and forecast hour;
+never silently substitute a different forecast.
+
+## Subset GRIB2 by Inventory
+
+GRIB2 files contain consecutive messages. A companion inventory such as
+`.idx`, `.grib2.idx`, or `.grb2.inv` records each message's starting byte.
+
+1. Fetch the small inventory first.
+2. Inspect its actual rows before writing a regex.
+3. Select exact variables, levels, and forecast-step records.
+4. Set each selected message's end byte to one less than the next message's
+   start; request the final selected message through EOF when no end is known.
+5. Coalesce adjacent selected messages into one range.
+6. Issue one `Range: bytes=START-END` request per range. S3 does not support
+   multiple ranges in one `GetObject` request.
+7. Require `206 Partial Content` and a matching `Content-Range`. If a server
+   answers `200`, do not append the whole object as though it were a fragment.
+8. Pin the object's length and identity (`ETag` and/or `Last-Modified`) while
+   downloading. Discard fragments if the object changes.
+9. Assemble into a temporary file, verify it with a GRIB decoder, then rename
+   atomically into the cache.
+
+A GRIB message contains one field over its grid. Message-range subsetting saves
+variables and levels, not geography. A point request still downloads the full
+grid for every selected message unless the provider offers a point, regional,
+Zarr, or other chunked endpoint.
+
+## Herbie Example
+
+Use the current `search` argument; `searchString` is deprecated. Start from the
+inventory, fail on an empty match, and keep the download directory explicit.
+
+```python
+from pathlib import Path
+
+from herbie import Herbie
+
+PRESSURE_FIELDS = (
+    r":(?:HGT|TMP|RH|SPFH|UGRD|VGRD):\d+(?:\.\d+)? mb:"
+)
+
+
+def fetch_hrrr_pressure_run(initialization, forecast_hour, cache_dir):
+    cache_dir = Path(cache_dir)
+    h = Herbie(
+        initialization,
+        model="hrrr",
+        product="prs",
+        fxx=forecast_hour,
+        priority=["aws", "nomads", "google", "azure"],
+        save_dir=cache_dir,
+        verbose=False,
+    )
+
+    selected = h.inventory(PRESSURE_FIELDS)
+    if selected.empty:
+        raise RuntimeError("inventory matched no pressure-level fields")
+
+    downloaded = h.download(PRESSURE_FIELDS, errors="raise")
+    path = Path(downloaded) if downloaded is not None else None
+    if path is None or not path.is_file() or path.stat().st_size == 0:
+        raise RuntimeError("GRIB2 subset was not materialized")
+
+    return path, {
+        "model": h.model,
+        "product": h.product,
+        "initialization": h.date.isoformat(),
+        "forecast_hour": h.fxx,
+        "valid_time": h.valid_date.isoformat(),
+        "provider": h.grib_source,
+        "remote_object": str(h.grib),
+        "messages": len(selected),
+    }
+```
+
+For xarray output, call `h.xarray(search, ...)` and handle either one
+`xarray.Dataset` or a list of incompatible GRIB hypercubes. Merge only groups
+whose coordinates and dimensions are compatible, and close every dataset when
+finished.
+
+## Public AWS S3 Diagnostics
+
+NOAA Open Data buckets allow unsigned reads. `--no-sign-request` prevents the
+AWS CLI from loading credentials; it does not disable TLS verification.
+
+```bash
+aws s3 ls --no-sign-request s3://noaa-hrrr-bdp-pds/hrrr.YYYYMMDD/conus/
+
+aws s3api get-object --no-sign-request \
+  --bucket noaa-hrrr-bdp-pds \
+  --key "hrrr.YYYYMMDD/conus/hrrr.tHHz.wrfprsfFF.grib2" \
+  --range "bytes=START-END" fragment.grib2
+```
+
+Use these commands to inspect a documented public object or reproduce one
+known range. For normal multi-message assembly, reuse Herbie or the project's
+tested downloader instead of scripting binary concatenation in shell.
+
+## Complete Sounding Contract
+
+A pressure-level file alone may not contain a usable surface row. Before
+building a vertical profile, require:
+
+- all published isobaric levels for geopotential height, temperature, a
+  moisture variable (dew point, relative humidity, or specific humidity), and
+  U/V wind;
+- surface pressure and terrain or surface height;
+- 2 m temperature and moisture;
+- 10 m U/V wind.
+
+Some providers split pressure and surface fields into separate products. Fetch
+and join the companion product from the same run, or reject the request with a
+list of missing fields. Do not fabricate a ground row or silently reduce the
+profile to a short mandatory-level list.
+
+After decoding, sort pressure monotonically, remove duplicate levels, normalize
+units and longitude conventions, and run the consuming project's profile QC.
+
+## Point and Batch Extraction
+
+- On one-dimensional latitude/longitude grids, labeled nearest selection may be
+  sufficient.
+- On projected or curvilinear grids with two-dimensional coordinates, use the
+  project's model-aware nearest-cell routine; verify the selected latitude,
+  longitude, and distance.
+- For many points from one model hour, fetch and decode once, then reuse it.
+- For many hours, members, or regional slices, compare the GRIB route with a
+  chunked Zarr or provider-native endpoint before scaling up.
+
+## Reliability, Cache, and Cleanup
+
+- Cache by provider, object key, object identity, and field selection. A
+  filename alone is not enough provenance.
+- Retry timeouts, `408`, `429`, and transient `5xx` responses with bounded
+  exponential backoff and jitter; honor `Retry-After`.
+- Do not retry permission errors, malformed inventories, or impossible model
+  coordinates as transient failures.
+- Bound concurrency. More range workers can increase throttling and make
+  cancellation slower.
+- Keep partial files separate from valid cache entries and resume only when the
+  remote object identity still matches.
+- For a one-shot render or export, isolate data in a request-specific temporary
+  directory and remove it in `finally` after the derived artifact is durable.
+- For an interactive viewer, retain data until the final consumer closes. Never
+  delete a shared user cache as request cleanup.
+
+Measure discovery, inventory, transfer, decode, point extraction, and rendering
+separately. A slow end-to-end request is not evidence that GRIB decoding is the
+bottleneck.
+
+## Verification Checklist
+
+- The resolved initialization time, forecast hour, valid time, product, and
+  member match the request.
+- The selected inventory is nonempty and contains every required field/level.
+- The response status, byte ranges, lengths, and object identity are consistent.
+- The final file is nonempty and opens with the intended GRIB decoder.
+- Decoded variables, units, level count, grid coordinates, and valid time are
+  plausible and explicit.
+- A point result reports the actual selected grid coordinate.
+- Cancellation leaves no file that can be mistaken for a complete cache hit.
+- Cleanup preserves the requested final artifact and removes only data owned by
+  that request.
+
+## Security & Safety Notes
+
+- Fetch only public datasets or resources the user is authorized to access.
+- Do not put cloud credentials in code, URLs, logs, examples, or skill files.
+- Keep certificate verification enabled; never solve TLS errors with
+  `--no-verify-ssl`.
+- Validate inventory-derived ranges against the remote object length before
+  allocating buffers or writing files.
+- Bound requested cycles, members, forecast hours, concurrency, disk usage, and
+  retries before a large batch.
+- Follow provider usage policies and preserve required dataset attribution.
+
+## Common Pitfalls
+
+- **No data for the newest run:** The cycle is still publishing. Use the newest
+  completed cycle and report the fallback.
+- **Subset is as large as the full file:** The inventory was missing, the regex
+  was too broad, or the server ignored `Range`.
+- **xarray returns a list:** The selected messages form multiple incompatible
+  hypercubes. Process them separately or merge only compatible groups.
+- **Point extraction is still expensive:** GRIB message ranges are not spatial
+  chunks. Use a point/regional service or Zarr when available.
+- **A cached file opens but has missing fields:** Validate the inventory contract
+  and object identity before accepting a cache hit.
+
+## Limitations
+
+- Provider key layouts, retention windows, model schedules, and Herbie templates
+  can change; verify them against current provider documentation.
+- Variable subsetting requires a usable remote inventory. Without one, download
+  the full object or use a different provider.
+- This skill does not validate forecast skill, scientific suitability, or
+  proprietary-provider credentials and quotas.
+
+## Additional Resources
+
+- [Herbie documentation](https://herbie.readthedocs.io/)
+- [Herbie source and model templates](https://github.com/blaylockbk/Herbie)
+- [NOAA fast GRIB2 downloads with inventories](https://nomads.ncep.noaa.gov/info.php?page=fastdownload)
+- [Amazon S3 `GetObject` byte ranges](https://docs.aws.amazon.com/AmazonS3/latest/API/API_GetObject.html)
+- [NOAA HRRR on the AWS Registry of Open Data](https://registry.opendata.aws/noaa-hrrr-pds/)
+- [NOAA GFS on the AWS Registry of Open Data](https://registry.opendata.aws/noaa-gfs-bdp-pds/)