feat(api): add landscape governance and topology (#354)

Add portfolio, lifecycle, topology, policy-placement, assessment, and eval guidance while preserving contract ownership boundaries.\n\nAI-assisted: Jasper orchestrated implementation and verification with OpenCode.

Signed-off-by: Magnus Hedemark <magnus919@pm.me>

.claude-plugin/marketplace.json

@@ -93,7 +93,7 @@
         "./api-design-and-evolution"
       ],
       "strict": false,
-      "description": "Design, document, review, and evolve consumer-facing APIs and event interfaces. Use when choosing REST/HTTP, GraphQL, RPC, events, webhooks, or streaming; writing OpenAPI or AsyncAPI contracts; defining schemas, pagination, mutations, errors, idempotency, or API compatibility; or planning API versioning, deprecation, and migration. Use secure-software-engineering for a full security lifecycle, ADR authoring for durable architecture decisions, and spec-driven-development for a delivery specification and implementation gates."
+      "description": "Design, govern, document, review, and evolve consumer-facing APIs and event interfaces. Use when choosing REST/HTTP, GraphQL, RPC, events, webhooks, or streaming; writing OpenAPI or AsyncAPI contracts; assessing an API landscape, ownership, duplication, lifecycle, discoverability, retirement, gateways, service meshes, north-south or east-west traffic, routing, policy, observability, or failure boundaries; defining schemas, pagination, mutations, errors, idempotency, or compatibility; or planning versioning, deprecation, and migration. Do not use for product discovery, platform operations, full security assessment, ADR authoring, or delivery gates; route those to the neighboring specialist skills."
     },
     {
       "name": "artifact-pyramids",

README.md

@@ -46,7 +46,7 @@ Convert Word, PowerPoint, Excel, OpenDocument, RTF, EPUB, CSV, and text-based PD
 
 ### [api-design-and-evolution](api-design-and-evolution/SKILL.md)
 
-Design, document, review, and evolve consumer-facing HTTP, GraphQL, RPC, event, webhook, and streaming interfaces. Covers consumer jobs, domain semantics, contracts, failure behavior, compatibility, deprecation, migration, and deployed-boundary verification.
+Design, govern, document, review, and evolve consumer-facing HTTP, GraphQL, RPC, event, webhook, and streaming interfaces. Covers consumer jobs, domain semantics, API landscapes, ownership, lifecycle, topology, contracts, failure behavior, compatibility, deprecation, migration, and deployed-boundary verification. Do not use for product discovery, platform operations, full security assessment, ADR authoring, or delivery gates.
 
 ### [artifact-pyramids](artifact-pyramids/SKILL.md)
 

api-design-and-evolution/README.md

@@ -1,6 +1,6 @@
 # API Design And Evolution
 
-Design APIs that consumers can integrate with, operate, and migrate without relying on unwritten assumptions.
+Design and govern APIs that consumers can integrate with, operate, and migrate without relying on unwritten assumptions.
 
 ## Why Install This Skill
 
@@ -12,15 +12,17 @@ route or selecting a protocol.
 It produces practical design artifacts for HTTP, GraphQL, RPC, events, webhooks, and
 streams. Your agent can document retries, errors, authorization boundaries, delivery
 semantics, compatibility risks, and a migration path instead of treating an OpenAPI
-file as the whole design.
+file as the whole design. It can also assess a portfolio for ownership, duplication,
+discoverability, lifecycle, and retirement, then separate gateway or ingress concerns
+from service-mesh responsibilities and application contracts.
 
 ## What You Get
 
 | Contents | Provides |
 |---|---|
 | `SKILL.md` | A workflow from discovery through rollout and verification |
-| `references/` | Protocol, schema, failure, event, evolution, testing, and source guidance |
-| `templates/` | Fillable briefs, contracts, taxonomies, assessments, plans, and reviews |
+| `references/` | Protocol, schema, failure, event, evolution, landscape, topology, testing, and source guidance |
+| `templates/` | Fillable briefs, contracts, taxonomies, landscape assessments, plans, and reviews |
 
 ## Quick Start
 
@@ -36,6 +38,8 @@ produce a contract reviewable by consumers and implementers.
 - Define pagination, errors, idempotency, concurrency, or rate/resource behavior
 - Assess a consumer-breaking API change, version an interface, or plan deprecation
 - Build a migration and rollback plan for an external interface
+- Assess an API portfolio, ownership model, discoverability, duplication, lifecycle, or retirement
+- Decide which gateway, ingress proxy, service mesh, routing, policy, telemetry, or failure boundary owns a concern
 
 ## Requirements
 

api-design-and-evolution/SKILL.md

@@ -1,13 +1,15 @@
 ---
 name: api-design-and-evolution
 description: >-
-  Design, document, review, and evolve consumer-facing APIs and event interfaces.
-  Use when choosing REST/HTTP, GraphQL, RPC, events, webhooks, or streaming; writing
-  OpenAPI or AsyncAPI contracts; defining schemas, pagination, mutations, errors,
-  idempotency, or API compatibility; or planning API versioning, deprecation, and
-  migration. Use secure-software-engineering for a full security lifecycle, ADR
-  authoring for durable architecture decisions, and spec-driven-development for a
-  delivery specification and implementation gates.
+  Design, govern, document, review, and evolve consumer-facing APIs and event
+  interfaces. Use when choosing REST/HTTP, GraphQL, RPC, events, webhooks, or
+  streaming; writing OpenAPI or AsyncAPI contracts; assessing an API landscape,
+  ownership, duplication, lifecycle, discoverability, retirement, gateways, service
+  meshes, north-south or east-west traffic, routing, policy, observability, or failure
+  boundaries; defining schemas, pagination, mutations, errors, idempotency, or
+  compatibility; or planning versioning, deprecation, and migration. Do not use for
+  product discovery, platform operations, full security assessment, ADR authoring,
+  or delivery gates; route those to the neighboring specialist skills.
 license: MIT
 compatibility: No runtime dependency. References version- and status-aware public standards indexed in references/source-index.md.
 ---
@@ -36,35 +38,41 @@ assessment, or an implementation test plan. Hand those concerns to
 
 ## Workflow
 
-1. **Discover the agreement.** State consumer jobs, domain terms and invariants,
+1. **Classify the scope.** If the request spans more than one interface, start
+   [templates/api-landscape-assessment.md](templates/api-landscape-assessment.md) and
+   read [references/api-landscape-and-governance.md](references/api-landscape-and-governance.md).
+   If it changes where traffic is admitted, routed, observed, or isolated, read
+   [references/api-infrastructure-topologies.md](references/api-infrastructure-topologies.md).
+   Keep portfolio findings separate from any individual contract decision.
+2. **Discover the agreement.** State consumer jobs, domain terms and invariants,
    authoritative data and schema owners, actors, object/action authority boundaries,
    data sensitivity, and failure modes. Record unanswered questions rather than
    inventing policy. Start [templates/api-design-brief.md](templates/api-design-brief.md).
-2. **Choose the interface shape.** Compare interaction direction, coupling,
+3. **Choose the interface shape.** Compare interaction direction, coupling,
    delivery needs, query flexibility, mutation semantics, caching, observability,
    and evolution surface. Read [references/interface-selection.md](references/interface-selection.md).
    Record the choice and rejected options in the brief; use an ADR only when the
    choice is consequential beyond this interface.
-3. **Make the contract explicit.** Define representations and their semantics,
+4. **Make the contract explicit.** Define representations and their semantics,
    including null versus absent, defaults, enums/unions, identifiers, timestamps,
    units, ordering, filtering, and pagination. Use
    [templates/endpoint-contract.md](templates/endpoint-contract.md) with
    [references/contract-semantics.md](references/contract-semantics.md).
-4. **Design mutation and failure behavior.** Define authority checks, preconditions,
+5. **Design mutation and failure behavior.** Define authority checks, preconditions,
    idempotency scope and equivalence, retries, concurrency, partial outcomes,
    long-running operation state, errors, and resource limits. Read
    [references/operations-and-failures.md](references/operations-and-failures.md)
    and create [templates/error-taxonomy.md](templates/error-taxonomy.md) when
    errors are shared across operations.
-5. **Describe asynchronous delivery where relevant.** For messages, webhooks, or
+6. **Describe asynchronous delivery where relevant.** For messages, webhooks, or
    streams, state the publisher/subscriber perspective, envelope, delivery contract,
    duplicate/gap/reordering behavior, ordering scope, and security boundary. Read
    [references/events-webhooks-streaming.md](references/events-webhooks-streaming.md).
-6. **Assess change from each consumer's perspective.** Inventory consumers,
+7. **Assess change from each consumer's perspective.** Inventory consumers,
    generated clients, strict decoders, signatures, caches, quotas, and operational
    dependencies. Complete [templates/compatibility-change-assessment.md](templates/compatibility-change-assessment.md).
    Do not call a change safe solely because it is additive.
-7. **Plan and verify rollout.** For a deprecation or migration, use
+8. **Plan and verify rollout.** For a deprecation or migration, use
    [templates/deprecation-migration-plan.md](templates/deprecation-migration-plan.md)
    and [references/evolution-and-deprecation.md](references/evolution-and-deprecation.md).
    Review the contract using [templates/contract-review.md](templates/contract-review.md).
@@ -78,6 +86,8 @@ assessment, or an implementation test plan. Hand those concerns to
 
 | Load when | File |
 |---|---|
+| Assessing an API portfolio, ownership, duplication, discoverability, lifecycle, standards, or retirement | [references/api-landscape-and-governance.md](references/api-landscape-and-governance.md) and [templates/api-landscape-assessment.md](templates/api-landscape-assessment.md) |
+| Comparing gateways, ingress proxies, service meshes, traffic direction, routing, policy, telemetry, or failure boundaries | [references/api-infrastructure-topologies.md](references/api-infrastructure-topologies.md) |
 | Selecting REST/HTTP, GraphQL, RPC, event/message, webhook, or streaming | [references/interface-selection.md](references/interface-selection.md) |
 | Modeling data, collection reads, schemas, or OpenAPI | [references/contract-semantics.md](references/contract-semantics.md) |
 | Designing writes, errors, retry behavior, limits, or authorization handoff | [references/operations-and-failures.md](references/operations-and-failures.md) |
@@ -96,6 +106,24 @@ or abuse resistance, load
 [secure-software-engineering](../secure-software-engineering/SKILL.md). An API
 contract cannot prove that an authorization boundary is enforced.
 
+## Ownership Boundaries
+
+- **Product owners** decide consumer outcomes, audience, value, and lifecycle intent;
+  this skill turns those decisions into interface agreements and evidence.
+- **Platform owners** decide gateway, ingress, mesh, networking, deployment, and
+  runtime operations. This skill identifies topology responsibilities and contract
+  consequences but does not operate the substrate.
+- **Security owners** decide threat models, credential and secret controls, abuse
+  resistance, and tenant isolation. This skill records the contract handoff and
+  required authorization behavior without substituting for the assessment.
+- **Architecture owners** decide cross-system principles, significant boundaries,
+  and durable architecture decisions. Use [adr-authoring](../adr-authoring/SKILL.md)
+  when a landscape or topology decision has consequences beyond the API portfolio.
+
+An API landscape assessment is not a product roadmap, platform runbook, security
+review, or enterprise architecture repository. Escalate unresolved ownership,
+authority, or retirement decisions instead of assigning them implicitly.
+
 ## Completion
 
 Stop when the selected interface has an owner, an authoritative contract, explicit

api-design-and-evolution/evals/evals.json

@@ -61,6 +61,42 @@
         "Key validity, uniqueness under concurrency, and key-replay-with-different-payload are addressed",
         "The timeout response shape prevents the double-submit race"
       ]
