gateway-routes Package Skill

Package: @epicdm/gateway-routes Repository: epic-flowstate-community Path: packages/gateway-routes Version: 0.1.7

Use this published Dojo skill as the package-level entrypoint. For detailed workflows, use the package-local skills listed below.

Primary Package Workflow

Gateway Agent Kong Extensions

Status: Active Purpose: Preserve the full-regeneration contract for orchestrator-managed agent Kong routes. Scope: packages/gateway-routes/src/emit-kong.ts plus consumers in packages/flowstate-workers/src/orchestrator/kong-routes.ts. Trigger: A task touches dynamic agent routing, agentServices, agentPlugins, Kong sidecar reconciliation, or worker-orchestrator gateway output. Input: Base ROUTES, agent service descriptors, agent plugin descriptors, and expected Kong output. Output: Deterministic Kong YAML generated by emitKong without manual string merging.

Core Rule

Do not splice Kong YAML fragments into a previously generated file. The orchestrator should gather current registry state, then call emitKong(ROUTES, { agentServices, agentPlugins, ...options }) so the whole config is regenerated consistently.

Data Shapes

Use exported types from @epicdm/gateway-routes:

Workflow

1. Inspect the consumer path, usually packages/flowstate-workers/src/orchestrator/kong-routes.ts.
2. Build sorted agentServices and agentPlugins from the authoritative registry state.
3. Pass them into emitKong; do not use marker replacement as the primary generation path.
4. Preserve JWT_CLAIMS_LUA reuse so agent routes do not drift from base route identity handling.
5. Add tests that call emitKong(ROUTES, optionsWithAgents) twice and compare deterministic output.
6. Add tests that parse or structurally inspect the generated service, route, consumer, and plugin sections.

Example

import { ROUTES, emitKong, type KongEmitOptions } from '@epicdm/gateway-routes'

const options: KongEmitOptions = {
  gatewayPort: 7080,
  jwtIssuer: 'http://localhost:7080',
  jwtConsumer: 'flowstate-auth',
  agentServices,
  agentPlugins,
}

const yaml = emitKong(ROUTES, options)

Verification

yarn workspace @epicdm/gateway-routes test -- emit-kong
yarn workspace @epicdm/flowstate-workers test -- kong-routes

Run package typecheck after changing exported types.

Red Flags

Created: 2026-06-29

Package Skill Inventory

Package Skill Inventory: @epicdm/gateway-routes

Package Context

This package teaches gateway route operations. Skills must route agents to the correct runtime boundary: route table, logical bindings, Kong, Cloudflare, smoke specs, dynamic agent routes, or package maintenance.

Skill Map

Anti-Sprawl Decision: Eight skills are warranted because the package has distinct public surfaces with different failure modes. Merging them would hide route/runtime safety rules.

Feature Coverage

Composition Model

Start with flowstate-gateway-routes, then route to the focused skill matching the touched public surface. Use maintenance after behavior changes to update docs, feature inventory, and Dojo artifacts.

Deferred Skills

No additional skills deferred. Downstream consumer-specific guidance belongs in those package skills.

Review Questions

• Should the community package gain an automated upstream parity check?
• Should Dojo publish IDs use the community package ID or canonical platform package ID when both exist?

Review Gate

Package Skills Review: @epicdm/gateway-routes

Verdict

Pass

Findings

Coverage

Drift and Contract Risks

Dojo Publication Decision

Ready after rebuilt skill.yaml, course.json, and sync-state.json pass local validation.

Follow-Up Work

• Add automated upstream parity check if route drift becomes frequent.
• Retry Cloud Dojo publish after authenticated session is repaired.

Start with this skill to understand the package purpose, then use the package-local focused skills for specific workflows. Keep this Dojo version aligned with packages/gateway-routes/package.json. Do not treat generated feature lists as lessons; use workflow evidence from CODE-REVIEW.md, SKILL-INVENTORY.md, and REVIEW.md.