cogni-dao/cogni / .claude/skills/agent-infrastructure-expert
agent-infrastructure-expert
VerifiedAuthoritative map of Cogni's AI-agent infrastructure — the substrate that turns a LangGraph graph into a billed, observed, durably-orchestrated, deployable production agent. Use when designing/debugging the graph execution path (InProc vs LangGraph Server), the build-ship-run topology (what's in the app image, how the Temporal worker reaches a graph), evals, or deciding which spec in the sprawling agent/langgraph cluster is authoritative. Routes graph-authoring mechanics to agent-development.md and tool-authoring to tools-authoring.md; this skill owns the infrastructure altitude above them. For all dated status (what's built, InProc↔Server alignment, doc DRY/drift) see agent-infrastructure-scorecard. Triggers — "how does a graph actually run in prod", "agent CI/CD", "does a new graph rebuild the worker", "InProc vs Server", "GraphExecutorPort", "where do evals stand", "which agent spec is canonical", "graph execution topology".
Agent Infrastructure Expert
You own the infrastructure altitude of Cogni agents: how a LangGraph graph becomes a production-grade, billed, observable, durably-orchestrated, deployed agent. Graph authoring (factory/prompts/tools/catalog) is one tier below you — route it to agent-development.md. You answer: where does it run, what ships it, how is it billed/observed, and is the eval gate real.
Stable skill, living scorecard. This file holds the mental model and rules that don't move. All dated status — InProc↔Server alignment, built-vs-designed, doc DRY/drift/consolidation, doc-map staleness — lives in
agent-infrastructure-scorecard. When reality moves, update the scorecard, not this skill.
Mental Model — Four Planes
| Plane | What it does | Canonical doc |
|---|---|---|
| Author | Write the graph: pure factory, prompts, toolIds, catalog entry, cogni-exec.ts entrypoint | langgraph-patterns.md + agent-development.md |
| Execute | Run it behind one GraphExecutorPort — billing, credit-preflight, observability, ALS, tool-allowlist decorators, all applied once | graph-execution.md |
| Orchestrate + Ship | Temporal triggers it durably; the graph rides the node app image and runs in-proc; the worker reaches it over HTTP | unified-graph-launch.md + temporal-patterns.md |
| Evaluate | Score graphs after deploy; gate promotion on quality | agent-evaluation-loop |
(Per-plane build status → scorecard.)
Build → Ship → Run Topology (the load-bearing truth)
There is no separate graph artifact, and the graph package never reaches the Temporal worker. Verified from code + catalog:
- Graph code ships inside the node app image.
nodes/<node>/appdepends on@cogni/<node>-graphs→@cogni/langgraph-graphs(workspace:*); Next.js bundles them. Adding a graph = affected-only rebuild of the app target(s) inpr-build.yml. New graph ⇒ app rebuild only — never a worker rebuild (scheduler-workeris its owntype: servicecatalog target with zero graph deps). - The Temporal worker holds no graph code, no DB creds, no LLM keys (
SHARED_COMPUTE_HOLDS_NO_DB_CREDS, task.0280). It is a lean durable dispatcher. - The app IS the executor. Worker activity →
POST {nodeUrl}/api/internal/graphs/:graphId/runs(bearerSCHEDULER_API_TOKEN,Idempotency-Key,nodeId→URL viaCOGNI_NODE_ENDPOINTS) → the node app runs the graph in-proc viacreateScopedGraphExecutor().runGraph()and pumps events to Redis→SSE (EXECUTION_VIA_SERVICE_API).
Temporal (schedule/webhook) → GraphRunWorkflow ─HTTP─► node app /api/internal/graphs/:id/runs
orchestrate (no graph code) execute in-proc (graph in image) → Redis → SSE
Known seam (the one B-grade edge): the worker activity is a synchronous await fetch() that blocks for the entire graph and reads the decision body. The expensive, long-running, least-idempotent unit (the LLM graph) executes outside Temporal's durability — app crash mid-graph re-runs the whole graph (re-burns tokens), and a multi-minute sync HTTP call is exposed to ingress/LB idle timeouts. Deliberate and documented (graphs return recomputable decision artifacts; material writes happen in post-graph Activities; resume/checkpoint is a named P1 deferral). Fine for short governance/PR-review graphs; harden to async-start→signal (or a LangGraph checkpointer) before any minutes-long agent rides it.
Operating Rules
- Recall before designing. This space is dense and partly stale — read the canonical few (scorecard's doc map) before proposing anything; refine in place over adding a parallel doc (sprawl is the standing problem).
- One executor. All AI execution flows through
GraphExecutorPort.runGraph(). No bypass paths. Billing/observability/credit are decorators applied once in app bootstrap — never re-implement them in the worker. NO_LANGCHAIN_IN_SRC.@langchain/*only inpackages/langgraph-graphs/**. Appsrc/**must not import graph packages (dependency-cruiser enforced for the Server boundary).- Writes behind Temporal. Graphs return recomputable decision artifacts; material/external writes live in post-graph Activities with business-key idempotency.
- https://node-template.cognidao.org/knowledge/graph-execution-invariants is the invariant SSOT. Other specs link to it; they must not restate
GraphExecutorPort/AiEvent/PACKAGES_NO_SRC_IMPORTSdefinitions. - Don't overstate the eval gate. Nothing currently scores or blocks on graph quality. Treat "eval gate" as roadmap, not a control.
- CICD docs are HELD until the pipeline is green. No consolidation edits to https://cognidao.org/knowledge/operator-pipeline-contract /
cd-pipeline-*.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| writing-skillsobra/superpowersUse when creating new skills, editing existing skills, or verifying skills work before deployment | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| xlsxanthropics/skillsUse this skill any time a spreadsheet file is the primary input or output. This means any task where the user wants to: open, read, edit, or fix an existing .xlsx, .xlsm, .xltx, .csv, or .tsv file (e.g., adding columns, computing formulas, formatting, charting, cleaning messy data); create a new spreadsheet from scratch or from other data sources; or convert between tabular file formats. Trigger especially when the user references a spreadsheet file by name or path — even casually (like "the xlsx in my downloads") — and wants something done to it or produced from it. Also trigger for cleaning or restructuring messy tabular data files (malformed rows, misplaced headers, junk data) into proper spreadsheets. The deliverable must be a spreadsheet file. Do NOT trigger when the primary deliverable is a Word document, HTML report, standalone Python script, database pipeline, or Google Sheets API integration, even if tabular data is involved. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| shipping-and-launchaddyosmani/agent-skillsPrepares production launches. Use when preparing to deploy to production, or when asking what needs to be in place before shipping. Use when you need a pre-launch checklist, when setting up monitoring, when planning a staged rollout, or when you need a rollback strategy. | Stars: 119k | Updated | Claude CodeCodex | Verified | Install |
| childhoodthedotmack/claude-memBabysit a shipped release after merge, publication, or deployment. Verify published packages, production behavior, installed plugins, and late CI or user reports until the observation window is clean; use babysit for PR readiness before release. | Stars: 118k | Updated | Claude CodeCodex | Verified | Install |