+    },
+    {
+      "id": "api-landscape-governance",
+      "prompt": "Our company has 40 APIs and several teams expose customer and order data through overlapping REST endpoints. We need a landscape assessment and a governance recommendation without creating a heavyweight central review board. What should we inventory, decide, and measure?",
+      "expected_output": "A landscape assessment that inventories surfaces, authority, owners, audiences, consumers, contracts, lifecycle state, evidence confidence, and topology. It identifies duplication by consumer job and domain authority rather than URL similarity, improves discoverability, assigns lifecycle and retirement ownership, and proposes risk-proportional standards with visible exceptions and local decision rights. It keeps product, platform, security, and architecture responsibilities distinct.",
+      "assertions": [
+        "The assessment includes inventory fields for authority, ownership, consumers, contract, lifecycle, and evidence gaps",
+        "Duplication is evaluated by domain meaning and consumer job, with intentional overlap allowed when justified",
+        "Discoverability and lifecycle include ownership, feedback, deprecation, retirement, and residual dependency evidence",
+        "Governance is proportional to exposure, blast radius, data sensitivity, and reversibility rather than a universal maturity ladder",
+        "The response preserves explicit boundaries with product, platform, security, and architecture owners"
+      ]
+    },
+    {
+      "id": "gateway-mesh-topology",
+      "prompt": "We are adding an ingress gateway and a service mesh while moving internal order traffic between clusters. Explain the north-south and east-west responsibilities, where routing and policy belong, what observability is required, and how to avoid hiding failure or multiplying retries.",
+      "expected_output": "A topology assessment that maps the request path and separates gateway or ingress responsibilities from mesh transport responsibilities and service/domain authorization. It identifies north-south versus east-west traffic, owner and unavailable-component behavior for each policy, timeout and retry ownership, telemetry across hops, and failure boundaries including ambiguous completion. It calls out contract-visible changes during migration and requires deployed-boundary verification.",
+      "assertions": [
+        "North-south and east-west traffic are distinguished with responsibilities for each",
+        "Gateway/ingress and service-mesh concerns are separated without treating either as a universal product boundary",
+        "Routing, identity, policy placement, owner, and fail-open/closed behavior are explicit",
+        "Timeouts, retries, budgets, observability, and failure attribution address retry multiplication and hidden failures",
+        "Topology migration checks contract-visible behavior and deployed-boundary evidence"
+      ]
+    },
+    {
+      "id": "landscape-retirement-boundary",
+      "prompt": "A team wants to delete an old partner API because its dashboard shows almost no traffic. Give me a safe decision process and state which parts belong to API design versus product, platform, security, and architecture owners.",
+      "expected_output": "A retirement decision process that verifies inventory completeness, undocumented and indirect consumers, owner and successor, consumer-specific migration support, telemetry limitations, communication, pause or rollback conditions, residual routes and credentials, and post-retirement monitoring. It distinguishes API contract and lifecycle evidence from product value decisions, platform route removal, security credential or abuse review, and architecture-level cross-domain decisions.",
+      "assertions": [
+        "Low observed traffic is treated as insufficient evidence without checking inventory confidence and hidden consumers",
+        "Retirement requires an owner, successor or explicit no-successor decision, migration support, criteria, communication, and pause/recovery path",
+        "Residual routes, credentials, jobs, caches, SDKs, and indirect dependencies are considered",
+        "Product, platform, security, architecture, and API ownership boundaries are explicit",
+        "The process ends with evidence-based retirement and post-retirement monitoring rather than deletion alone"
+      ]
     }
   ]
 }

