diff --git a/.agents/skills/adopt-upstream.md b/.agents/skills/adopt-upstream.md new file mode 100644 index 0000000..b30bdbb --- /dev/null +++ b/.agents/skills/adopt-upstream.md @@ -0,0 +1,76 @@ +--- +name: adopt-upstream +description: Adopt upstream Everruns changes into the SDK. Use when asked to sync or pull changes from everruns/everruns, update the OpenAPI spec, analyze upstream API/docs changes, implement obvious SDK updates across Rust, Python, and TypeScript, propose ambiguous changes, and ship adopted changes. +user_invocable: true +--- + +# Adopt Upstream + +Adopt current `everruns/everruns` API and docs changes into this SDK repo. + +Requirements live in `specs/upstream-adoption.md`. Use that spec as authority. This skill describes expected outcomes, not a rigid workflow. + +## Arguments + +- `$ARGUMENTS` - Optional scope, date range, upstream PR/commit, feature area, or "ship" intent. + +## Goals + +### Current Base + +Work from latest `origin/main`. In a worktree, fetch `origin/main`, create or use a branch based on it, and rebase before shipping. + +### Upstream Understanding + +Build enough evidence to know what changed upstream: + +- refresh `openapi/openapi.json` from upstream +- inspect the OpenAPI diff +- inspect recent upstream commits/PRs/docs relevant to SDK behavior +- compare findings with local `specs/`, generated types, SDK clients, tests, docs, and cookbooks + +Do not treat OpenAPI generation as the whole job. It only exposes part of the delta. + +### Decision Quality + +Classify each upstream delta: + +- **Obvious**: SDK behavior follows existing patterns or explicit specs. Implement it. +- **Non-obvious**: semantics, naming, target parity, or user ergonomics need a decision. Propose it. + +For non-obvious changes, produce a proposal with: + +- recommended SDK surface +- spec updates needed +- Rust/Python/TypeScript impact +- tests and docs needed +- open questions or upstream gaps + +### Complete Adoption + +For obvious changes, make the SDK whole: + +- update specs first or with code when requirements changed +- regenerate types after OpenAPI changes +- implement public client behavior in every target +- add/update positive and negative tests +- update user docs, code docs, and cookbooks when public behavior changed +- keep examples equivalent across Rust, Python, and TypeScript + +No target should be left behind unless a spec explicitly excludes it. + +### Shipment + +If the user asked to ship, or the obvious change is ready to ship, use `/ship` after implementation. Shipping means merged to `main`; PR creation alone is not done. + +If mixed obvious and non-obvious changes exist, ship the obvious safe subset only when it is independently coherent. Leave the rest as a proposal. + +## Output + +Report: + +- upstream sources inspected +- OpenAPI/spec/code/docs changes made +- target parity status +- tests/checks run +- shipped PR/merge status, or proposal status with blockers diff --git a/AGENTS.md b/AGENTS.md index 2c999f1..3f15957 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -28,6 +28,7 @@ Fix root cause. Unsure: read more code; if stuck, ask w/ short options. Unrecogn - `specs/error-handling.md` - Error types per language, retry patterns - `specs/release-process.md` - Versioning, changelog, publishing to registries - `specs/shipping.md` - Ship workflow phases, quality core, test coverage requirements +- `specs/upstream-adoption.md` - Requirements for adopting changes from everruns/everruns ### OpenAPI @@ -95,6 +96,7 @@ just generate # Regenerate types from OpenAPI `.agents/skills/` contains agent skills (also symlinked at `.claude/skills/`). - `ship.md` - Full shipping workflow: test, verify artifacts, smoke test, push, PR, merge +- `adopt-upstream.md` - Adopt upstream Everruns API/docs changes into all SDK targets ### Shipping diff --git a/specs/upstream-adoption.md b/specs/upstream-adoption.md new file mode 100644 index 0000000..a4efdc1 --- /dev/null +++ b/specs/upstream-adoption.md @@ -0,0 +1,104 @@ +# Upstream Adoption + +Requirements for adopting changes from `everruns/everruns` into this SDK repo. + +## Definition + +Upstream adoption means the SDKs are brought back into agreement with the current Everruns product API and public documentation. + +The deliverable is either: + +- shipped SDK changes for obvious upstream deltas, merged to `main` +- a concrete proposal for non-obvious deltas, with enough detail to implement next +- both, when an upstream update has mixed obvious and ambiguous parts + +## Sources Of Truth + +- Upstream OpenAPI: `everruns/everruns:docs/api/openapi.json` +- Local OpenAPI mirror: `openapi/openapi.json` +- Local SDK requirements: `specs/` +- Local generated API types: language-specific generated code +- Public SDK docs and examples: root and per-language READMEs, `docs/`, `cookbook/` +- Upstream public SDK docs when relevant: `everruns/everruns:docs/features/sdk.mdx` + +`openapi/openapi.json` is mirrored from upstream. Do not hand-edit it except to replace it with the current upstream file. + +## Classification + +### Obvious Changes + +Implement and ship upstream changes when the SDK behavior is mechanically clear: + +- new request/response fields generated from OpenAPI +- enum/schema changes with no ergonomic API design question +- endpoint changes matching an existing SDK resource pattern +- validation rule changes already stated in OpenAPI or upstream docs +- documentation updates that follow implemented SDK behavior +- cookbook updates that keep scenarios aligned across languages + +### Non-Obvious Changes + +Propose before implementing when the right SDK behavior is not clear: + +- new product concepts that need naming or resource boundaries +- endpoints that do not fit existing client structure +- streaming, pagination, auth, retry, or error semantics not specified enough to code +- cross-language ergonomics where idiomatic APIs would diverge +- OpenAPI behavior that conflicts with local specs or implementation +- upstream docs that describe behavior missing from OpenAPI + +Proposals must include the recommended SDK surface, impacted specs, target-language impact, migration scope, tests needed, and open questions. + +## Requirements + +### OpenAPI Sync + +- Fetch the current upstream OpenAPI file from `https://raw.githubusercontent.com/everruns/everruns/main/docs/api/openapi.json`. +- Compare it to the local mirror before generating or coding. +- Regenerate types after any OpenAPI change with `just generate`. +- Treat generated diffs as inputs to implementation, not as complete adoption. + +### Upstream Delta Analysis + +- Inspect upstream changes relevant to API behavior, SDK docs, examples, auth, streaming, errors, and endpoint semantics. +- Use upstream commits, PRs, docs, and OpenAPI diffs as evidence. +- Distinguish product/API changes from internal server-only changes. +- Record ambiguous or conflicting findings instead of guessing. + +### Spec Alignment + +- Update `specs/` when behavior, API coverage, SDK architecture, auth, streaming, errors, shipping, or release expectations change. +- `specs/api-surface.md` must match the endpoints intentionally exposed by all SDK targets. +- Specs are requirements. Code should satisfy them or propose spec changes before implementation. + +### Target Parity + +- Rust, Python, and TypeScript SDKs must expose the same feature set unless a spec explicitly says otherwise. +- New endpoints, models, validations, errors, docs, and examples must be considered for every target. +- A change is incomplete if one target implements a public feature that the others do not. + +### Documentation + +- Update user-facing docs when public API usage changes. +- Update code docs when public classes, methods, functions, types, or modules change. +- Keep README and cookbook examples runnable and aligned across targets. +- If upstream public SDK docs are stale, include an upstream-docs follow-up or PR plan. + +### Verification + +- Add or update tests for implemented behavior, including positive and negative paths. +- Run target-specific checks for changed languages. +- Run cross-target checks when API parity, generated types, cookbooks, or shared specs change. +- Obvious changes are not done until they pass the repo shipping requirements and are merged. + +## Shipping + +Obvious adopted changes must use the normal shipping requirements in `specs/shipping.md` and the `/ship` skill. + +Do not merge: + +- red CI +- unreviewed generated diffs +- partial target implementations +- spec/code disagreements +- guessed behavior for non-obvious upstream changes