# Context: cp1-agents Repository-wide facts for coding agents. Pattern- and agent-specific context lives in `individual-agents//.agents/` and in `/.agents/`. ## Layout - **`///`.** The patterns are `sub-agents` and `individual-agents`. A Feature folder is named `ALZ-F0N: Workflow Agent`. ALZ-F01 is built; the F02 and F03 folders are empty. - **A Feature folder works like a small repository:** its agents, `workflows/`, its own `scripts/build_workflow.py` and, for individual agents, its pattern ADRs and `.agents/`. Relative links inside a Feature (`../scripts/`, `../workflows/`, `../../../docs/adr/` from an agent's `docs/adr/`) resolve inside that Feature. - **Shared, at the root:** - `scripts/`: - `check_agents.py` (cp4's rules, plus `app/` only when declared); - `render_k8s.py` (finds an agent by name under either pattern); - `kab_import_workflow.py ` (loads that Feature's `scripts/build_workflow.py`); - `kab_front_steps.py` (Feature builders import it from `parents[3]/scripts`); - `render_mcp_server.py`, `smoke_mcp_server.py`. - `mcp-servers/`, `deploy/`, and `docs/`. ## Sources of truth | What | Where | |---|---| | Requirements | ADO project "Global Modernization Engineering Hub - Agent Board": Epic 3214440, Features 3214441–3214447, F01 stories 3214451–3214458. The v1.1 story files are in the engineering hub workspace (`drafts/cp1/agentic-landing-zone/`), not in this repository | | Agent shape | `docs/source-material/agent-shapes/agent-pattern` and `subagent-pattern` (KAB's; their `.env` files are local and git-ignored, and the zips, which contain `.env` files, are left out) | | KAB workflow exports used as references | `docs/source-material/workflow-files/` | | Workflow documentation | `docs/source-material/workflow-documentation/` | | Reference repository | `cp4-agents` (gitea.kyndemo.live/agents/cp4-agents): layout, check script, workflow export format | | Changes to requirements | Sub-agents: `/docs/adr/`. Individual agents: `individual-agents//docs/adr/` | | Platform problems found | `docs/platform-issues/` | ## Platform facts - **Runtime image:** `cruciblecoredevacr.azurecr.io/kab/agent-runtime-adk:0.35.7`. Images are pushed to `cruciblecoredevacr.azurecr.io/kab/cp1/:`. - **Cluster:** context `crucible-kab-dev-aks`, in the Windows kubeconfig `/mnt/c/Users/JonathanBoniface/.kube/config`. - Agents run in namespace `agents`, MCP servers in `mcp-servers`, and the gateways in `core-components`. - Model gateway: `http://kyn-agent-builder-litellm.core-components.svc.cluster.local:4000`. Its key is Secret `agent-builder-secrets`, key `litellm-master-key`, in `agents`. - MCP gateway: `http://kyn-agent-builder-mcp-gateway.core-components.svc.cluster.local:8000`. - Shared storage: PVC `execution-storage-pvc` (RWX) in `agents`, mounted at `/data/executions`. The platform doesn't set `EXECUTION_STORAGE_ROOT`, so an agent that writes there sets it in its own ConfigMap. - There's **no** `agent-platform-connections` ConfigMap, so the gateway URLs go in each agent's ConfigMap through `deploy/.yaml`. - **The `repo` label is in every Deployment's selector** (`includeSelectors: true`). The individual agents keep `repo: cp1-agents-individual` (set per agent in `deploy/`), and the orchestrator and the MCP server use `cp1-agents`. - **An agent needs its own `MCP_AGENT_API_KEY`** (Secret `-secrets`), issued when it's created in KAB. Without it, every request fails at startup. - **MCP server registration fails as of 2026-10-29.** In the gateway's single tenancy mode, a server insert passes row-level security only when the caller's tenant is `default`, and KAB's default tenant isn't mapped to it. See `docs/platform-issues/mcp-gateway-default-tenant/`. - **Workflow export** (`export_version` 2.0.0): - Each agent step is a `generic_agent_call` to `http://.agents.svc.cluster.local:8080`. - Inputs come `from_workflow`, `from_steps` or `static` (front steps only). - `parallelGroup` and `executionLevel` order the steps. - Approvals are `hitl` with `checkpoint_type: approval`. - **Models on the Azure resource behind the gateway:** `gpt-4o`, `gpt-5.6-sol`, `claude-sonnet-5-5`, `claude-haiku-5-5`, `text-embedding-3-small`. Whether the cluster's LiteLLM serves each name hasn't been confirmed. ## Glossary | Term | Meaning | |---|---| | Orchestrator | The sub-agent pattern's one agent per Feature. It makes every MCP call and holds the run workspace. | | Sub-agent | A story's agent, run by the orchestrator through `delegate` (`as_tool: false`). It has functions only, never MCP tools. | | Run workspace | Write-once records plus a hash-chained manifest, under `/data/executions/alz-discovery///` | | Phase | One request's share of a workflow: plan, collect, analyse or critique, for Discovery | | Logical MCP server | A name in `agent.yaml` `mcp:` (`alz-scope` …), mapped to a deployed server at the MCP gateway |