api-design-and-evolution/references/api-infrastructure-topologies.md

@@ -0,0 +1,96 @@
+# API Infrastructure Topologies
+
+Use this reference when an API decision depends on where traffic enters, crosses, or
+leaves a system. Topology supports a contract; it does not define the domain agreement.
+Describe the actual path, the responsibility at each hop, and the failure behavior
+consumers can observe.
+
+## Traffic Directions
+
+- **North-south:** traffic between clients or external networks and a service estate.
+  Common concerns include public admission, identity handoff, rate/resource controls,
+  external routing, protocol translation, and partner-facing observability.
+- **East-west:** traffic among services, jobs, brokers, and internal control planes.
+  Common concerns include service identity, discovery, retries and deadlines, locality,
+  load balancing, encryption, dependency policy, and partial-failure containment.
+- **Ingress and egress:** name the boundary explicitly. An ingress proxy may admit
+  traffic into a cluster or domain; an egress control may govern calls leaving it. Do
+  not infer either responsibility from the word "gateway."
+
+## Gateway Versus Service Mesh
+
+Use a gateway or ingress proxy for boundary-facing concerns such as listener and host
+routing, external authentication integration, protocol adaptation, public throttling,
+request-size limits, cross-origin behavior, and consumer-visible access policy. Keep
+domain authorization and contract semantics in the service unless the gateway is an
+explicitly governed policy decision point.
+
+Use a service mesh for service-to-service transport concerns such as service identity,
+encryption between workloads, discovery, load balancing, traffic shifting, retries,
+timeouts, and telemetry propagation. A mesh does not make an unsafe retry safe, prove
+business authorization, or define an event's delivery guarantee.
+
+These are tendencies, not mandatory product boundaries. A deployment may combine
+functions, use no mesh, or place a control in another proxy. Record who owns each
+policy and what happens when the enforcement component is unavailable.
+
+## Map The Request Path
+
+For each important flow, draw or tabulate:
+
+1. caller and trust context;
+2. DNS or discovery and route selection;
+3. ingress/gateway hops and transformations;
+4. mesh sidecars, gateways, or direct service links;
+5. service authorization and contract enforcement;
+6. downstream calls, queues, or data stores;
+7. response, event, or callback path;
+8. telemetry and correlation propagation at every boundary.
+
+For each hop record protocol, timeout/deadline, retry owner, load-balancing scope,
+buffering, size limit, identity propagation, policy decision, and whether the hop can
+duplicate, reorder, delay, or drop work. Never add retries at multiple layers without
+an explicit retry budget and operation safety assessment.
+
+## Place Policy Deliberately
+
+Classify a policy as edge, transport, service, or domain policy. Edge policy can
+protect a public boundary but may lack domain context. Transport policy can constrain
+who may connect and how traffic behaves but cannot replace object/action authorization.
+Service policy can enforce resource and operation rules with domain context. Domain
+policy decides business invariants and state transitions. Duplicate enforcement only
+when the different layers have distinct purposes and failure behavior.
+
+For each policy state the decision owner, source of truth, update path, audit evidence,
+fail-open or fail-closed behavior, and stale-policy risk. Route threat modeling and
+abuse resistance to `secure-software-engineering`.
+
+## Observability And Failure Boundaries
+
+Define signals at the consumer-visible boundary and at internal hops: request outcome,
+latency, saturation, retries, timeouts, rejected policy decisions, route changes, and
+correlation/trace continuity. Attribute failures to the narrowest known boundary and
+preserve enough context to distinguish an edge rejection, proxy failure, mesh failure,
+service failure, dependency failure, and ambiguous completion.
+
+Health checks must reflect the promise they make. A process-level success signal does
+not prove that a dependency or route is usable. Document which failures are retried,
+which are surfaced, which may have caused work despite an error, and how a consumer
+reconciles uncertain outcomes. Coordinate SLO and incident operations with
+`site-reliability-engineering`; do not create platform runbooks here.
+
+## Topology Change
+
+Before moving a route, adding a proxy, or introducing a mesh, compare the old and new
+paths for contract-visible changes: headers, status mapping, timeout, retry, ordering,
+source identity, body limits, caching, streaming support, and telemetry. Use a staged
+coexistence path where feasible. Prove the deployed boundary, rollback or pause trigger,
+and recovery of in-flight or ambiguously completed work. A topology migration does not
+authorize a contract change without the compatibility workflow.
+
+## Topology Exit Check
+
+Stop when traffic direction and paths are explicit, each concern has an owner, policy
+placement and unavailable-component behavior are documented, observability crosses the
+relevant boundaries, failure and retry multiplication are bounded, and any contract
+impact has a separate compatibility assessment.

