@mmerterden/multi-agent-pipeline 20.2.1 → 20.3.0

package/pipeline/skills/shared/external/android-performance/references/patterns.md

@@ -79,10 +79,10 @@ class BaselineProfileGenerator {
             device.findObject(By.text("Search")).click()
             device.waitForIdle()
 
-            device.findObject(By.res("search_field")).text = "Istanbul"
+            device.findObject(By.res("search_field")).text = "London"
             device.waitForIdle()
 
-            device.findObject(By.res("flight_card")).click()
+            device.findObject(By.res("order_card")).click()
             device.waitForIdle()
         }
     }
@@ -106,7 +106,7 @@ class BaselineProfileGenerator {
 ```kotlin
 // Mark a class as truly immutable (all properties never change after construction)
 @Immutable
-data class FlightUiModel(
+data class OrderUiModel(
     val id: String,
     val route: String,
     val price: String,
@@ -116,8 +116,8 @@ data class FlightUiModel(
 // Mark a class as stable (Compose can track changes via equals)
 @Stable
 data class FilterState(
-    val origin: String = "",
-    val destination: String = "",
+    val store: String = "",
+    val region: String = "",
     val date: LocalDate? = null,
 )
 ```
@@ -132,19 +132,19 @@ implementation("org.jetbrains.kotlinx:kotlinx-collections-immutable:0.3.8")
 
 // Usage
 @Immutable
-data class FlightListUiState(
-    val flights: ImmutableList<FlightUiModel> = persistentListOf(),
+data class OrderListUiState(
+    val orders: ImmutableList<OrderUiModel> = persistentListOf(),
     val isLoading: Boolean = false,
 )
 
 // Convert in ViewModel
-val uiState: StateFlow<FlightListUiState> = repository.getFlights()
-    .map { flights ->
-        FlightListUiState(
-            flights = flights.map(::toUiModel).toImmutableList(),
+val uiState: StateFlow<OrderListUiState> = repository.getOrders()
+    .map { orders ->
+        OrderListUiState(
+            orders = orders.map(::toUiModel).toImmutableList(),
         )
     }
-    .stateIn(viewModelScope, SharingStarted.WhileSubscribed(5000), FlightListUiState())
+    .stateIn(viewModelScope, SharingStarted.WhileSubscribed(5000), OrderListUiState())
 ```
 
 ### Strong Skipping Mode (Kotlin 2.0+)
@@ -224,17 +224,17 @@ efficiently diff items.
 // CORRECT: stable key from item ID
 LazyColumn {
     items(
-        items = flights,
-        key = { flight -> flight.id },
-    ) { flight ->
-        FlightCard(flight = flight)
+        items = orders,
+        key = { order -> order.id },
+    ) { order ->
+        OrderCard(order = order)
     }
 }
 
 // WRONG: no key -- full list diff on every change
 LazyColumn {
-    items(flights) { flight ->
-        FlightCard(flight = flight)
+    items(orders) { order ->
+        OrderCard(order = order)
     }
 }
 ```
@@ -248,14 +248,14 @@ LazyColumn {
         key = { it.id },
         contentType = { item ->
             when (item) {
-                is FeedItem.Flight -> "flight"
+                is FeedItem.Order -> "order"
                 is FeedItem.Hotel -> "hotel"
                 is FeedItem.Ad -> "ad"
             }
         },
     ) { item ->
         when (item) {
-            is FeedItem.Flight -> FlightCard(item)
+            is FeedItem.Order -> OrderCard(item)
             is FeedItem.Hotel -> HotelCard(item)
             is FeedItem.Ad -> AdBanner(item)
         }
@@ -270,16 +270,16 @@ similar to RecyclerView's view type system.
 
 ```kotlin
 // WRONG: formatting on every recomposition
-items(flights, key = { it.id }) { flight ->
+items(orders, key = { it.id }) { order ->
     val formatted = SimpleDateFormat("HH:mm", Locale.getDefault())
-        .format(Date(flight.departureTime))
+        .format(Date(order.placedAt))
     Text(formatted)
 }
 
 // CORRECT: precompute in ViewModel or UiModel
-data class FlightUiModel(
+data class OrderUiModel(
     val id: String,
-    val formattedDeparture: String, // precomputed
+    val formattedPlacedAt: String, // precomputed
 )
 ```
 
@@ -292,8 +292,8 @@ LazyColumn(
     // For custom behavior:
     flingBehavior = ScrollableDefaults.flingBehavior(),
 ) {
-    items(flights, key = { it.id }) { flight ->
-        FlightCard(flight = flight)
+    items(orders, key = { it.id }) { order ->
+        OrderCard(order = order)
     }
 }
 ```
@@ -448,7 +448,7 @@ class StartupBenchmark {
             pressHome()
             startActivityAndWait()
 
-            val list = device.findObject(By.res("flight_list"))
+            val list = device.findObject(By.res("order_list"))
             list.setGestureMargin(device.displayWidth / 5)
             list.fling(Direction.DOWN)
             device.waitForIdle()
@@ -516,7 +516,7 @@ implementation("io.coil-kt:coil-compose:2.7.0")
 
 // Composable
 @Composable
-fun FlightImage(imageUrl: String, modifier: Modifier = Modifier) {
+fun OrderImage(imageUrl: String, modifier: Modifier = Modifier) {
     AsyncImage(
         model = ImageRequest.Builder(LocalContext.current)
             .data(imageUrl)
@@ -524,7 +524,7 @@ fun FlightImage(imageUrl: String, modifier: Modifier = Modifier) {
             .memoryCacheKey(imageUrl)
             .diskCacheKey(imageUrl)
             .build(),
-        contentDescription = "Flight image",
+        contentDescription = "Order image",
         modifier = modifier,
         contentScale = ContentScale.Crop,
     )
@@ -576,10 +576,10 @@ AsyncImage(
 ```kotlin
 AsyncImage(
     model = imageUrl,
-    contentDescription = "Airline logo",
-    placeholder = painterResource(R.drawable.placeholder_airline),
-    error = painterResource(R.drawable.error_airline),
-    fallback = painterResource(R.drawable.default_airline),
+    contentDescription = "Brand logo",
+    placeholder = painterResource(R.drawable.placeholder_brand),
+    error = painterResource(R.drawable.error_brand),
+    fallback = painterResource(R.drawable.default_brand),
     modifier = Modifier
         .size(48.dp)
         .clip(CircleShape),
@@ -592,7 +592,7 @@ AsyncImage(
 
 ```kotlin
 @Composable
-fun FlightList(flights: List<Flight>) {
+fun OrderList(orders: List<Order>) {
     val listState = rememberLazyListState()
 
     // Only recalculates when the derived condition changes
@@ -602,7 +602,7 @@ fun FlightList(flights: List<Flight>) {
 
     Box {
         LazyColumn(state = listState) {
-            items(flights, key = { it.id }) { FlightCard(it) }
+            items(orders, key = { it.id }) { OrderCard(it) }
         }
 
         if (showScrollToTop) {
@@ -640,12 +640,12 @@ fun DateDisplay(timestamp: Long) {
 ```kotlin
 @HiltViewModel
 class SearchViewModel @Inject constructor(
-    private val searchUseCase: SearchFlightsUseCase,
+    private val searchUseCase: SearchOrdersUseCase,
 ) : ViewModel() {
 
     private val searchQuery = MutableStateFlow("")
 
-    val searchResults: StateFlow<List<Flight>> = searchQuery
+    val searchResults: StateFlow<List<Order>> = searchQuery
         .debounce(300) // Wait 300ms after last keystroke
         .distinctUntilChanged()
         .filter { it.length >= 2 }

package/pipeline/skills/shared/external/api-patterns/SKILL.md

@@ -1,73 +1,117 @@
 ---
 name: api-patterns
-description: "API design principles and decision-making. REST vs GraphQL vs tRPC selection, response formats, versioning, pagination. Use when choosing between REST, GraphQL and tRPC, or shaping response formats, versioning and pagination."
-risk: unknown
-source: community
-date_added: "2026-02-27"
+description: "Choosing an API style (REST, GraphQL, gRPC, webhooks, events) and the contracts every style needs: versioning, cursor pagination, idempotency keys, RFC 9457 errors. Use when deciding how two systems talk or how a contract evolves."
+metadata:
+  risk: safe
+  source: multi-agent-pipeline
+  date_added: "2026-09-25"
+  not-for: rest-api-design
 ---
 
 # API Patterns
 
-> API design principles and decision-making for 2025.
-> **Learn to THINK, not copy fixed patterns.**
-
-## 📑 Topics
-
-| Topic | Covers | When it applies |
-|------|-------------|--------------|
-| API style | REST vs GraphQL vs tRPC decision tree | Choosing API type |
-| REST | Resource naming, HTTP methods, status codes | Designing REST API |
-| Response shape | Envelope pattern, error format, pagination | Response structure |
-| GraphQL | Schema design, when to use, security | Considering GraphQL |
-| tRPC | TypeScript monorepo, type safety | TS fullstack projects |
-| Versioning | URI/Header/Query versioning | API evolution planning |
-| Auth | JWT, OAuth, Passkey, API Keys | Auth pattern selection |
-| Rate limiting | Token bucket, sliding window | API protection |
-| Documentation | OpenAPI/Swagger best practices | Documentation |
-| Security testing | OWASP API Top 10, auth/authz testing | Security audits |
-
----
-
-## 🔗 Related Skills
-
-| Need | Skill |
-|------|-------|
-| API implementation | `@[skills/backend-development]` |
-| Data structure | `@[skills/database-design]` |
-| Security details | `@[skills/security-hardening]` |
-
----
-
-## ✅ Decision Checklist
-
-Before designing an API:
-
-- [ ] **Asked user about API consumers?**
-- [ ] **Chosen API style for THIS context?** (REST/GraphQL/tRPC)
-- [ ] **Defined consistent response format?**
-- [ ] **Planned versioning strategy?**
-- [ ] **Considered authentication needs?**
-- [ ] **Planned rate limiting?**
-- [ ] **Documentation approach defined?**
-
----
-
-## ❌ Anti-Patterns
-
-**DON'T:**
-- Default to REST for everything
-- Use verbs in REST endpoints (/getUsers)
-- Return inconsistent response formats
-- Expose internal errors to clients
-- Skip rate limiting
-
-**DO:**
-- Choose API style based on context
-- Ask about client requirements
-- Document thoroughly
-- Use appropriate status codes
-
----
-
-## When to Use
-This skill is applicable to execute the workflow or actions described in the overview.
+An interface outlives the code on both sides of it. Clients ship on their own
+schedule, mobile builds stay installed for years, and partner integrations get
+written once and forgotten. The decisions here are the ones that are expensive
+to reverse, so make them deliberately and write the reasoning down.
+
+This skill covers the choice of style and the contracts that apply whatever
+style wins. REST mechanics (URLs, verbs, status codes, cache headers, OpenAPI)
+live in `rest-api-design`; security controls live in `api-security-best-practices`.
+
+## 1. Start from the consumers, not the technology
+
+Answer these before naming a style:
+
+- **Who calls it?** Your own frontend, other internal services, third parties
+  you do not control, or devices that update rarely.
+- **What is the interaction shape?** Ask-and-answer, a long-running job, a
+  notification that something happened, or a continuous feed.
+- **Who owns change?** If one team owns both ends, coupling is cheap. If the
+  caller is outside your release train, every change is a negotiation.
+- **What does the network look like?** Browser, mobile on flaky links,
+  service mesh inside one data centre.
+
+## 2. Choosing a style
+
+| Situation | Reasonable default | Why |
+|---|---|---|
+| Public or partner API, broad tooling expected | REST over HTTP with an OpenAPI document | Every language and proxy understands it; caching works |
+| One product team owns a rich client with many screens pulling nested data | GraphQL | Client picks fields; one round trip per screen |
+| Internal service-to-service calls with strict latency budgets | gRPC with protobuf | Typed contracts, code generation, HTTP/2 streaming |
+| TypeScript monorepo where server and client ship together | tRPC or a shared schema package | Types flow end to end without a separate IDL |
+| "Tell me when X happens" to an external party | Webhooks | Caller does not poll; you push on change |
+| Many internal consumers reacting to the same fact | Events on a log or broker (Kafka, NATS, SQS/SNS) | Producers stay unaware of consumers |
+| Work that takes longer than a request should | Accept, return a job resource, then poll or notify | Keeps request timeouts honest |
+
+Mixing is normal: a public REST API, gRPC between internal services, and an
+event stream for side effects is a common and healthy shape. What goes wrong is
+picking GraphQL or gRPC for a public surface because it is fashionable, then
+rebuilding caching, auth and tooling that REST gave for free.
+
+### GraphQL specifics worth deciding up front
+
+- Depth and complexity limits, or one query can fan out into thousands of
+  resolver calls.
+- A batching layer (DataLoader or equivalent) so a list of 50 orders does not
+  run 50 customer lookups.
+- Persisted queries for production clients, which also shrink the attack surface.
+- Errors: GraphQL returns 200 with an `errors` array; decide which failures are
+  field-level and which reject the whole operation.
+
+### gRPC specifics
+
+- Never reuse or renumber a protobuf field tag; mark removed ones `reserved`.
+- Set deadlines on every call and propagate them downstream.
+- Browsers need gRPC-Web or Connect; plan a gateway if a web client is coming.
+
+## 3. Evolving a contract
+
+Additive changes (optional fields, new endpoints or event types, enum values
+clients were told to tolerate) ship without a version; removals, renames, type
+or meaning changes need a migration plan. Prefer additive-only, then dated
+versions, then a path major version. Announce deprecation with `Deprecation`
+and `Sunset` headers, measure remaining callers, and check event schema
+compatibility in CI. Details: `references/contract-details.md`.
+
+## 4. Contracts every style needs
+
+Load `references/contract-details.md` for examples. The rules:
+
+- **Pagination**: opaque cursor over the sort key plus a unique tiebreaker,
+  server-capped `limit`, no total count unless it is cheap; offset paging only
+  for small, static data.
+- **Idempotency**: non-idempotent writes accept an `Idempotency-Key` scoped to
+  the caller. Replay the stored result for a completed key, `409` while it is
+  still running, `422` for the same key with a different body; store key and
+  result in the side effect's transaction and expire them after a stated window.
+  Consumers deduplicate on the event id.
+- **Errors**: one RFC 9457 problem-details shape (`application/problem+json`)
+  with a stable `type`, field errors as JSON Pointers, a request id, and no
+  internals. gRPC uses canonical codes plus `google.rpc` details; events go to a
+  dead-letter destination with the reason.
+- **Webhooks**: HMAC-signed timestamp plus body with replay rejection, retries
+  with backoff and jitter then parking, a documented thin or full payload, and
+  replay on request.
+
+## 5. Checklist before publishing a contract
+
+- [ ] Style chosen from consumer and interaction shape, reasoning recorded (ADR).
+- [ ] Machine-readable schema exists: OpenAPI, GraphQL SDL, `.proto`, or event schema.
+- [ ] Unknown fields and enum values are tolerated by clients, and documented as such.
+- [ ] List endpoints paginate with a capped cursor.
+- [ ] Non-idempotent writes accept an idempotency key.
+- [ ] Every error uses the shared problem shape with a stable `type`.
+- [ ] Deprecation policy is written down with a minimum notice period.
+- [ ] A contract test or breaking-change check runs in CI.
+
+## References
+
+- `references/contract-details.md`: pagination, idempotency, problem-details and webhook examples in full.
+
+## Related skills
+
+- `rest-api-design`: URLs, methods, status codes, caching headers, OpenAPI.
+- `api-security-best-practices`: authentication, authorization, rate limits.
+- `architecture`: recording the decision as an ADR.
+- `nodejs-backend-patterns`, `fastapi-pro`: implementing the chosen contract.

package/pipeline/skills/shared/external/api-patterns/references/contract-details.md

@@ -0,0 +1,128 @@
+# API contract details
+
+Versioning rules and worked examples for the pagination, idempotency, error-shape and webhook rules summarised in SKILL.md.
+
+## Contents
+
+- Evolving a contract
+- Pagination
+- Idempotency for retried writes
+- One error shape everywhere
+- Webhooks done properly
+
+## Evolving a contract
+
+Treat every published field as a promise. Additive change is almost always safe;
+removal, renaming and changing meaning are not.
+
+Safe without a new version:
+
+- adding an optional request field or a new response field;
+- adding a new endpoint, RPC or event type;
+- adding an enum value, **only if** clients were told to tolerate unknown values.
+
+Breaking, needs a migration plan:
+
+- removing or renaming a field, or making an optional field required;
+- changing a type, unit or format (`price` from cents to decimal string);
+- changing default behaviour or the meaning of a status.
+
+Versioning mechanics, from lightest to heaviest:
+
+1. **No explicit version, additive only.** Works longer than people expect.
+2. **Dated versions** pinned per client (`Api-Version: 2026-06-01`), with the
+   server translating older shapes. Good for public APIs with many integrators.
+3. **Major version in the path** (`/v2/orders`). Simple to route and reason
+   about, costly to maintain two copies.
+
+Whatever the scheme, publish a deprecation window, emit a `Deprecation` and
+`Sunset` header (RFC 9745 / RFC 8594) on retiring endpoints, and measure who is
+still calling before you switch anything off.
+
+For events, the same rules apply to the payload schema. Keep a schema registry
+or a versioned schema file and run a compatibility check in CI.
+
+## Pagination
+
+Offset pagination (`?page=7`) is easy and wrong for data that changes: rows
+shift between requests and deep pages get slow. Prefer an opaque cursor.
+
+```http
+GET /products?limit=50&after=eyJpZCI6IjAxSjhRIn0
+
+200 OK
+{
+  "data": [ ... ],
+  "page": { "next": "eyJpZCI6IjAxSjk0In0", "hasMore": true }
+}
+```
+
+- The cursor encodes the sort key plus a unique tiebreaker (`created_at`, `id`)
+  and is base64 so clients treat it as opaque.
+- Cap `limit` on the server; ignore or clamp values above it.
+- Do not promise a total count unless it is cheap; counting a large table on
+  every page request is a common production hotspot.
+- Streaming or long-lived exports are a job, not a very large page.
+
+## Idempotency for retried writes
+
+Networks drop responses, not just requests. A client that times out on
+`POST /orders` cannot know if the order exists. Give it a way to retry safely.
+
+```http
+POST /orders
+Idempotency-Key: 5f1c2d0e-8b7a-4c77-9a61-0d3f6c1b2a90
+Content-Type: application/json
+
+{ "productId": "p_812", "quantity": 2 }
+```
+
+Server behaviour:
+
+1. Look up the key scoped to the caller. If a completed result exists, return it
+   unchanged, including the original status code.
+2. If a request with that key is still running, return `409 Conflict` so the client backs off.
+3. If the same key arrives with a different body, reject it with `422`.
+4. Store the key and result in the same transaction as the side effect, and
+   expire keys after a stated window (24 hours is typical).
+
+`PUT` and `DELETE` are idempotent by definition, but only if your handler is.
+Webhook and event consumers need the same property: deduplicate on the event id,
+because at-least-once delivery means duplicates will arrive.
+
+## One error shape everywhere
+
+Use RFC 9457 problem details for HTTP APIs. Clients then write one error
+handler instead of one per endpoint.
+
+```json
+{
+  "type": "https://api.example.com/problems/insufficient-stock",
+  "title": "Not enough stock",
+  "status": 409,
+  "detail": "Only 1 unit of product p_812 is available.",
+  "instance": "/orders/req_01J9Z",
+  "errors": [{ "pointer": "/quantity", "detail": "must be at most 1" }]
+}
+```
+
+- `type` is a stable identifier clients can branch on; `title` is for humans.
+- Put field-level validation failures in an extension member (`errors` above)
+  using JSON Pointers into the request body.
+- Never leak stack traces, SQL or internal hostnames in `detail`.
+- Include a request or trace id so support can find the log line.
+- Serve it as `application/problem+json`.
+
+For gRPC, map to canonical status codes and attach `google.rpc` error details;
+for events, a failed consumer moves the message to a dead-letter destination
+with the reason attached.
+
+## Webhooks done properly
+
+- Sign every delivery (HMAC-SHA256 over timestamp plus body) and document how to
+  verify it; reject deliveries older than a few minutes to stop replay.
+- Retry with exponential backoff and jitter for a bounded period, then park the
+  delivery and surface it in a dashboard.
+- Send a thin payload (event type, id, resource URL) or a full snapshot, and say
+  which; thin payloads avoid stale data at the cost of a follow-up call.
+- Let integrators replay past deliveries; they will lose some.