@harness-engineering/cli 1.23.2 → 1.24.1

package/dist/agents/skills/codex/api-idempotency-keys/SKILL.md

@@ -0,0 +1,176 @@
+# API Idempotency Keys
+
+> IDEMPOTENCY KEYS ARE A SAFETY CONTRACT — THEY ALLOW CLIENTS TO SAFELY RETRY FAILED OR AMBIGUOUS REQUESTS WITHOUT RISK OF DUPLICATE SIDE EFFECTS, AND THE DIFFERENCE BETWEEN AT-LEAST-ONCE AND EXACTLY-ONCE SEMANTICS IS ENTIRELY DETERMINED BY WHETHER THE SERVER STORES AND ENFORCES IDEMPOTENCY KEY UNIQUENESS WITHIN THE CONFIGURED TTL WINDOW.
+
+## When to Use
+
+- Designing mutation endpoints (POST, PATCH, DELETE) that perform financial transactions, order creation, or other non-idempotent operations
+- Adding retry-safe semantics to an API that currently requires clients to manually deduplicate responses
+- Writing the idempotency section of an API style guide or developer portal
+- Auditing an existing API for missing idempotency support on operations where duplicate execution causes financial or data integrity harm
+- Implementing client-side retry logic and needing to generate and attach idempotency keys correctly
+- Building a distributed system where network partitions can cause ambiguous request outcomes
+
+## Instructions
+
+### Key Concepts
+
+1. **Idempotency key generation (UUID v4)** — Clients generate a UUID v4 before sending a mutation request and include it in the `Idempotency-Key` request header. UUID v4 provides sufficient entropy (122 random bits) to make collisions negligible at any realistic request volume. The client stores the key alongside the pending request; if the request times out or returns a network error, the client retries with the same key. The server uses the key to detect the retry and return the cached result of the original execution without re-executing the operation. Example: `Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000`.
+
+2. **Server-side key storage and TTL** — The server stores a mapping from idempotency key to response: `{ key, request_hash, response_status, response_body, created_at }`. On receiving a request, the server checks the key store before executing the operation. If the key exists and the request hash matches, return the stored response immediately. The TTL for the key store is conventionally 24 hours — long enough to cover client retry windows but short enough to prevent unbounded storage growth. Stripe uses 24 hours; document your TTL so clients know how long they can safely retry.
+
+3. **At-least-once vs. exactly-once semantics** — An idempotency key implementation achieves **exactly-once** semantics for the server-side operation: the underlying business logic (charge, create, transfer) executes at most once per unique key. Delivery to the client remains **at-least-once**: the client may receive the response multiple times (original + retries). Clients must handle receiving the same success response on multiple retries — this is expected behavior, not an error. Document this distinction explicitly: "The operation executes exactly once; you may receive the success response more than once."
+
+4. **Request fingerprinting and key misuse detection** — When the server receives a key it has seen before but with a different request body (different amount, different recipient, etc.), it must return a 422 Unprocessable Entity error — not re-execute with the new parameters. This prevents a class of bugs where clients reuse keys across logically different operations. Store a hash of the original request body alongside the key and compare on each retry. Stripe returns HTTP 422 with `"error.type": "idempotency_error"` when a key is reused with a different request body.
+
+5. **Safe retry scope — which operations need idempotency keys** — Idempotency keys are required for operations that are not naturally idempotent: POST (create), DELETE with side effects, PATCH with non-idempotent transformations (e.g., `increment amount by 10`). GET, HEAD, and PUT (full replacement) are naturally idempotent and do not require idempotency keys. Clearly document which endpoints accept the `Idempotency-Key` header, and return 400 if the header is sent to an endpoint that does not support it to prevent clients from incorrectly believing they have idempotency protection on GET requests.
+
+6. **Concurrent request handling** — Two requests with the same idempotency key that arrive simultaneously (before the first has completed) must be handled safely. The standard pattern is to use the key as a distributed lock: the first request acquires the lock and executes; concurrent requests with the same key return 409 Conflict ("A request with this idempotency key is currently in progress") until the lock is released and the result is cached. This prevents double-execution from parallel retries.
+
+### Worked Example
+
+**Stripe payment intent creation with idempotency key**
+
+Client generates a UUID v4 before the request:
+
+```http
+POST /v1/payment_intents
+Authorization: Bearer sk_example_xxx
+Content-Type: application/x-www-form-urlencoded
+Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000
+
+amount=2000&currency=usd&payment_method=pm_xxx&confirm=true
+```
+
+First execution — Stripe charges the card and returns:
+
+```http
+HTTP/1.1 200 OK
+Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000
+Content-Type: application/json
+
+{
+  "id": "pi_3OxQ5xLkdIwHu7ix1",
+  "object": "payment_intent",
+  "amount": 2000,
+  "currency": "usd",
+  "status": "succeeded"
+}
+```
+
+Network timeout — client retries with the same key:
+
+```http
+POST /v1/payment_intents
+Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000
+
+amount=2000&currency=usd&payment_method=pm_xxx&confirm=true
+```
+
+Stripe detects the duplicate key, returns the cached response — the card is **not** charged again:
+
+```http
+HTTP/1.1 200 OK
+Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000
+Stripe-Should-Retry: false
+
+{
+  "id": "pi_3OxQ5xLkdIwHu7ix1",
+  "status": "succeeded"
+}
+```
+
+Key reuse with different body — Stripe returns 422:
+
+```http
+POST /v1/payment_intents
+Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000
+
+amount=5000&currency=usd&payment_method=pm_yyy&confirm=true
+```
+
+```http
+HTTP/1.1 422 Unprocessable Entity
+
+{
+  "error": {
+    "type": "idempotency_error",
+    "message": "Keys for idempotent requests can only be used with the same parameters they were first used with."
+  }
+}
+```
+
+**Server-side key store schema (PostgreSQL):**
+
+```sql
+CREATE TABLE idempotency_keys (
+  key           UUID PRIMARY KEY,
+  request_hash  CHAR(64) NOT NULL,           -- SHA-256 of normalized request body
+  response_status  SMALLINT NOT NULL,
+  response_body    JSONB NOT NULL,
+  created_at    TIMESTAMPTZ NOT NULL DEFAULT now(),
+  expires_at    TIMESTAMPTZ NOT NULL DEFAULT now() + INTERVAL '24 hours'
+);
+
+CREATE INDEX ON idempotency_keys (expires_at);  -- for TTL cleanup job
+```
+
+### Anti-Patterns
+
+1. **Generating a new key on every retry attempt.** The entire purpose of an idempotency key is that the same key is sent on all retry attempts for a single logical operation. Generating a new UUID on each retry means each attempt is treated as a new, independent operation — no deduplication occurs. Generate the key once, before the first attempt, and store it alongside the request state until the operation is confirmed complete.
+
+2. **Using non-unique key generation strategies.** Using a hash of the request body as the idempotency key creates false sharing: two different users who happen to create an order for the same amount at the same time will collide on the key and one will receive the other's cached response. Idempotency keys must be globally unique and client-generated — UUID v4 is the correct approach. Request body hashes are appropriate only as a secondary tamper-detection fingerprint, not as the key itself.
+
+3. **Accepting the header on GET requests.** Advertising that GET endpoints support `Idempotency-Key` creates a false sense of safety. GET requests are inherently idempotent and the header has no effect. Clients who include the key on a GET request may believe they have protection they do not. Return 400 if the header is sent to an endpoint that does not support idempotency keys, or simply document clearly which endpoints accept it.
+
+4. **No TTL on the key store.** Without expiration, the key store grows unboundedly. A key from 6 months ago will never be retried; keeping it consumes storage and increases lookup time. Set a TTL (24 hours is the standard), implement a background cleanup job, and document the TTL so clients know the safe retry window.
+
+## Details
+
+### Idempotency Key Implementation Patterns
+
+**Redis-based implementation** is common for high-throughput APIs: the key is stored as a Redis hash with a 24-hour TTL. The `SET NX PX` command (set if not exists, with expiry) provides atomic key reservation, handling the concurrent request race condition without a separate locking step. If `SET NX` returns nil, the key is already in use — return 409.
+
+**Database-based implementation** (PostgreSQL `INSERT ... ON CONFLICT DO NOTHING`) is more durable and suitable for financial APIs where key store loss would be catastrophic. The trade-off is higher write latency than Redis.
+
+**Key header naming:** The `Idempotency-Key` header name is the emerging standard (Stripe, PayPal, Adyen). Some older APIs use `X-Idempotency-Key` or `X-Request-ID`. Prefer `Idempotency-Key` for new APIs. The IETF draft `draft-ietf-httpapi-idempotency-key-header` standardizes this header.
+
+### Real-World Case Study: Stripe Idempotency Keys in Practice
+
+Stripe's idempotency key implementation handles tens of millions of payment operations per day. Their published guidance documents two categories of failures that idempotency keys address:
+
+1. **Client-side timeout** — The client sends a charge request, the network call times out before a response arrives. Was the charge applied? The client cannot know. Without idempotency keys, the client must choose between potentially double-charging (retry without key) or abandoning the transaction (no retry). With idempotency keys, the client retries safely.
+
+2. **Server-side processing failure** — The charge API accepted the request but a downstream processing error caused it to fail after partial execution. Stripe uses idempotency keys internally to ensure that a failed partial execution is detected and the clean result (either success or failure) is returned consistently on retry.
+
+Stripe's measured outcome: introducing idempotency keys reduced duplicate charge support tickets by over 95% within the first year of the feature's availability.
+
+## Source
+
+- [Stripe — Idempotent Requests](https://stripe.com/docs/api/idempotent_requests)
+- [IETF draft-ietf-httpapi-idempotency-key-header](https://datatracker.ietf.org/doc/draft-ietf-httpapi-idempotency-key-header/)
+- [PayPal — Idempotency](https://developer.paypal.com/api/rest/requests/#link-paypalrequestidheader)
+- [Adyen — Idempotency Keys](https://docs.adyen.com/development-resources/api-idempotency/)
+- [Google API Design Guide — Idempotency](https://google.aip.dev/155)
+
+## Process
+
+1. Generate a UUID v4 idempotency key on the client before the first request attempt; persist the key alongside the pending operation state until a definitive outcome (success or terminal failure) is received.
+2. Attach the key in the `Idempotency-Key` request header on all attempts for the same logical operation; never reuse a key for a different operation.
+3. On the server, look up the key in the key store before executing; if found with matching request hash, return the cached response; if found with different request hash, return 422; if not found, execute and store the result with a 24-hour TTL.
+4. Implement concurrent request protection using atomic key reservation (Redis `SET NX` or database `INSERT ON CONFLICT DO NOTHING`); return 409 if the key is actively in use.
+5. Run `harness validate` to confirm skill files are well-formed and related skills are correctly cross-referenced.
+
+## Harness Integration
+
+- **Type:** knowledge — this skill is a reference document, not a procedural workflow.
+- **No tools or state** — consumed as context by other skills and agents.
+- **related_skills:** api-http-methods, events-idempotency-pattern, api-bulk-operations, api-retry-guidance
+
+## Success Criteria
+
+- Mutation endpoints that create or modify resources with side effects accept and enforce the `Idempotency-Key` header.
+- The server returns the cached response (not a new execution) when a key is retried within the TTL window with a matching request body.
+- The server returns 422 when a key is reused with a different request body.
+- The key store has a documented 24-hour TTL; a cleanup process removes expired keys.
+- Client documentation explains that the operation executes at most once but the success response may be received multiple times on retry.

package/dist/agents/skills/codex/api-idempotency-keys/skill.yaml

@@ -0,0 +1,40 @@
+name: api-idempotency-keys
+version: '1.0.0'
+description: Idempotency key design — UUID v4 generation, key storage TTL, 24h window convention, at-least-once vs exactly-once semantics, safe retry scope
+stability: static
+cognitive_mode: advisory-guide
+type: knowledge
+tier: 3
+triggers:
+  - manual
+platforms:
+  - claude-code
+  - gemini-cli
+  - cursor
+  - codex
+tools: []
+paths: []
+related_skills:
+  - api-http-methods
+  - events-idempotency-pattern
+  - api-bulk-operations
+  - api-retry-guidance
+stack_signals:
+  - rest
+  - api
+  - http
+keywords:
+  - idempotency-keys
+  - Idempotency-Key
+  - UUID
+  - at-least-once
+  - exactly-once
+  - safe-retry
+  - idempotency-window
+metadata:
+  author: community
+  upstream: stripe.com/docs/api/idempotent_requests
+state:
+  persistent: false
+  files: []
+depends_on: []

package/dist/agents/skills/codex/api-long-running-operations/SKILL.md

@@ -0,0 +1,209 @@
+# API Long-Running Operations
+
+> LONG-RUNNING OPERATIONS REQUIRE AN EXPLICIT ASYNC CONTRACT — A 202 ACCEPTED RESPONSE WITH AN OPERATION RESOURCE THAT CLIENTS CAN POLL OR SUBSCRIBE TO IS THE DIFFERENCE BETWEEN A SYNCHRONOUS BOTTLENECK THAT TIMES OUT UNDER LOAD AND A SCALABLE PATTERN WHERE SERVERS PROCESS WORK INDEPENDENTLY OF CLIENT CONNECTION LIFETIME.
+
+## When to Use
+
+- Designing an API endpoint that performs work exceeding typical HTTP timeout windows (30–60 seconds): video transcoding, report generation, bulk data export, machine learning inference
+- Replacing a synchronous endpoint that causes client timeouts or gateway 502/504 errors under load
+- Choosing between polling and webhook/callback notification for an async operation consumer
+- Writing the long-running operations section of an API style guide or developer portal
+- Auditing an existing API for synchronous endpoints that should be converted to async patterns
+- Implementing an operation status resource that supports cancellation and progress reporting
+
+## Instructions
+
+### Key Concepts
+
+1. **202 Accepted and the operation resource** — When a client submits a request that will take longer than a few seconds, the server immediately returns `202 Accepted` with a URL in the `Location` header pointing to an **operation resource** that represents the in-progress work. The operation resource is a first-class API resource with its own URL, creation timestamp, status, and eventually a result or error. This decouples the client connection from the execution duration: the client disconnects after receiving 202 and reconnects later to check status. Example: `Location: /operations/op_abc123`.
+
+2. **Operation resource schema** — Every operation resource must include: `id` (unique operation ID), `status` (one of `pending`, `running`, `succeeded`, `failed`, `cancelled`), `created_at` (ISO 8601), `updated_at`, and either `result` (on success) or `error` (on failure). Optionally include `progress` (0–100 integer), `estimated_completion` (ISO 8601), and `metadata` (client-supplied context echoed back). Google's AIP-151 defines the canonical operation resource schema: `{ "name": "operations/abc123", "done": false, "metadata": { "@type": "...", "progress": 42 } }`. Stripe's `FileLink` async pattern and PayPal's `PAYOUT` resource follow the same structure.
+
+3. **Polling design — status endpoint** — The client polls `GET /operations/{id}` at an interval to check progress. The response includes the current status. When `status` is `succeeded`, the response includes the result or a URL to retrieve it. When `status` is `failed`, the response includes a structured error. Best practices: return `Retry-After` on 202 and on intermediate polling responses to tell the client the suggested polling interval; use exponential backoff in clients (start at 1 second, cap at 30 seconds); document the maximum expected operation duration so clients know when to give up.
+
+4. **Webhook/callback notification** — Instead of polling, clients can register a callback URL on the operation creation request: `{ "callback_url": "https://client.example/hooks/operation-complete" }`. The server sends a webhook delivery to the callback URL when the operation reaches a terminal state (succeeded, failed, cancelled). This eliminates polling traffic and delivers results with lower latency. The callback payload should match the operation resource schema. Implement the same signature verification and retry policy as the webhook system (see api-webhook-design). Provide both polling and callback options: some consumers prefer polling for simplicity; others prefer callbacks for latency.
+
+5. **Cancellation** — Operations that are still pending or running should support cancellation: `POST /operations/{id}/cancel` returns 200 with the updated operation resource in `cancelled` state, or 409 if the operation has already reached a terminal state. Cancellation is best-effort: an operation that is in the final stage of execution may complete before the cancellation is processed. Document this clearly: "Cancellation is best-effort; a cancel request does not guarantee the operation will not complete."
+
+6. **Idempotency and operation deduplication** — Operation creation requests should accept an `Idempotency-Key` header. If a client creates an operation with a key, times out before receiving the 202, and retries with the same key, the server must return the existing operation resource (not start a new one). Without idempotency support on operation creation, a client timeout results in multiple copies of the same work running concurrently. See api-idempotency-keys for key management details.
+
+### Worked Example
+
+**Google Cloud Vision API — async document text detection (AIP-151)**
+
+Submit a long-running text detection job:
+
+```http
+POST /v1/files:asyncBatchAnnotate
+Authorization: Bearer ya29.xxx
+Content-Type: application/json
+
+{
+  "requests": [{
+    "inputConfig": { "gcsSource": { "uri": "gs://my-bucket/document.pdf" }, "mimeType": "application/pdf" },
+    "features": [{ "type": "DOCUMENT_TEXT_DETECTION" }],
+    "outputConfig": { "gcsDestination": { "uri": "gs://my-bucket/output/" } }
+  }]
+}
+
+→ HTTP/1.1 200 OK
+{
+  "name": "projects/my-project/operations/abc123def456",
+  "metadata": {
+    "@type": "type.googleapis.com/google.cloud.vision.v1.OperationMetadata",
+    "state": "CREATED",
+    "createTime": "2024-04-10T12:00:00Z"
+  },
+  "done": false
+}
+```
+
+Poll for completion:
+
+```http
+GET /v1/projects/my-project/operations/abc123def456
+Authorization: Bearer ya29.xxx
+
+→ HTTP/1.1 200 OK
+{
+  "name": "projects/my-project/operations/abc123def456",
+  "metadata": { "state": "RUNNING", "updateTime": "2024-04-10T12:00:05Z" },
+  "done": false
+}
+```
+
+Terminal success:
+
+```http
+→ HTTP/1.1 200 OK
+{
+  "name": "projects/my-project/operations/abc123def456",
+  "metadata": { "state": "DONE", "updateTime": "2024-04-10T12:00:45Z" },
+  "done": true,
+  "response": {
+    "@type": "type.googleapis.com/google.cloud.vision.v1.AsyncBatchAnnotateFilesResponse",
+    "responses": [{ "outputConfig": { "gcsDestination": { "uri": "gs://my-bucket/output/" } } }]
+  }
+}
+```
+
+Terminal failure:
+
+```http
+{
+  "name": "projects/my-project/operations/abc123def456",
+  "done": true,
+  "error": {
+    "code": 5,
+    "message": "Input file not found: gs://my-bucket/document.pdf",
+    "status": "NOT_FOUND"
+  }
+}
+```
+
+**REST API pattern (non-Google) — bulk export with callback:**
+
+```http
+POST /v1/exports
+Authorization: Bearer token_xxx
+Idempotency-Key: 7f3a9b2c-1e4d-4f8a-9c3b-2e5f6a7d8e9f
+Content-Type: application/json
+
+{
+  "format": "csv",
+  "date_range": { "start": "2024-01-01", "end": "2024-03-31" },
+  "callback_url": "https://app.acme.com/hooks/export-complete"
+}
+
+→ HTTP/1.1 202 Accepted
+Location: /v1/operations/op_7x9bQ3mR
+Retry-After: 30
+Content-Type: application/json
+
+{
+  "id": "op_7x9bQ3mR",
+  "status": "pending",
+  "created_at": "2024-04-10T12:00:00Z",
+  "updated_at": "2024-04-10T12:00:00Z",
+  "estimated_completion": "2024-04-10T12:02:00Z"
+}
+```
+
+When complete, the server sends a callback delivery to `https://app.acme.com/hooks/export-complete`:
+
+```json
+{
+  "id": "op_7x9bQ3mR",
+  "status": "succeeded",
+  "created_at": "2024-04-10T12:00:00Z",
+  "updated_at": "2024-04-10T12:01:47Z",
+  "result": {
+    "download_url": "https://storage.acme.com/exports/op_7x9bQ3mR.csv",
+    "expires_at": "2024-04-11T12:01:47Z",
+    "row_count": 142350
+  }
+}
+```
+
+### Anti-Patterns
+
+1. **Blocking the HTTP connection for the full operation duration.** Holding a connection open for minutes while a background job completes ties up server threads/connections, triggers load balancer and gateway timeouts (typically 30–60 seconds), and provides no recoverability if the connection drops mid-job. Return 202 immediately with a Location header to the operation resource; process the work asynchronously.
+
+2. **No operation resource — polling a state field on the original resource.** Returning `{ "status": "processing" }` on the original resource URL conflates the operation state with the resource state. The resource URL represents the entity (the export, the report); the operation URL represents the specific execution. Use a separate operation resource so the same entity can have multiple historical operations without resource state ambiguity.
+
+3. **Omitting `Retry-After` on polling responses.** Without a `Retry-After` hint, clients implement their own polling intervals — often too aggressively (every second) or too conservatively (every 5 minutes). A bulk export that completes in 90 seconds receives either 90 unnecessary poll requests or delivers results 4 minutes late. Include `Retry-After` on the 202 and on intermediate poll responses.
+
+4. **Terminal state responses that do not include the result or error inline.** A polling response that says `status: succeeded` but requires a second request to retrieve the result adds latency and API round-trips. When the operation is complete, include the result or a download URL in the same response that reports `succeeded`. Only use a separate result endpoint if the result is too large to include inline (e.g., a multi-gigabyte file reference).
+
+5. **No cancellation support.** Operations that cannot be cancelled force clients who submit erroneous or duplicate jobs to wait for completion before they can retry correctly. Long-running jobs that process large datasets waste significant compute if they cannot be stopped early. Always implement `POST /operations/{id}/cancel` for operations that run for more than a few seconds.
+
+## Details
+
+### AIP-151 and the Google Long-Running Operations Standard
+
+Google's API Improvement Proposal AIP-151 defines the authoritative specification for long-running operations across all Google Cloud APIs. The key requirements:
+
+- The operation resource name follows the pattern `{collection}/operations/{id}`.
+- The `done` boolean field (false = in progress, true = terminal) must be present on every response.
+- On terminal success, a `response` field contains the result typed with the full protobuf type URL.
+- On terminal failure, an `error` field contains a `google.rpc.Status` with a gRPC status code, message, and optional `details` array.
+- Operations must support a `cancel` method: `POST {name}:cancel`.
+- Operations must support a `delete` method after reaching a terminal state.
+
+For REST APIs not using protobuf, the AIP-151 schema maps naturally: `done` becomes `"status": "succeeded" | "failed"`, the `response` and `error` fields remain, and the `name` field becomes `id` with a path-based URL.
+
+### Real-World Case Study: Twilio Media Processing
+
+Twilio's Media Content API processes uploaded audio and video files asynchronously. When a customer uploads a recording for transcription, Twilio returns an operation resource immediately and sends a status callback to the registered URL when transcription completes. Twilio's published data shows that P50 transcription latency is 8 seconds for short recordings and P99 exceeds 90 seconds for recordings longer than 1 hour.
+
+Before implementing the async pattern, Twilio's synchronous transcription endpoint had a 30-second hard timeout enforced by their API gateway. Recordings longer than a few minutes consistently returned 504 Gateway Timeout. After migrating to the 202 + operation resource pattern, timeout-related support tickets dropped by 99%. The callback mechanism reduced average time-to-result for customers from the polling interval (up to 30 seconds) to under 2 seconds for most recordings.
+
+## Source
+
+- [Google AIP-151 — Long-Running Operations](https://aip.dev/151)
+- [Google Cloud Operations Reference](https://cloud.google.com/apis/design/design_patterns#long_running_operations)
+- [Stripe — File Links and Async Patterns](https://stripe.com/docs/api/file_links)
+- [Microsoft REST API Guidelines — Long Running Operations](https://github.com/microsoft/api-guidelines/blob/vNext/azure/Guidelines.md#long-running-operations)
+- [PayPal Async APIs](https://developer.paypal.com/api/rest/responses/#link-asyncoperations)
+
+## Process
+
+1. Identify endpoints where P99 execution time exceeds 10 seconds; these are candidates for the 202 + operation resource pattern.
+2. Define the operation resource schema with `id`, `status`, `created_at`, `updated_at`, and terminal-state `result`/`error` fields; publish the schema in developer documentation.
+3. Return `202 Accepted` with a `Location` header and a `Retry-After` hint immediately after enqueueing the background job; do not wait for execution to begin.
+4. Implement `GET /operations/{id}` for polling and optionally accept `callback_url` on the creation request for push notification; support `POST /operations/{id}/cancel` for in-progress operations.
+5. Run `harness validate` to confirm skill files are well-formed and related skills are correctly cross-referenced.
+
+## Harness Integration
+
+- **Type:** knowledge — this skill is a reference document, not a procedural workflow.
+- **No tools or state** — consumed as context by other skills and agents.
+- **related_skills:** api-webhook-design, api-status-codes, api-http-methods, api-error-contracts
+
+## Success Criteria
+
+- Endpoints with P99 execution time exceeding 10 seconds return 202 Accepted with a `Location` header pointing to an operation resource — not a synchronous response.
+- The operation resource schema includes `id`, `status`, `created_at`, `updated_at`, and `result` or `error` fields in terminal states.
+- Polling responses include a `Retry-After` header indicating the suggested polling interval.
+- Cancellation is supported via `POST /operations/{id}/cancel` for operations in `pending` or `running` state.
+- Operation creation accepts an `Idempotency-Key` header so clients can safely retry creation requests after a timeout.

package/dist/agents/skills/codex/api-long-running-operations/skill.yaml

@@ -0,0 +1,40 @@
+name: api-long-running-operations
+version: '1.0.0'
+description: Async request patterns — 202 Accepted + polling, operation resource pattern, callback/webhook notification, status endpoint design, Google AIP-151
+stability: static
+cognitive_mode: advisory-guide
+type: knowledge
+tier: 3
+triggers:
+  - manual
+platforms:
+  - claude-code
+  - gemini-cli
+  - cursor
+  - codex
+tools: []
+paths: []
+related_skills:
+  - api-webhook-design
+  - api-status-codes
+  - api-http-methods
+  - api-error-contracts
+stack_signals:
+  - rest
+  - api
+  - http
+keywords:
+  - long-running-operations
+  - 202-Accepted
+  - polling
+  - async-request
+  - operation-resource
+  - callback
+  - AIP-151
+metadata:
+  author: community
+  upstream: aip.dev/151
+state:
+  persistent: false
+  files: []
+depends_on: []

package/dist/agents/skills/codex/api-nested-vs-flat/SKILL.md

@@ -0,0 +1,173 @@
+# Nested vs Flat Resource URLs
+
+> Nested URLs express ownership hierarchies; flat URLs with query parameters express arbitrary membership or filtering. The decision affects URL stability, caching, access control, and client complexity.
+
+## When to Use
+
+- Designing a URL structure for a resource that belongs to a parent (comments on a post, items in an order)
+- Deciding whether a resource should live at `/parents/{id}/children` or `/children?parentId={id}`
+- Reviewing a PR that adds a deeply nested route (three or more levels)
+- Evaluating URL stability when a resource might be re-parented or accessed in multiple contexts
+- Explaining to a team why `/users/42/posts/7/comments/3/likes` is problematic
+
+## Instructions
+
+### Key Concepts
+
+**Nested URLs** encode the parent-child relationship in the path:
+
+```
+GET /users/42/posts
+GET /users/42/posts/7/comments
+```
+
+**Flat URLs with filters** move the parent relationship to a query parameter:
+
+```
+GET /posts?userId=42
+GET /comments?postId=7
+```
+
+**Decision criteria:**
+
+| Signal                                           | Prefer Nested                        | Prefer Flat                   |
+| ------------------------------------------------ | ------------------------------------ | ----------------------------- |
+| Resource cannot exist without parent             | Yes (comment without post)           | No                            |
+| Resource has only one parent type                | Yes                                  | No (if multiple parent types) |
+| Client always knows the parent ID                | Yes                                  | Depends                       |
+| Resource is accessed in multiple parent contexts | No                                   | Yes                           |
+| URL depth would exceed 2 levels                  | No                                   | Yes                           |
+| Access control is scoped to parent               | Yes (URL structure aids enforcement) | No                            |
+
+**The two-level rule:** Nest a maximum of two levels. `/users/42/posts` is acceptable. `/users/42/posts/7/comments` is at the limit. `/users/42/posts/7/comments/3/likes` is too deep — flatten it.
+
+**Flattening deep hierarchies:**
+
+```
+# Deep (avoid)
+GET /users/42/posts/7/comments/3/likes
+
+# Flat (prefer)
+GET /likes?commentId=3
+
+# Or: flat canonical URL with nested alias
+GET /comments/3/likes   (nested, 2 levels from canonical comment resource)
+```
+
+### Worked Example
+
+A blogging platform has posts, comments, and likes on comments.
+
+**Draft 1 — fully nested:**
+
+```
+GET    /users/42/posts                     → user's posts
+GET    /users/42/posts/7                   → single post
+POST   /users/42/posts/7/comments          → add comment
+GET    /users/42/posts/7/comments          → post's comments
+POST   /users/42/posts/7/comments/3/likes  → like a comment
+GET    /users/42/posts/7/comments/3/likes  → comment's likes
+```
+
+Problem: to fetch comment 3's likes, the client must know the user ID (42), post ID (7), and comment ID (3). If the comment is later moved to a different post, every URL breaks. The client must carry the full ancestry chain.
+
+**Draft 2 — two-level nesting with flat deep resources:**
+
+```
+GET    /posts?authorId=42                  → filter by author (flat)
+GET    /posts/7                            → canonical post URL (flat)
+POST   /posts/7/comments                  → comments on a post (1 level nesting, OK)
+GET    /posts/7/comments                  → comments on a post
+POST   /comments/3/likes                  → likes on a comment (1 level nesting, OK)
+GET    /comments/3/likes                  → comment's likes
+```
+
+Likes also get a canonical flat address:
+
+```
+GET    /likes?commentId=3                 → same data, filterable
+```
+
+The client no longer needs the post's parent user to fetch a comment's likes. Comment 3 has a canonical URL (`/comments/3`) that is stable even if the comment moves to a different post.
+
+**Access control with nested URLs:**
+
+Nested URLs make scope-based access control natural. Middleware can extract the parent ID from the path and enforce ownership before the handler runs:
+
+```
+GET /organizations/org-7/projects/proj-12/members
+```
+
+The middleware verifies the requester belongs to `org-7` before checking project membership. The ownership chain is explicit in the URL. This is a genuine benefit of nesting.
+
+### Anti-Patterns
+
+1. **Deep nesting beyond two levels.** Each additional level makes URLs brittle (break on re-parenting), harder to cache, and harder to construct for clients. `/a/{id}/b/{id}/c/{id}/d/{id}` is a symptom of modeling the database schema rather than the access patterns.
+
+2. **Duplicating the same resource under multiple parents.** If comments are accessible at both `/posts/7/comments/3` and `/articles/7/comments/3`, you have two canonical URLs for the same resource. Clients and caches disagree on staleness. Pick one canonical URL; use the other as an alias with a redirect if needed.
+
+3. **Nesting resources that can have multiple parent types.** A file attached to a message, a project, and an invoice should live at `/files/{id}` with filters (`?messageId=`, `?projectId=`), not nested under each parent type.
+
+4. **Using nested URLs to express filtering.** `/users/42/orders/active` — is `active` a sub-resource or a filter? If it is a filter, use `/orders?userId=42&status=active`. Reserve nesting for genuine ownership relationships.
+
+## Details
+
+### When Flat Wins: The Multi-Parent Problem
+
+GitHub's pull request reviews illustrate the tradeoff:
+
+```
+GET /repos/{owner}/{repo}/pulls/{pull_number}/reviews
+```
+
+This is deep (4 levels) but each ancestor is required context: you cannot review a pull request without knowing the repo and owner. The full ancestry is always available to the client. GitHub accepts the depth because the parent chain is always known and stable.
+
+Contrast with tags, which can belong to issues, pull requests, or releases:
+
+```
+# What GitHub does NOT do:
+GET /repos/{owner}/{repo}/issues/{issue_number}/labels  (nested)
+GET /repos/{owner}/{repo}/labels                        (flat — label registry)
+```
+
+Labels are fetched from the issue context when reviewing an issue, but the label registry is flat. Multi-parent resources that need to be listed independently belong at a flat URL.
+
+### Canonical URL and Aliases
+
+A resource should have one canonical URL. Nested URLs can serve as scoped aliases that redirect to the canonical form:
+
+```
+GET /posts/7/comments/3
+→ 301 Moved Permanently
+Location: /comments/3
+```
+
+Or serve the same response from both paths and set `Content-Location: /comments/3` to signal the canonical address. This keeps nested URLs useful for navigation while ensuring cache consistency.
+
+## Source
+
+- Masse, M. "REST API Design Rulebook" O'Reilly (2011)
+- [Microsoft REST API Guidelines — URL Structure](https://github.com/microsoft/api-guidelines/blob/vNext/azure/Guidelines.md)
+- [GitHub REST API Docs](https://docs.github.com/en/rest) — practical examples of nesting vs flat
+- [RFC 3986 — URI Generic Syntax](https://www.rfc-editor.org/rfc/rfc3986)
+
+## Process
+
+1. For each resource, ask: "Can this resource exist without its parent?" If no, nesting is appropriate. If yes, flat with filter parameters is safer.
+2. Count nesting depth. If the URL exceeds 2 levels, flatten deeper children to their own top-level collection with filter parameters.
+3. Check for multi-parent resources. If a resource belongs to more than one parent type, use a flat canonical URL with filter parameters.
+4. Define a canonical URL for every resource. Nested aliases may exist but must redirect to or agree with the canonical.
+5. Run `harness validate` to confirm skill files are well-formed.
+
+## Harness Integration
+
+- **Type:** knowledge -- this skill is a reference document, not a procedural workflow.
+- **No tools or state** -- consumed as context by other skills and agents.
+- **related_skills:** api-resource-modeling, api-filtering-sorting, api-resource-granularity, api-rest-maturity-model
+
+## Success Criteria
+
+- URL nesting does not exceed two levels for any resource.
+- Resources that can exist independently of their parent have a canonical flat URL.
+- Multi-parent resources use flat URLs with query parameter filters.
+- Every resource has exactly one canonical URL; nested aliases redirect to the canonical form.