api-design-and-evolution/references/api-landscape-and-governance.md

@@ -0,0 +1,97 @@
+# API Landscape And Governance
+
+Use this reference when a team needs to understand or steer a collection of APIs,
+not only design one contract. The output is a decision-ready landscape record with
+evidence, owners, exceptions, and follow-up work. It is not a universal maturity
+ladder: capability and risk vary by audience, domain, and change pressure.
+
+## Build The Inventory
+
+Start from published contracts, runtime routes, repositories, gateways, event
+catalogs, client registries, and deployment records. Reconcile them rather than
+treating any one source as complete. For each surface capture:
+
+- business capability and domain authority;
+- interface style, audience, exposure, contract location, and lifecycle state;
+- owning team, accountable product owner, technical contact, and support path;
+- consumers, critical workflows, data classification, and dependency direction;
+- deployment and topology references, traffic evidence, quotas, and incident history;
+- last meaningful change, successor or replacement, and confidence in each fact.
+
+Mark unknowns and stale records explicitly. An inventory that hides uncertainty gives
+false confidence and makes retirement unsafe.
+
+## Find Ownership And Duplication
+
+Map each domain concept to its authoritative owner, then compare interfaces by
+consumer job and semantic responsibility, not by similar URL names. Investigate
+duplicates, wrappers, forks, shadow APIs, version drift, and multiple schemas for the
+same fact. A surface may be intentionally distinct when its audience, authority,
+latency, sensitivity, or failure contract differs. Record the reason; do not merge
+interfaces merely to reduce a count.
+
+Assign one accountable owner for contract meaning and lifecycle. Supporting teams may
+own implementation, gateway configuration, SDKs, or documentation, but those roles
+must not silently replace the authority owner.
+
+## Improve Discoverability
+
+Make the path from a consumer job to a trustworthy interface short. Publish the
+contract, audience, owner, domain vocabulary, examples, authentication handoff,
+limits, support path, lifecycle state, and known compatibility posture in a searchable
+catalog. Link generated artifacts to their source contract and distinguish experimental,
+internal, partner, and public surfaces. Measure failed searches, stale entries,
+unowned surfaces, and support questions as feedback, not as a reason to mandate one
+catalog product.
+
+## Govern The Lifecycle
+
+Treat an API as a product-shaped capability with an accountable problem and consumer
+feedback loop:
+
+1. **Propose:** identify the consumer job, domain owner, audience, alternatives, and
+   expected operational consequences.
+2. **Shape:** define the contract and topology handoffs; check for duplication and
+   reuse without forcing incompatible consumers onto one surface.
+3. **Operate:** collect consumer, reliability, latency, error, adoption, and support
+   evidence with signal definitions appropriate to the interface.
+4. **Improve:** prioritize changes by consumer harm, domain value, and reversibility.
+5. **Deprecate:** name a successor, affected consumers, migration support, telemetry,
+   communication, pause conditions, and evidence-based sunset criteria.
+6. **Retire:** remove only after the owner verifies criteria, residual routes and
+   consumers are understood, and an operational recovery or communication path exists.
+
+Retirement is a decision, not a deletion task. Keep a record of why the surface was
+retired, what replaced it, and what evidence would reveal an overlooked dependency.
+Reuse the contract-level [deprecation and migration plan](../templates/deprecation-migration-plan.md)
+for consumer-specific execution.
+
+## Make Standards Proportional
+
+Set a small baseline for every surface, then add controls where exposure, blast radius,
+data sensitivity, consumer diversity, irreversibility, or regulatory obligations justify
+them. A proportional policy can vary review depth, contract verification, observability,
+support, rollout evidence, and retirement controls by risk class. Keep exceptions
+visible with an owner, rationale, expiry or review condition, and compensating evidence.
+
+Avoid universal thresholds for adoption, latency, review time, version count, or
+retirement windows. Standards are useful when they reduce recurring ambiguity; they are
+harmful when compliance artifacts replace consumer outcomes and operational evidence.
+
+## Ownership Handoffs
+
+- Product owns the consumer problem, audience, value, and lifecycle intent.
+- API owners own domain meaning, contract authority, consumer compatibility, and
+  interface lifecycle evidence.
+- Platform owns the gateway, ingress, mesh, networking, deployment, and runtime
+  controls described in the topology handoff.
+- Security owns threat modeling, credential lifecycle, abuse controls, and isolation.
+- Architecture owners arbitrate cross-domain principles and durable decisions when the
+  blast radius exceeds the API portfolio.
+
+## Landscape Exit Check
+
+Stop when every material surface has an owner and lifecycle state, duplicate or
+intentional overlap has a recorded rationale, discovery gaps are visible, standards
+are tied to risk, retirement candidates have evidence and a recovery/communication
+path, and unresolved decisions are assigned to the accountable owner.

