cogni-dao/cogni / .claude/skills/agent-infrastructure-scorecard
agent-infrastructure-scorecard
VerifiedLiving status scorecard for Cogni agent infrastructure — InProc↔LangGraph-Server alignment, built-vs-designed inventory, and the agent/langgraph doc DRY/drift/consolidation state. The stable mental model lives in agent-infrastructure-expert; this is the dated state that moves as graphs, executors, and evals ship. Use to check "what's actually built vs paper", "where do InProc and Server diverge", "which agent specs are stale/duplicated/safe-to-delete". Update THIS, not the expert skill.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 10.0 KB |
SKILL.md
View on GitHub---
name: agent-infrastructure-scorecard
description: Living status scorecard for Cogni agent infrastructure — InProc↔LangGraph-Server alignment, built-vs-designed inventory, and the agent/langgraph doc DRY/drift/consolidation state. The stable mental model lives in agent-infrastructure-expert; this is the dated state that moves as graphs, executors, and evals ship. Use to check "what's actually built vs paper", "where do InProc and Server diverge", "which agent specs are stale/duplicated/safe-to-delete". Update THIS, not the expert skill.
---
# Agent Infrastructure Scorecard
> Living state under [`agent-infrastructure-expert`](../agent-infrastructure-expert/SKILL.md). The expert skill holds the stable mental model + operating rules; this scorecard holds dated status that moves as things ship. **When something changes, refine this file — the skill stays constant.**
**Last verified:** 2026-06-09
## InProc ↔ LangGraph Server Alignment
https://node-template.cognidao.org/knowledge/graph-execution-invariants north-star: _"InProc must model as closely to LangGraph Server's I/O as possible."_ Where they stand:
| Dimension | InProc (live, P0) | LangGraph Server (designed) | Aligned? |
| ---------------------- | --------------------------------------------- | -------------------------------------------------------------------------- | ---------------------------------- |
| `GraphExecutorPort` | ✅ | ✅ | 🟢 same port |
| `providerId` / graphId | `langgraph` / `langgraph:<name>` | `langgraph` / `langgraph:<name>` | 🟢 backend swaps via env, not id |
| Output vocabulary | ai-core `AiEvent` | ai-core `AiEvent` | 🟢 nothing vendor-specific crosses |
| Tool events | full (`tool_call_*`) | P0: text/usage/done/error only | 🟡 InProc richer |
| `stateKey` / threads | **ignored** — no persistence | required; UUIDv5 tenant-scoped checkpoints | 🔴 divergent |
| Resume / time-travel | none (graph loss = full re-run) | native checkpointer (Redis) | 🔴 divergent |
| Billing path | stream `usage_report` → `commitUsageFact()` | async reconciliation via LiteLLM `end_user`/spend-logs | 🔴 different mechanism |
| LLM routing | `CogniCompletionAdapter` (ALS `completionFn`) | LiteLLM proxy, per-user virtual key | 🟡 different |
| Deployment | **only live path** — bundled in app image | **not deployed** (no catalog target, no `LANGGRAPH_SERVER_URL` in any env) | 🔴 Server is paper |
**Takeaway:** InProc is production; Server is a spec + compose file with no running instance. They diverge most exactly where durability lives (threads/resume/billing) — the same seam as the synchronous-HTTP execution boundary. Never claim Server parity in a design without confirming it's actually deployed.
## Built vs Designed-Only
| Capability | Status |
| ---------------------------------------------------------- | --------------------------------------------------------------------------------------------------------- |
| InProc execution, billing, observability, credit preflight | 🟢 built |
| Temporal orchestration + HTTP-delegated graph runs | 🟢 built |
| Node-sovereign graph packages (`@cogni/<node>-graphs`) | 🟢 built |
| LangGraph Server executor | 🔴 spec + compose only, not deployed |
| **Evals — datasets, LLM-judge, CI gate, canary gate** | 🔴 **0/8; `evals/` dir does not exist; nothing gates promotion** (`proj.ai-evals-pipeline.md`, task.0286) |
| UI graph picker | 🟡 `AVAILABLE_GRAPHS` hardcoded in `ChatComposerExtras.tsx`, not from `/api/v1/ai/agents` |
## DRY, Drift & Consolidation — agent/langgraph cluster
Evidence-backed. **CICD docs are out of scope and on HOLD until the pipeline is green** — no edits to https://cognidao.org/knowledge/operator-pipeline-contract / `cd-pipeline-*`.
| # | Finding | Evidence | Fix |
| --- | ------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------- |
| 1 | Invariant duplication; https://node-template.cognidao.org/knowledge/graph-execution-invariants is SSOT yet others restate | `GraphExecutorPort`+`AiEvent` in all 4 of graph-execution / langgraph-patterns / langgraph-server / unified-graph-launch; `PACKAGES_NO_SRC_IMPORTS` ×3; `NO_LANGCHAIN_IN_SRC` ×2 | each restated invariant → one-line link to graph-execution |
| 2 | Speculative executor specs for unbuilt paths | `claude-sdk-adapter` (_not implemented_), `n8n-adapter` (_P2_), `multi-provider-llm` (_future_), `completions-api` (_proposed_) — all `draft` | collapse to one "Future Executors" stub under graph-execution |
| 3 | Path drift | `apps/operator` (real `nodes/<node>/app`) in unified-graph-launch, ai-pipeline-e2e, multi-provider-llm; `../LANGGRAPH_SERVER.md` (real `https://node-template.cognidao.org/knowledge/langgraph-server-adapter`) in langgraph-patterns | mechanical rewrite |
| 4 | `agent-development.md` operator-centric + missing ship/run | leads shared Tier 1a; no runtime/CI link | lead node-local `packages/graphs`; add Build→Ship→Run paragraph |
| 5 | Paradigm doc masquerading as guide | `agent-design.md` = KPIs/paradigm, not a runbook | → operator knowledge Dolt. Rule: guide = runbook; paradigm = knowledge entry |
**Target shape:** ~6 core specs (graph-execution = single invariant SSOT, + langgraph-patterns, langgraph-server, temporal-patterns, unified-graph-launch, ai-pipeline-e2e) and 3 guides (agent-development, tools-authoring, langgraph-server). Everything else links up or merges; nothing restates invariants.
## Canonical Doc Map (read order + stale flags)
1. [`graph-execution.md`](https://node-template.cognidao.org/knowledge/graph-execution-invariants) — **authoritative spec.** Executor port, decorator stack, routing, catalog, ALS.
2. [`langgraph-patterns.md`](https://node-template.cognidao.org/knowledge/graph-execution-invariants) — package boundaries, InProc flow, anti-patterns. 🟡 fix `../LANGGRAPH_SERVER.md` link.
3. [`unified-graph-launch.md`](https://node-template.cognidao.org/knowledge/graph-run-launch-contract) — run topology (Temporal → app → Redis → SSE). 🟡 `apps/operator` drift.
4. [`temporal-patterns.md`](https://cognidao.org/knowledge/temporal-workflow-rules) — durability boundary, webhook→workflow→graph→write.
5. [`langgraph-server.md`](https://node-template.cognidao.org/knowledge/langgraph-server-adapter) — alternate executor (designed, not live).
6. [`ai-pipeline-e2e.md`](https://node-template.cognidao.org/knowledge/charge-receipt-pipeline) — auth→execution→billing→security E2E. 🟡 `apps/operator` drift.
**Narrower/adjacent:** `agent-discovery`, `agent-registry`, `ai-setup`, `sandboxed-agents`, `node-baas-architecture`.
**Speculative (see DRY #2):** `claude-sdk-adapter`, `n8n-adapter`, `multi-provider-llm`, `completions-api`.
**Authoring tier:** [`agent-development.md`](https://node-template.cognidao.org/knowledge/agent-development) 🟡, [`agent-design.md`](https://node-template.cognidao.org/knowledge/design-an-agent) → knowledge, [`tools-authoring.md`](https://node-template.cognidao.org/knowledge/add-an-ai-tool).
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 |