@harness-engineering/cli 1.23.2 → 1.24.1

package/dist/agents/skills/gemini-cli/api-field-selection/SKILL.md

@@ -0,0 +1,193 @@
+# Field Selection
+
+> FIELD SELECTION LETS CLIENTS REQUEST ONLY THE RESPONSE PROPERTIES THEY NEED — REDUCING PAYLOAD SIZE, ELIMINATING OVER-FETCHING, AND CUTTING BOTH BANDWIDTH AND SERIALIZATION COST ON THE SERVER WITHOUT REQUIRING A SEPARATE GRAPHQL LAYER OR BESPOKE NARROW ENDPOINTS.
+
+## When to Use
+
+- Designing a list endpoint whose full response schema is large but whose mobile clients only need 3–4 fields
+- Implementing `?fields=` to allow clients to project a subset of response properties
+- Comparing field selection as an alternative to GraphQL for an API that serves heterogeneous clients
+- Reviewing a PR that returns deeply nested objects on a list endpoint used by bandwidth-constrained clients
+- Building admin tooling that needs all fields while the mobile app needs a minimal projection
+- Designing nested field selection (e.g., `?fields=id,name,owner.login`) for resources with embedded sub-objects
+- Evaluating performance tradeoffs between server-side field selection, multiple narrow endpoints, and GraphQL
+- Reducing JSON serialization cost for endpoints that serialize large string fields (descriptions, content bodies, HTML) on every response
+
+## Instructions
+
+### Key Concepts
+
+1. **Sparse Fieldsets** — A sparse fieldset is the requested subset of fields for a resource type. The client specifies which fields it wants; the server omits all others from the response. The JSON:API specification formalizes this as `?fields[resource_type]=field1,field2`. Simpler APIs use `?fields=field1,field2` without the type qualifier. Both are valid; choose based on whether your API has a single resource type per endpoint or multiple embedded types.
+
+   ```
+   ?fields=id,name,email              → return only id, name, email
+   ?fields[user]=id,name              → JSON:API style for the user resource
+   ?fields[user]=id,name&fields[org]=id,slug  → multi-type projection
+   ```
+
+2. **Nested Field Selection** — For resources with embedded sub-objects, use dot notation to select specific sub-fields. This avoids returning the full sub-object when only one property is needed:
+
+   ```
+   ?fields=id,title,author.name,author.avatar_url
+   ```
+
+   The server must parse the dot-path and project only the specified sub-fields from the embedded object. Fields not listed in the projection are omitted from the embedded object entirely, not set to null.
+
+3. **Always-Present Fields** — Some fields must always be present in every response regardless of projection: the resource ID, resource type, and any fields required for link traversal (e.g., `href`, `self`). Document these as mandatory fields that clients cannot exclude. If a client requests `?fields=name` but omits `id`, the response must still include `id`.
+
+4. **Server-Side Projection vs. Post-Processing** — True field selection projects fields at the data retrieval layer (SQL `SELECT col1, col2` instead of `SELECT *`) to avoid reading unused data from disk. A naive implementation fetches the full object and strips fields before serialization — this reduces response size but does not reduce database I/O or memory use. For maximum benefit, push the projection down to the query layer. Use SQL column lists, MongoDB projections, or equivalent for non-relational stores.
+
+5. **Performance Tradeoffs vs. GraphQL** — Field selection via `?fields=` covers 80% of over-fetching use cases with zero client-side schema knowledge and no query language. GraphQL covers the remaining 20%: deeply nested multi-resource queries, aliased field names, inline fragments, and complex query composition. For REST APIs serving heterogeneous clients, `?fields=` is a low-cost, high-value addition. Introducing GraphQL for field selection alone adds significant operational complexity. Choose GraphQL when clients need rich query composition, not just field projection.
+
+6. **Documenting Field Names** — The `?fields=` parameter is only usable if the available field names are documented. Include a complete field reference in the API documentation for every resource type, noting which fields are always-present and which are optional. An undocumented field surface forces clients to discover fields by trial and error.
+
+### Worked Example
+
+The Google Drive API implements `fields` parameter selection on nearly every endpoint, making it a canonical reference for production-grade field selection:
+
+**Without field selection (full resource — 847 bytes):**
+
+```http
+GET /drive/v3/files/1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs74OgVE2upms
+Authorization: Bearer ya29...
+```
+
+```http
+HTTP/1.1 200 OK
+Content-Type: application/json
+
+{
+  "kind": "drive#file",
+  "id": "1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs74OgVE2upms",
+  "name": "Q1 Report",
+  "mimeType": "application/vnd.google-apps.spreadsheet",
+  "description": "",
+  "starred": false,
+  "trashed": false,
+  "explicitlyTrashed": false,
+  "parents": ["0AEoMqdKFcXE3Uk9PVA"],
+  "spaces": ["drive"],
+  "version": "1",
+  "webViewLink": "https://docs.google.com/spreadsheets/...",
+  "iconLink": "https://drive-thirdparty.googleusercontent.com/...",
+  "hasThumbnail": false,
+  "thumbnailVersion": "0",
+  "viewedByMe": true,
+  "createdTime": "2024-01-10T08:00:00.000Z",
+  "modifiedTime": "2024-03-15T10:22:00.000Z",
+  "modifiedByMeTime": "2024-03-15T10:22:00.000Z",
+  "owners": [{ "kind": "drive#user", "displayName": "Alice", "emailAddress": "alice@example.com" }],
+  "lastModifyingUser": { "kind": "drive#user", "displayName": "Alice" },
+  "shared": false,
+  "ownedByMe": true,
+  "capabilities": { "canEdit": true, "canComment": true, "canShare": true }
+}
+```
+
+**With field selection (only id, name, modifiedTime — 94 bytes, 89% reduction):**
+
+```http
+GET /drive/v3/files/1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs74OgVE2upms?fields=id,name,modifiedTime
+Authorization: Bearer ya29...
+```
+
+```http
+HTTP/1.1 200 OK
+Content-Type: application/json
+
+{
+  "id": "1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs74OgVE2upms",
+  "name": "Q1 Report",
+  "modifiedTime": "2024-03-15T10:22:00.000Z"
+}
+```
+
+**List endpoint with nested field selection:**
+
+```http
+GET /drive/v3/files?fields=files(id,name,owners/displayName),nextPageToken
+Authorization: Bearer ya29...
+```
+
+Google Drive uses parentheses for nested selection in lists (`files(id,name)`) and `/` for nested object paths (`owners/displayName`). The `?fields=` syntax is documented exhaustively in the Google API Discovery documents.
+
+### Anti-Patterns
+
+1. **Stripping fields after full serialization.** Fetching all columns from the database, constructing the full response object in memory, serializing it to JSON, and then removing keys before sending saves bandwidth but wastes CPU, memory, and database I/O. For large objects with blob fields (markdown content, HTML, image metadata), the serialization of the unused fields may dominate request processing time. Push the projection to the SQL `SELECT` list or ORM query.
+
+2. **Silently ignoring unknown field names.** If a client requests `?fields=id,nme` (typo), silently returning only `id` makes the client believe it received all requested fields. The client may then treat the missing `name` field as null rather than detecting the typo. Return `400 Bad Request` listing the unrecognized field names. This prevents silent data bugs in client integrations.
+
+3. **Allowing field selection to bypass access control.** If field-level permissions exist (e.g., `salary` is restricted to HR roles), a generic `?fields=salary` from an unprivileged caller must still return a 403 for that field, not simply include it in the projection. Field selection must be applied after, not instead of, field-level authorization. The projection layer should filter fields from the set the caller is already authorized to see.
+
+4. **Omitting always-present fields from the documentation.** If clients discover through trial and error that `id` is always returned even when not in `?fields=`, they may rely on undocumented behavior. Document always-present fields explicitly in the API reference so clients can reason about the projection contract without experimenting.
+
+## Details
+
+### Implementation Patterns
+
+**SQL projection (preferred):**
+
+```python
+ALLOWED_FIELDS = {"id", "name", "email", "created_at", "role"}
+ALWAYS_PRESENT = {"id"}
+requested = set(params.get("fields", "").split(",")) & ALLOWED_FIELDS | ALWAYS_PRESENT
+columns = ", ".join(f"u.{f}" for f in requested)
+cursor.execute(f"SELECT {columns} FROM users u WHERE u.id = %s", [user_id])
+```
+
+**Post-serialization stripping (acceptable for small objects):**
+
+```python
+full_response = serialize(user)
+if "fields" in params:
+    allowed = set(params["fields"].split(",")) | ALWAYS_PRESENT
+    full_response = {k: v for k, v in full_response.items() if k in allowed}
+```
+
+### Field Selection on List Endpoints
+
+On list endpoints, apply the projection to every item in the collection. The `nextPageToken` or `next_cursor` field in the outer envelope is not subject to projection — it is metadata about the result set, not part of the resource schema.
+
+```json
+{
+  "items": [
+    { "id": "1", "name": "Alice" },
+    { "id": "2", "name": "Bob" }
+  ],
+  "next_cursor": "Y3Vyc29yMg=="
+}
+```
+
+### Real-World Case Study: Contentful
+
+Contentful's Delivery API serves content to web and mobile clients from a single content graph. Mobile clients for a news app needed only `sys.id`, `fields.title`, and `fields.heroImage.url` from entries that carried 40+ fields including rich-text body content averaging 12KB per entry. After implementing `?select=sys.id,fields.title,fields.heroImage` (Contentful's field selection syntax), the news app's feed API response size dropped from 387KB per 10-item page to 12KB — a 97% reduction. Server-side CPU for JSON serialization fell by 68% on that endpoint, and CDN cache efficiency improved because smaller, more cache-friendly responses fit in CDN edge memory more densely.
+
+## Source
+
+- [Google Drive API — Request Partial Responses](https://developers.google.com/drive/api/guides/fields-parameter)
+- [JSON:API — Sparse Fieldsets](https://jsonapi.org/format/#fetching-sparse-fieldsets)
+- [Contentful Delivery API — Select operator](https://www.contentful.com/developers/docs/references/content-delivery-api/#/reference/search-parameters/select-operator)
+- [GraphQL vs. REST field selection](https://graphql.org/learn/thinking-in-graphs/)
+- [OData — Select system query option](https://docs.oasis-open.org/odata/odata/v4.01/odata-v4.01-part2-url-conventions.html#sec_SystemQueryOptionselect)
+
+## Process
+
+1. Define the complete field schema for each resource type and identify always-present fields (at minimum: the resource ID and any hypermedia links).
+2. Build an explicit allow-list of selectable field names mapped to their SQL column or object property path. Reject unknown field names in `?fields=` with `400 Bad Request` listing valid options.
+3. Push the projection to the data retrieval layer: build the SQL `SELECT` column list or ORM projection from the requested fields, not from the full schema. Include always-present fields unconditionally.
+4. Apply field-level authorization before projection: the selectable field set is the intersection of requested fields and fields the caller is authorized to read.
+5. Document always-present fields, the projection syntax, and field names in the API reference for every endpoint that supports `?fields=`.
+
+## 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-granularity, graphql-client-patterns, api-filtering-sorting, api-pagination-cursor
+
+## Success Criteria
+
+- Field projection is pushed to the data retrieval layer (SQL SELECT or ORM projection), not applied by post-processing the full serialized response.
+- Unknown field names in `?fields=` return `400 Bad Request` with a list of valid field names.
+- Always-present fields (resource ID, hypermedia links) are included in every response regardless of the projection requested.
+- Field-level authorization is applied before projection; callers cannot use field selection to access fields they lack permission to read.
+- API documentation lists every selectable field, identifies always-present fields, and includes worked examples of the `?fields=` syntax.

package/dist/agents/skills/gemini-cli/api-field-selection/skill.yaml

@@ -0,0 +1,39 @@
+name: api-field-selection
+version: '1.0.0'
+description: Sparse fieldsets and partial responses via ?fields= syntax, nested field selection, and performance tradeoffs vs GraphQL
+stability: static
+cognitive_mode: advisory-guide
+type: knowledge
+tier: 3
+triggers:
+  - manual
+platforms:
+  - claude-code
+  - gemini-cli
+  - cursor
+  - codex
+tools: []
+paths: []
+related_skills:
+  - api-resource-granularity
+  - graphql-client-patterns
+  - api-filtering-sorting
+  - api-pagination-cursor
+stack_signals:
+  - rest
+  - api
+  - http
+keywords:
+  - field-selection
+  - sparse-fieldsets
+  - partial-response
+  - "?fields"
+  - projection
+  - over-fetching
+metadata:
+  author: community
+  upstream: developers.google.com/drive/api/guides/fields-parameter
+state:
+  persistent: false
+  files: []
+depends_on: []

package/dist/agents/skills/gemini-cli/api-filtering-sorting/SKILL.md

@@ -0,0 +1,170 @@
+# Filtering and Sorting
+
+> WELL-DESIGNED FILTER AND SORT PARAMETERS GIVE CLIENTS PRECISE CONTROL OVER RESULT SETS WITHOUT REQUIRING BESPOKE ENDPOINTS — BUT POORLY DESIGNED QUERY PARAMETERS INVITE INJECTION ATTACKS, PRODUCE UNINDEXED TABLE SCANS, AND LEAK INTERNAL SCHEMA DETAILS THAT BECOME BREAKING CHANGES WHEN THE DATA MODEL EVOLVES.
+
+## When to Use
+
+- Designing query parameters for a list endpoint that returns large result sets
+- Implementing server-side filtering so clients do not download all records and filter in memory
+- Choosing a filter operator syntax (`?status=active` vs. `?filter[status]=active` vs. `?q=status:active`)
+- Adding multi-field sorting with direction control (`?sort=-created_at,name`)
+- Reviewing a PR that passes filter parameters directly into a SQL query without sanitization
+- Building a search-like endpoint that needs range queries, `IN` lists, and substring matches
+- Evaluating whether a filter field should be backed by an index before exposing it in the API
+- Designing filter parameter naming for consistency across multiple list endpoints in an API surface
+
+## Instructions
+
+### Key Concepts
+
+1. **Filter Operator Vocabulary** — Define a consistent set of operators for every filter-capable field. At minimum, support equality and set membership. For orderable types (dates, numbers, strings), support range operators:
+
+   | Operator    | Meaning                       | Example                             |
+   | ----------- | ----------------------------- | ----------------------------------- |
+   | `eq`        | Exact match (default)         | `?status=active`                    |
+   | `ne`        | Not equal                     | `?filter[status][ne]=archived`      |
+   | `gt`, `lt`  | Greater/less than (exclusive) | `?filter[amount][gt]=100`           |
+   | `gte`,`lte` | Greater/less than or equal    | `?filter[created][gte]=2024-01-01`  |
+   | `in`        | Member of a set               | `?filter[status][in]=active,paused` |
+   | `contains`  | Substring or array contains   | `?filter[name][contains]=acme`      |
+   | `null`      | Is null / is not null         | `?filter[deleted_at][null]=true`    |
+
+2. **Sort Syntax** — Use a single `sort` parameter with comma-separated fields. Prefix a field name with `-` to indicate descending order. This convention is followed by JSON:API and many major APIs and is unambiguous:
+
+   ```
+   ?sort=-created_at,name       → ORDER BY created_at DESC, name ASC
+   ?sort=priority,-updated_at   → ORDER BY priority ASC, updated_at DESC
+   ```
+
+   Reject unknown sort fields with `400 Bad Request` and a list of allowed sort fields in the error body. Never silently ignore unsupported sort fields.
+
+3. **Filter Injection Prevention** — Filter parameters must never be interpolated directly into SQL. Always use parameterized queries or a query builder that maps field names to safe column references through an explicit allow-list. An API that passes `?filter[field]=users WHERE 1=1--` to a raw SQL string is vulnerable to SQL injection. Map every filterable field name to a concrete column reference in code; reject any field name not on the allow-list with `400 Bad Request`.
+
+4. **Performance Hints and Index Budget** — Every filterable field exposed in the API should be backed by a database index. Before adding a new filter field, verify the query plan. Exposing an un-indexed field in a public API invites callers to trigger full table scans at scale. Document which filter combinations are supported and which trigger a hint that index coverage is partial (e.g., `?filter[free_text]` triggers a full-text index, not a B-tree scan).
+
+5. **Filter Combination Semantics** — When multiple filter parameters are present, document whether they combine as AND (the default and most intuitive) or OR. Most REST APIs use AND semantics: `?status=active&priority=high` returns records where both conditions are true. If OR semantics are needed, make them explicit: `?filter[or][0][status]=active&filter[or][1][status]=paused` or accept a structured filter body via POST.
+
+6. **Sort Stability** — When no sort parameter is specified, use a stable default that does not change between requests. An unstable default sort (e.g., database insertion order without a tiebreaker) causes non-deterministic page ordering that breaks cursor pagination. Always include the primary key as the final tiebreaker in any sort, whether default or client-specified.
+
+### Worked Example
+
+The GitHub REST API provides fine-grained filtering and sorting on its Issues endpoint, demonstrating production-grade query parameter design:
+
+**Filter by state and assignee, sorted by comment count descending:**
+
+```http
+GET /repos/octocat/hello-world/issues?state=open&assignee=monalisa&sort=comments&direction=desc&per_page=5
+Authorization: Bearer ghp_...
+```
+
+```http
+HTTP/1.1 200 OK
+Content-Type: application/json
+X-RateLimit-Remaining: 59
+
+[
+  {
+    "id": 1001,
+    "number": 42,
+    "title": "Fix the login bug",
+    "state": "open",
+    "comments": 14,
+    "assignee": { "login": "monalisa" },
+    "created_at": "2024-02-10T09:00:00Z",
+    "updated_at": "2024-03-15T10:00:00Z"
+  },
+  {
+    "id": 998,
+    "number": 39,
+    "title": "Update README",
+    "state": "open",
+    "comments": 3,
+    "assignee": { "login": "monalisa" },
+    "created_at": "2024-01-20T08:00:00Z",
+    "updated_at": "2024-03-10T11:00:00Z"
+  }
+]
+```
+
+**Filter by date range using `since`:**
+
+```http
+GET /repos/octocat/hello-world/issues?state=closed&since=2024-01-01T00:00:00Z
+Authorization: Bearer ghp_...
+```
+
+GitHub's parameter naming is flat (`sort`, `direction`, `state`) rather than bracket-notation. This is a pragmatic choice for a small, fixed operator set. For APIs with many operators or dynamic filter fields, bracket notation (`filter[field][op]=value`) scales better.
+
+### Anti-Patterns
+
+1. **Passing filter parameter values directly into SQL strings.** A query like `"SELECT * FROM users WHERE " + params["filter"]` is a textbook SQL injection vulnerability. Always use parameterized queries. Map filter field names to column references through an explicit allow-list in code:
+
+   ```python
+   # Wrong
+   cursor.execute(f"SELECT * FROM orders WHERE {field} = '{value}'")
+
+   # Correct
+   ALLOWED_FIELDS = {"status": "orders.status", "created_at": "orders.created_at"}
+   column = ALLOWED_FIELDS.get(field)
+   if column is None:
+       raise ValidationError(f"Unknown filter field: {field}")
+   cursor.execute(f"SELECT * FROM orders WHERE {column} = %s", [value])
+   ```
+
+2. **Exposing un-indexed filter fields without documentation.** Allowing `?filter[description][contains]=invoice` on a varchar column without a full-text index causes a sequential scan on every request. At 1M+ rows, this degrades response time to seconds and can saturate the database under moderate traffic. Either add an index, use a dedicated search engine for text filters, or explicitly document that certain filters are not suitable for high-frequency use.
+
+3. **Silently ignoring unknown filter or sort fields.** When a caller typos a filter field (`?staus=active`), a silent ignore returns the full unfiltered result set — the caller believes the filter was applied and may make incorrect decisions based on the unfiltered data. Always return `400 Bad Request` with a descriptive error listing the valid field names. This surfaces typos immediately rather than causing silent data quality bugs.
+
+4. **Using sort without a tiebreaker.** `ORDER BY updated_at DESC` is non-deterministic when multiple rows share the same `updated_at` timestamp. The database may return these rows in different orders on each query, causing cursor pagination to skip or repeat rows. Always append the primary key as the final sort tiebreaker: `ORDER BY updated_at DESC, id DESC`.
+
+## Details
+
+### RSQL: A Standard Filter Grammar
+
+[RSQL](https://github.com/jirutka/rsql-parser) (RESTful Service Query Language) is a superset of the FIQL feed query language that provides a URL-safe filter expression syntax used by several enterprise APIs:
+
+```
+?q=status==active;priority=gt=2     # status == active AND priority > 2
+?q=status==active,status==paused    # status == active OR status == paused
+?q=name=*acme*                       # name contains "acme"
+```
+
+RSQL is particularly useful when the filter space is large and dynamically defined, as in admin APIs or data-exploration endpoints. For most product APIs, simpler bracket-notation or flat key-value parameters are sufficient and easier for clients to construct without a library.
+
+### Combining Filters with Pagination
+
+When filter and sort parameters are combined with cursor pagination, every filter and sort value must be included in every subsequent page request — the cursor alone does not carry them. Design the paginated endpoint to treat `after`, `sort`, and all `filter` parameters as a single atomic query specification. If a client changes a filter parameter while advancing pages, treat it as a new query starting from page 1.
+
+### Real-World Case Study: Salesforce SOQL-Style Filtering
+
+Salesforce's REST API exposes a SOQL (Salesforce Object Query Language) endpoint that accepts structured queries as URL-encoded strings: `?q=SELECT+Id,Name+FROM+Account+WHERE+Industry='Technology'+ORDER+BY+Name+LIMIT+5`. For customers running large-scale reporting on multi-million-row orgs, Salesforce reported that migrating common filter patterns from ad-hoc field enumeration to indexed SOQL predicates reduced average query execution time by 73% and cut database CPU load by 45% during peak reporting windows.
+
+## Source
+
+- [JSON:API — Filtering](https://jsonapi.org/format/#fetching-filtering)
+- [GitHub REST API — List repository issues](https://docs.github.com/en/rest/issues/issues#list-repository-issues)
+- [OWASP — SQL Injection Prevention Cheat Sheet](https://cheatsheetseries.owasp.org/cheatsheets/SQL_Injection_Prevention_Cheat_Sheet.html)
+- [RSQL Parser](https://github.com/jirutka/rsql-parser)
+- [Stripe API — List all charges (filtering example)](https://stripe.com/docs/api/charges/list)
+
+## Process
+
+1. Define the allow-list of filterable fields: for each field, specify its type (string, number, date, enum), supported operators, and the backing database column. Reject any field name not on the allow-list with `400 Bad Request`.
+2. Choose a filter parameter syntax (flat key-value, bracket notation, or RSQL) and document it consistently across all list endpoints in the API.
+3. Implement parameterized query construction: map field names to column references in code, never via string interpolation. Verify the query plan for every filterable field; add indexes where missing.
+4. Define and document sort field support: allowed sort fields, default sort, sort direction syntax (`-` prefix for DESC). Always append the primary key as a sort tiebreaker.
+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-nested-vs-flat, api-pagination-cursor, api-field-selection, db-query-rewriting
+
+## Success Criteria
+
+- All filter field names are validated against an explicit allow-list before use in query construction; unknown fields return `400 Bad Request`.
+- Filter values are passed to the database via parameterized queries, never string interpolation.
+- Every filterable field exposed in the API is backed by a database index; un-indexed filter fields are documented with performance caveats.
+- Sort parameters include the primary key as a tiebreaker to ensure deterministic ordering.
+- Filter combination semantics (AND vs. OR) are documented in the API reference for every list endpoint.

package/dist/agents/skills/gemini-cli/api-filtering-sorting/skill.yaml

@@ -0,0 +1,40 @@
+name: api-filtering-sorting
+version: '1.0.0'
+description: Query parameter design for filter operators (eq, gt, lt, in, contains), sort syntax, filter injection prevention, and performance hints
+stability: static
+cognitive_mode: advisory-guide
+type: knowledge
+tier: 3
+triggers:
+  - manual
+platforms:
+  - claude-code
+  - gemini-cli
+  - cursor
+  - codex
+tools: []
+paths: []
+related_skills:
+  - api-nested-vs-flat
+  - api-pagination-cursor
+  - api-field-selection
+  - db-query-rewriting
+stack_signals:
+  - rest
+  - api
+  - http
+keywords:
+  - filtering
+  - sorting
+  - query-parameters
+  - filter-operators
+  - sort-order
+  - field-filtering
+  - rsql
+metadata:
+  author: community
+  upstream: jsonapi.org/format/#fetching-filtering
+state:
+  persistent: false
+  files: []
+depends_on: []

package/dist/agents/skills/gemini-cli/api-hateoas/SKILL.md

@@ -0,0 +1,212 @@
+# HATEOAS
+
+> Hypermedia As The Engine Of Application State (HATEOAS) embeds links to available next actions in every API response. Clients navigate the API by following links rather than constructing URLs — making the API self-describing and decoupling clients from URL structure.
+
+## When to Use
+
+- Designing an API with complex, state-dependent workflows (order lifecycle, document approvals)
+- Building a public API where URL changes must not break long-lived third-party integrations
+- Evaluating whether to adopt HAL, JSON:API, or a custom link format
+- Reviewing a response that hardcodes related resource URLs as string fields
+- Explaining why returning `"authorId": 42` is different from returning `"author": { "href": "/users/42" }`
+- Deciding whether HATEOAS cost is justified for an internal API
+
+## Instructions
+
+### Key Concepts
+
+HATEOAS is the constraint that distinguishes Level 3 from Level 2 in the Richardson Maturity Model (see `api-rest-maturity-model`). A HATEOAS response tells the client what it can do next, not just what the current state is.
+
+**Without HATEOAS (Level 2):**
+
+```json
+{
+  "id": 42,
+  "status": "pending",
+  "amount": 150.0
+}
+```
+
+The client knows the order is pending, but must have out-of-band knowledge that it can call `DELETE /orders/42` to cancel or `POST /orders/42/payments` to pay. If those URLs change, clients break silently.
+
+**With HATEOAS (Level 3):**
+
+```json
+{
+  "id": 42,
+  "status": "pending",
+  "amount": 150.0,
+  "_links": {
+    "self": { "href": "/orders/42" },
+    "cancel": { "href": "/orders/42", "method": "DELETE" },
+    "pay": { "href": "/orders/42/payments", "method": "POST" },
+    "customer": { "href": "/customers/7" }
+  }
+}
+```
+
+The server controls what actions are available. When the order is paid, the `pay` link disappears and a `refund` link appears. The client does not need to know that paid orders cannot be paid again — the server stops advertising the action.
+
+**HAL (Hypertext Application Language):**
+
+HAL is the most widely adopted hypermedia format. It uses `_links` for navigation and `_embedded` for inline related resources.
+
+```json
+{
+  "id": 42,
+  "status": "shipped",
+  "total": 89.99,
+  "_links": {
+    "self": { "href": "/orders/42" },
+    "customer": { "href": "/customers/7" },
+    "track": { "href": "/shipments/s99" }
+  },
+  "_embedded": {
+    "items": [
+      {
+        "sku": "ABC-123",
+        "quantity": 2,
+        "_links": { "self": { "href": "/products/ABC-123" } }
+      }
+    ]
+  }
+}
+```
+
+**JSON:API link format:**
+
+```json
+{
+  "data": {
+    "type": "orders",
+    "id": "42",
+    "attributes": { "status": "shipped", "total": 89.99 },
+    "links": { "self": "/orders/42" },
+    "relationships": {
+      "customer": {
+        "links": { "related": "/customers/7" }
+      }
+    }
+  }
+}
+```
+
+### Worked Example
+
+A document approval workflow has states: `draft`, `submitted`, `under_review`, `approved`, `rejected`. Valid transitions depend on current state and the caller's role.
+
+**Without HATEOAS:**
+Clients must embed a state machine: "if status is `submitted` and I am a reviewer, I can call `POST /documents/d1/approvals` or `POST /documents/d1/rejections`." This logic must be duplicated in every client. When the workflow changes, every client must be updated.
+
+**With HATEOAS:**
+
+```json
+GET /documents/d1
+→ 200 OK
+{
+  "id": "d1",
+  "title": "Q4 Report",
+  "status": "submitted",
+  "_links": {
+    "self": { "href": "/documents/d1" },
+    "approve": { "href": "/documents/d1/approvals", "method": "POST" },
+    "reject": { "href": "/documents/d1/rejections", "method": "POST" },
+    "history": { "href": "/documents/d1/history" }
+  }
+}
+```
+
+A reviewer sees `approve` and `reject` links. The document author sees only `self` and `history`. The state machine lives on the server; clients follow what is advertised.
+
+**Pagination as a practical HATEOAS application:**
+
+```json
+GET /orders?page=3
+{
+  "items": [...],
+  "_links": {
+    "self":  { "href": "/orders?page=3" },
+    "prev":  { "href": "/orders?page=2" },
+    "next":  { "href": "/orders?page=4" },
+    "first": { "href": "/orders?page=1" },
+    "last":  { "href": "/orders?page=11" }
+  }
+}
+```
+
+This is HATEOAS in practice. The client never constructs pagination URLs. See `api-pagination-cursor` for cursor-based navigation links.
+
+### Anti-Patterns
+
+1. **HATEOAS without documented link relations.** Links like `"action123": { "href": "..." }` are meaningless without documentation. Use IANA-registered link relations (`self`, `next`, `prev`, `edit`, `delete`) or define custom relations in your API documentation with consistent semantics.
+
+2. **Adding `_links` to every response regardless of whether it adds value.** A `self` link on a deeply internal resource no client navigates to is noise. Apply HATEOAS where it actually changes client behavior — state machines, pagination, and discovery.
+
+3. **HATEOAS as a substitute for documentation.** Links advertise available transitions; they do not describe request bodies, required fields, or error semantics. HATEOAS and OpenAPI are complementary, not alternatives.
+
+4. **Mixing HATEOAS depth inconsistently.** Some resources return `_links`, others return bare IDs. Inconsistency forces clients to handle both patterns. If you adopt HATEOAS, apply it uniformly or not at all.
+
+5. **Hardcoding URLs in the client and ignoring the links.** The entire benefit of HATEOAS is that clients follow links rather than construct URLs. If your clients build URLs from templates and ignore the `_links`, you are paying the response-size cost with none of the decoupling benefit.
+
+## Details
+
+### The Real Cost of HATEOAS
+
+Implementing HATEOAS increases:
+
+- **Response size.** Every response carries link metadata. On high-volume endpoints, this adds meaningful bandwidth.
+- **Server complexity.** The server must compute which links are valid for the current state and caller role.
+- **Client complexity.** Clients must traverse links rather than construct URLs. Link-following clients are more complex to implement and test.
+- **Cache coherence.** Links may change when state changes. A cached response with stale links misleads clients. Set appropriate `Cache-Control` values.
+
+**When the cost is worth it:**
+
+- State-machine workflows where valid transitions depend on server-side state (order lifecycle, approvals, fulfillment)
+- Long-lived public APIs where URL stability over years matters more than response compactness
+- APIs with many third-party integrators who cannot be coordinated for URL migrations
+
+**When to skip it:**
+
+- Internal APIs where both client and server are deployed together
+- Simple CRUD APIs with no meaningful state machine
+- Mobile-first APIs where response size is a hard constraint
+
+### Industry Adoption
+
+Most major APIs implement partial HATEOAS: pagination links universally, state-transition links selectively, full HAL rarely.
+
+- **GitHub:** Returns `Link` header for pagination (`next`, `prev`, `last`). Does not use HAL body links.
+- **Stripe:** Returns `url` fields on resources but not HAL `_links`. Uses expand parameters rather than embedded resources.
+- **PayPal:** Full HATEOAS with HAL `_links` including `self`, `approve`, `capture`, `void` on payment objects. One of the most complete HATEOAS implementations in a major public API.
+- **Shopify:** No HATEOAS; cursor-based pagination via `Link` headers.
+
+The pragmatic conclusion: implement pagination links always, state-transition links for complex workflows, and full HAL only when client-server decoupling over time is a first-class requirement.
+
+## Source
+
+- Fielding, R.T. "Architectural Styles and the Design of Network-based Software Architectures" (2000) — original HATEOAS definition
+- [HAL Specification](https://stateless.group/hal_specification.html)
+- [JSON:API Specification](https://jsonapi.org/)
+- [IANA Link Relations Registry](https://www.iana.org/assignments/link-relations/link-relations.xhtml)
+- [Martin Fowler — Richardson Maturity Model](https://martinfowler.com/articles/richardsonMaturityModel.html)
+
+## Process
+
+1. Identify state machines in your domain: resources that have a `status` field with constrained valid transitions (order lifecycle, document approval, subscription state).
+2. For those resources, add `_links` to responses that advertise only currently valid transitions for the caller's role. Use IANA-registered relation names where possible.
+3. Implement pagination links (`next`, `prev`, `first`, `last`) on all collection endpoints — this is the highest-ROI HATEOAS application.
+4. For internal or simple CRUD APIs, consider limiting HATEOAS to pagination links and evaluating whether full link embedding is justified.
+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-rest-maturity-model, api-pagination-cursor, api-resource-modeling, api-http-methods
+
+## Success Criteria
+
+- Pagination responses include `next`, `prev`, `first`, and `last` links in `_links` or `Link` headers.
+- State-machine resources advertise only currently valid transitions in `_links`, filtered by caller role.
+- Link relations use IANA-registered names (`self`, `next`, `prev`, `edit`) or are documented custom relations.
+- HATEOAS is applied uniformly across the API — no mixed patterns where some resources use `_links` and others return bare IDs for the same type of relationship.