api-design-and-evolution/references/source-index.md

@@ -1,8 +1,6 @@
 # Source Index
 
-Versions, status, and URLs were checked against primary sources on 2026-07-13. Use a
-source for its stated purpose; adoption depends on the applicable organization,
-contract, and deployment. Recheck evolving specifications before relying on them.
+New topology-source rows were checked against primary sources on 2026-08-20. Other rows retain their row-specific verification dates where status is volatile. Use each source for its stated purpose; adoption depends on the applicable organization, contract, and deployment. Recheck evolving specifications before relying on them.
 
 | Source | Exact version/status | Primary URL | Decision use |
 |---|---|---|---|
@@ -21,3 +19,13 @@ contract, and deployment. Recheck evolving specifications before relying on them
 | Digest Fields | RFC 9530, Proposed Standard | https://www.rfc-editor.org/rfc/rfc9530 | Optional content-digest building block. |
 | Idempotency-Key Header Field | `draft-ietf-httpapi-idempotency-key-header-07`, expired Internet-Draft | https://datatracker.ietf.org/doc/draft-ietf-httpapi-idempotency-key-header/ | Convention requiring contract-specific semantics; not an RFC. |
 | RateLimit Fields | `draft-ietf-httpapi-ratelimit-headers-11`, active Internet-Draft/work in progress as checked 2026-07-13 | https://datatracker.ietf.org/doc/draft-ietf-httpapi-ratelimit-headers/ | Evolving rate-limit field model; do not assign an RFC number or substitute fields from an older draft. |
