AGENTS.md

Monorepo Project Map

• ./apps/devops_incident_response/mix.exs: Async webhook proof app above the greenfield platform
• ./apps/inference_ops/mix.exs: Reference proof app for cloud and self-hosted inference execution
• ./apps/trading_ops/mix.exs: Reference operator app slice above the greenfield platform
• ./connectors/codex_cli/mix.exs: Example session connector package for the greenfield platform
• ./connectors/github/mix.exs: Thin direct GitHub connector package backed by github_ex
• ./connectors/linear/mix.exs: Thin direct Linear connector package backed by linear_sdk
• ./connectors/market_data/mix.exs: Example stream connector package using the authored Runtime Control asm driver
• ./connectors/notion/mix.exs: Thin direct Notion connector package backed by notion_sdk
• ./core/asm_runtime_bridge/mix.exs: Integration-owned asm adapter into the shared runtime-control seam
• ./core/auth/mix.exs: Credential storage and resolution for the greenfield platform
• ./core/brain_ingress/mix.exs: Durable brain-to-lower-gateway submission intake and scope resolution
• ./core/conformance/mix.exs: Reusable v2-native connector conformance engine and report surface
• ./core/consumer_surfaces/mix.exs: Runtime support for generated Jido-native consumer surfaces
• ./core/contracts/mix.exs: Greenfield public contracts for runs, attempts, capabilities, and credentials
• ./core/control_plane/mix.exs: Capability registry and run ledger for the greenfield platform
• ./core/direct_runtime/mix.exs: Direct execution runtime for stateless and request/response capabilities
• ./core/dispatch_runtime/mix.exs: Async trigger dispatch runtime with retry, replay, and recovery
• ./core/ingress/mix.exs: Webhook and polling trigger admission for the greenfield platform
• ./core/inference_runtime/mix.exs: Explicit governed model invocation runtime with fixture and control-plane invokers
• ./core/model_invocation_contracts/mix.exs: Stable governed model invocation request, receipt, and stream fragment DTOs
• ./core/platform/mix.exs: Public facade package for the Jido Integration platform
• ./core/platform_cluster_runtime/mix.exs: Cluster-runtime shim for platform-owned package/runtime wiring
• ./core/policy/mix.exs: Admission policy evaluation for capabilities
• ./core/runtime_control/mix.exs: Shared runtime-control facade, IR, and driver contract layer
• ./core/runtime_router/mix.exs: Integration-owned router for session and stream runtime lanes
• ./core/session_runtime/mix.exs: Integration-owned internal jido_session runtime-control runtime
• ./core/store_local/mix.exs: Restart-safe local durability adapters for auth and control-plane truth
• ./core/store_postgres/mix.exs: Postgres durability package owning Repo, migrations, and sandbox posture
• ./core/webhook_router/mix.exs: Hosted webhook route registration and dispatch bridging above ingress
• ./mix.exs: Tooling root for the Jido Integration non-umbrella monorepo

AGENTS.md

This file defines the working contract for /home/home/p/g/n/jido_integration.

Onboarding

Read ONBOARDING.md first for the repo's one-screen ownership, first command, and proof path.

Purpose

jido_integration is a tooling-root Elixir monorepo for the greenfield integration platform. The repo root owns workspace tooling only. Runtime code belongs in isolated child packages.

Repository Shape

The current package layout is:

jido_integration/
  lib/                  # monorepo Mix tasks and workspace helpers only
  test/                 # root tooling tests only
  docs/                 # repo-level docs only
  core/                 # platform/runtime packages
  connectors/           # connector packages, one package per connector
  apps/                 # thin app/reference packages above the public platform

Current core packages:

• core/asm_runtime_bridge
• core/auth
• core/brain_ingress
• core/conformance
• core/consumer_surfaces
• core/contracts
• core/control_plane
• core/direct_runtime
• core/dispatch_runtime
• core/ingress
• core/inference_runtime
• core/model_invocation_contracts
• core/platform
• core/platform_cluster_runtime
• core/policy
• core/runtime_control
• core/runtime_router
• core/session_runtime
• core/store_local
• core/store_postgres
• core/webhook_router

Current connector packages:

• connectors/github
• connectors/linear
• connectors/notion
• connectors/codex_cli
• connectors/market_data

Current app packages:

• apps/devops_incident_response
• apps/inference_ops

Archived proof packages kept off the default workspace/CI lane:

• apps/trading_ops

Documentation Homes

Keep documentation aligned to the permanent V2 layout:

• repo-level architecture and operational guides belong in docs/
• package-specific workflows belong in package-local README.md files and package-local docs folders when needed
• host-level proof runbooks belong in apps/*/README.md
• proof code belongs in child packages or top-level apps, not in root examples/ or reference_apps/

Operating Rules

• Keep the repo root tooling-only. Do not move runtime or connector logic into the root unless it is genuinely monorepo-wide glue.
• Dependency source selection is handled by build_support/dependency_sources.exs and build_support/dependency_sources.config.exs. Local overrides use .dependency_sources.local.exs, which must stay gitignored. Dependency source selection must not use environment variables.
• Runtime application code under lib/** must not call direct OS env APIs. Runtime env reads belong in config/runtime.exs or a Config.Provider, then compiled/runtime code should consume materialized config or explicit options.
• This repo is a Weld consumer. Keep Weld checks focused on helper drift, dependency-source manifest validity, AGENTS guidance, generated package contracts, and publish order.
• Keep package boundaries explicit. If a connector uses a library directly, declare that dependency in the connector package instead of relying on transitive deps.
• Prefer adding new capabilities by adding or extending child packages, not by broadening the root project.
• Treat contracts as the shared public model and keep downstream packages honest against it.
• Treat core/brain_ingress as the durable brain-to-lower-gateway intake seam. Scope resolution, submission acceptance, and typed rejection normalization belong there rather than in the workspace root or connector packages.
• Treat platform as the public facade package. The root workspace must not reclaim app identity :jido_integration_v2.
• Treat shared adapter packages as contract producers, not governance owners. When implementing an adapter for :inference, Jido owns the governed translation into InferenceRequest, durable run/attempt truth, route selection, credential leases, replay, and review metadata. The adapter must not grow provider SDK branches or bypass ControlPlane.Inference.invoke/2.
• Treat connector packages as isolated deliverables. Each connector should compile, test, lint, type-check, and document cleanly on its own.
• DependencyResolver.execution_plane/1 resolves local sibling development to ../execution_plane/core/execution_plane. Do not point :execution_plane at the sibling repo root; that root is the non-published Blitz workspace project.
• Use the root mix jido.integration.new scaffold for new connector packages so they start with explicit child-package deps, runtime-fit handlers, and package-local conformance coverage.
• Keep webhook and async proof surfaces where they belong:
  • connector-local when the behavior is part of the connector contract
  • app-local when the behavior depends on hosted routing, dispatch handlers, or package composition above the connector
• Do not recreate the old root examples/ or reference_apps/ layout.

Required Validation Workflow

The root monorepo commands are the canonical quality surface for this repo.

Fresh clone setup from the repo root:

test -x bin/mix
git check-ignore -v bin/mix && {
  echo "bin/mix is ignored; remove the broad external ignore before continuing"
  exit 1
}
mix deps.get
mix mr.deps.get

bin/mix is a repo-owned workspace wrapper, not a local-only artifact. Keep it portable and tracked; do not replace it with a machine-specific shim path.

At minimum, future agents should preserve this invariant:

The repo docs now match the tooling-root workspace slice. I’m finishing with the root mix ci pass so the package graph is validated under the same monorepo commands the repo is supposed to expose.

Run these from the repo root:

mix monorepo.format
mix monorepo.compile
mix monorepo.test
mix monorepo.credo --strict
mix monorepo.dialyzer
mix monorepo.docs
mix ci

mix ci is the main acceptance gate. If it fails, the repo is not done. It is Blitz impact-aware through Hex ~> 0.3.0: clean baselines write compact .blitz/ state, docs edits stay owner-local, and source or mix.exs edits cascade through reverse package deps.

For connector-facing slices, also run the root conformance task against every affected connector module, for example:

mix jido.conformance Jido.Integration.V2.Connectors.GitHub
mix jido.conformance Jido.Integration.V2.Connectors.Linear

The root mix.exs also exposes equivalent mr.* shortcuts for day-to-day use:

mix mr.deps.get
mix mr.format
mix mr.compile
mix mr.test
mix mr.credo --strict
mix mr.dialyzer
mix mr.docs

Package-local live proofs remain opt-in. They should never be required for the default root acceptance gate.

Live Provider Checks

For live provider checks, use ~/scripts/with_bash_secrets <command>. It sources ~/.bash/bash_secrets and execs the command. Do not print secret values. Pipe LINEAR_API_KEY via stdin for Linear examples. GitHub live examples use gh auth or GH_TOKEN/GITHUB_TOKEN from the wrapper. Codex SDK examples use the existing Codex/OpenAI machine auth through the wrapper. Live provider smoke is not product acceptance unless it runs the product-owned Extravaganza command path.

Shared Adapter Boundary Checklist

Use this checklist when a shared library such as :inference enters Jido through a Jido-owned adapter:

• Preserve Inference.Client.defaults, Inference.Request.options, request metadata, trace context, and session fields unless the Jido boundary has an explicit reason to reject them.
• Prove request-level options override client defaults where both are accepted.
• Map portable tool controls into Jido tool_policy; do not leave them as unstructured provider options.
• Preserve provider-reported usage, cost, finish reason, route, run id, and attempt id on the returned shared response.
• Keep internal compatibility options internal. Do not leak raw prompts, provider payloads, secrets, or workflow histories into public DTOs, docs, or receipts.
• Run the shared producer package gate when the adapter depends on new shared semantics, then run this repo's root mix ci.

Working Style

• Make changes package-first, then validate from the root.
• When adding a new package, wire it into the root monorepo task surface so it is covered by the same commands as the rest of the repo.
• When changing connector review semantics, keep core/conformance, the root mix jido.conformance task, and connector companion evidence modules aligned.
• When adding a new connector package, prefer generating it from mix jido.integration.new <connector_name> and then editing the emitted package in place instead of hand-rolling a new child project.
• Keep README/package docs aligned with the current slice. Do not leave architecture or package docs behind the code.
• Keep repo guide text aligned with the actual package graph and proof surfaces.
• When documenting workflows, point to package-local or app-level proofs rather than inventing new root-level examples.
• Prefer TDD/RGR for new vertical slices: add or extend tests first, implement, then run the full root gate.
• Do not silently weaken quality gates to get green CI. Fix package boundaries or dependency shape instead.

Common Pitfalls

• Do not rely on transitive dependencies between child packages.
• Do not let a connector or app depend on the repo root; keep dependencies minimal and explicit.
• Do not let a connector package depend on unrelated runtime packages “because it works”; keep dependencies minimal and explicit.
• Do not assume root Dialyzer coverage is enough. The monorepo tasks intentionally run quality checks inside each child package as well.
• Do not treat generated docs as proof of correctness unless mix monorepo.docs or mix docs.all passes cleanly.
• Do not let V1-only layout language drift back into repo docs or package docs.

Expected Next Steps

The current skeleton proves four runtime families:

• direct
• session
• stream
• inference

Natural future slices include:

• additional durable stores
• richer auth lifecycle
• composed policy/gateway rules
• live CLI-published inference endpoints
• additional self-hosted inference backends
• more connectors
• more operator/reference apps above the public platform

Temporal developer environment

Temporal CLI is implicitly available on this workstation as temporal for local durable-workflow development. Do not make repo code silently depend on that implicit machine state; prefer explicit scripts, documented versions, and README-tracked ergonomics work.

Native Temporal development substrate

When Temporal runtime behavior is required, use the stack substrate in /home/home/p/g/n/mezzanine:

just dev-up
just dev-status
just dev-logs
just temporal-ui

Do not invent raw temporal server start-dev commands for normal work. Do not reset local Temporal state unless the user explicitly approves just temporal-reset-confirm.

jido_integration Agent Instructions Draft

Owns

• Connector capability catalog.
• Auth lifecycle.
• Credential leases.
• Lower gateway invocation.
• Durable connector execution state.
• Reviewable connector packets.

Does Not Own

• Product UX.
• Semantic reasoning.
• Citadel authority decisions.
• Execution Plane placement internals.
• GroundPlane universal primitives.

Allowed Dependencies

• Execution Plane packets and lane-facing contracts.
• Citadel authority/governance packet contracts.
• GroundPlane refs.
• Provider SDKs inside connector packages.

Forbidden Imports

• Product modules.
• Direct semantic prompt logic.
• Static long-lived provider tokens in runtime config.

Verification

• mix ci
• Connector lifecycle, lease, invocation, and lower-facts tests.

Escalation

If a connector needs a new lower execution shape, add the packet/lane contract in Execution Plane first.