+| Kubernetes Gateway API | Current project documentation as checked 2026-08-20 | https://gateway-api.sigs.k8s.io/ | Gateway and routing resource concepts; confirm the deployed controller's supported feature set. |
+| Envoy architecture overview | Current project documentation as checked 2026-08-20 | https://www.envoyproxy.io/docs/envoy/latest/intro/arch_overview | Proxy data-plane capabilities and boundaries; not a substitute for a platform operating runbook. |
+| Istio architecture | Current project documentation as checked 2026-08-20 | https://istio.io/latest/docs/ops/deployment/architecture/ | Service-mesh control/data-plane concepts and traffic policy; validate version-specific behavior. |
+| OpenTelemetry concepts | Current project documentation as checked 2026-08-20 | https://opentelemetry.io/docs/concepts/observability-primer/ | Cross-boundary traces, metrics, and logs; define API-specific signal ownership separately. |
+
+The issue's private licensed research inputs, *Continuous API Management* and
+*Mastering API Architecture*, informed the gap selection only. No purchased ebook
+text, tables, diagrams, examples, taxonomy, or chapter structure is reproduced here.
+The guidance in the landscape and topology references is an original synthesis for
+this skill and should be checked against the public sources above before adoption.

api-design-and-evolution/templates/api-landscape-assessment.md

@@ -0,0 +1,53 @@
+# API Landscape Assessment
+
+## Scope And Decision
+
+- Assessment date, scope, and evidence sources:
+- Decision or problem this assessment must support:
+- Accountable product, API, platform, security, and architecture owners:
+- Known evidence gaps and confidence:
+
+## Inventory
+
+| Surface | Capability/authority | Audience/exposure | Style and contract | Lifecycle | Owner/contact | Consumers | Evidence/gaps |
+|---|---|---|---|---|---|---|---|
+| | | | | | | | |
+
+## Coherence And Discoverability
+
+- Shared domain concepts and authoritative owners:
+- Duplicates, wrappers, forks, shadow surfaces, or intentional overlap:
+- Rationale for keeping or consolidating each overlap:
+- Catalog, contract, examples, support path, and lifecycle links:
+- Search failures, stale records, undocumented consumers, or unowned surfaces:
+
+## Lifecycle And Governance
+
+- New/change intake and decision locality:
+- Baseline standards and risk factors that increase review depth:
+- Exceptions, compensating controls, owner, and review condition:
+- Consumer feedback, reliability, adoption, support, and compatibility evidence:
+- Deprecation successor, migration support, telemetry, sunset criteria, and pause path:
+- Retirement evidence, residual dependency check, communication, and recovery path:
+
+## Topology And Failure Boundaries
+
+- North-south, east-west, ingress, and egress flows:
+- Gateway/ingress responsibilities and owner:
+- Mesh/service-to-service responsibilities and owner:
+- Routing, identity, policy, transformation, retry, timeout, and limit placement:
+- Observability and correlation at each boundary:
+- Failure behavior, fail-open/closed choices, ambiguous completion, and rollback:
+
+## Findings And Actions
+
+| Priority | Finding/evidence | Consumer or operational impact | Action | Owner | Due condition/status |
+|---|---|---|---|---|---|
+| | | | | | |
+
+## Verdict
+
+- Landscape status: coherent, conditional, blocked, or incomplete:
+- Decisions approved and decisions escalated:
+- Required contract, platform, product, security, or architecture handoffs:
+- Reassessment trigger:

llms.txt

@@ -11,7 +11,7 @@
 - [agent-skills](agent-skills/SKILL.md): Use this skill when creating, reviewing, or editing Agent Skills-format skills, or when implementing skill discovery and loading in an agent client. It covers directory structure, SKILL.md metadata, progressive disclosure, evals, and repository conventions. Do not use this skill for general software work that does not involve the Agent Skills format or lifecycle.
 - [ai-governance](ai-governance/SKILL.md): Design and operate an organization's AI governance system: define governance principles, operating models and decision rights, risk frameworks, lifecycle gates, and fairness, transparency, privacy, security, regulatory, and board-oversight controls. Use when standing up a governance program, tiering AI use-case risk, reviewing an LLM or agent system for governance and safety gaps, mapping a regulation to a compliance plan, scoring governance maturity, or preparing board reporting. For regulated life-sciences use cases, also cover GxP, ALCOA+, data integrity, electronic records, validation/assurance, and QMS interfaces. Do not use for interpreting regulations as legal advice (route to legal-strategy), data-governance mechanics (data-architect/data-engineering), or implementing application security (secure-software-engineering).
 - [anydoc](anydoc/SKILL.md): Convert Word (.doc/.docx/.docm), PowerPoint (.ppt/.pps/.pot/.pptx/.pptm/.ppsx/.ppsm), Excel (.xls/.xlsx/.xlsm/.xlsb), OpenDocument (.odt/.ods/.odp), RTF, EPUB, CSV, and PDF documents to clean GitHub-Flavored Markdown locally with the Any Doc CLI (npx -y @firecrawl/anydoc@0.1.6): headings, GFM tables, slide structure, and footnotes in one pass. Use when a task needs the contents of an office document, spreadsheet, presentation, ebook, or PDF you cannot read directly. Do not use for generating, editing, or validating documents (use documents), for ebook packaging (use epub), or for OCR of scanned or image-only PDFs (anydoc does not OCR; route to OCR tooling).
-- [api-design-and-evolution](api-design-and-evolution/SKILL.md): Design, document, review, and evolve consumer-facing APIs and event interfaces. Use when choosing REST/HTTP, GraphQL, RPC, events, webhooks, or streaming; writing OpenAPI or AsyncAPI contracts; defining schemas, pagination, mutations, errors, idempotency, or API compatibility; or planning API versioning, deprecation, and migration. Use secure-software-engineering for a full security lifecycle, ADR authoring for durable architecture decisions, and spec-driven-development for a delivery specification and implementation gates.
+- [api-design-and-evolution](api-design-and-evolution/SKILL.md): Design, govern, document, review, and evolve consumer-facing APIs and event interfaces. Use when choosing REST/HTTP, GraphQL, RPC, events, webhooks, or streaming; writing OpenAPI or AsyncAPI contracts; assessing an API landscape, ownership, duplication, lifecycle, discoverability, retirement, gateways, service meshes, north-south or east-west traffic, routing, policy, observability, or failure boundaries; defining schemas, pagination, mutations, errors, idempotency, or compatibility; or planning versioning, deprecation, and migration. Do not use for product discovery, platform operations, full security assessment, ADR authoring, or delivery gates; route those to the neighboring specialist skills.
 - [artifact-pyramids](artifact-pyramids/SKILL.md): Organize durable agent research outputs as summaries, analysis, and evidence dossiers. Use when producing multi-layer research artifacts or coordinating research handoffs.
 - [ascii-city-engine](ascii-city-engine/SKILL.md): Build portable, first-person colored ASCII city engines and small GIS-derived city packs. Use when designing terrain-following walking, raycast character rendering, city-provider schemas, or reproducible public-GIS ingestion. Do not use for conventional 3D/WebGL games, multi-level interiors, general GIS analysis, or committing full-resolution GIS archives.
 - [autogen](autogen/SKILL.md): Expert skill for conversational multi-agent AI with Microsoft AutoGen. AssistantAgent, UserProxyAgent, GroupChat, code execution, nested chats, cancellation tokens, tool integration, and MCP support. Use when building conversation-driven multi-agent systems or comparing agent frameworks.

references/skill-triggers.md

@@ -4,7 +4,7 @@ Each skill's `description` field is the canonical routing contract. This conveni
 
 | User says... | Load skill |
 |---|---|
-| "API design", "design an API", "API contract", "OpenAPI", "AsyncAPI", "GraphQL schema", "REST API", "RPC API", "webhook design", "event schema", "streaming API", "API versioning", "API deprecation", "API migration", "API compatibility", "idempotency key", "pagination design", "API error taxonomy" | [api-design-and-evolution](../api-design-and-evolution/SKILL.md) |
+| "API design", "design an API", "API contract", "OpenAPI", "AsyncAPI", "GraphQL schema", "REST API", "RPC API", "webhook design", "event schema", "streaming API", "API versioning", "API deprecation", "API migration", "API compatibility", "idempotency key", "pagination design", "API error taxonomy", "API landscape", "API inventory", "API governance", "API catalog", "API duplication", "API retirement", "API gateway topology", "ingress proxy", "service mesh", "north-south traffic", "east-west traffic" | [api-design-and-evolution](../api-design-and-evolution/SKILL.md) |
 | "build a CLI", "make a CLI tool", "agent-friendly CLI", "add --json flag" | [cli-builder](../cli-builder/SKILL.md) |
 | "CNCF Landscape", "CNCF project", "cloud-native technology shortlist", "compare CNCF projects", "what projects exist for", "technology candidate discovery" | [cncf-landscape](../cncf-landscape/SKILL.md) |
 | "SDD", "spec-driven development", "specification driven", "software factory", "spec first", "spec as code", "SPEC.md template", "write a spec for AI", "AI code generation pipeline", "acceptance criteria", "quality gates", "phase gate review", "BDD for AI", "OpenAPI first", "executable specification" | [spec-driven-development](../spec-driven-development/SKILL.md) |