Files
cp1-agents/.agents/CONTEXT.md
Jonathan Boniface c14a94f33b
Some checks failed
check agents / check (push) Failing after 12s
Add hyperscaler discovery MCP servers and Well-Architected guidance
azure-discovery, aws-discovery and gcp-discovery collect read-only metadata
on servers, workloads, Kubernetes clusters, networks, data stores, policies
and provider recommendations. Credentials arrive per call from the vault.
Replies are paged, scrubbed of secrets and anonymised, and throttled calls
back off. cloud-knowledge searches each provider's Well-Architected guidance
from fixed lists only, so no customer detail can leave the platform.

Adds shared skills, the render and test tooling, a public Python Dockerfile
until the hardened base image is reachable, the customer access guide, the
implementation plan and the Vault Service platform issue.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-30 20:11:57 +00:00

5.4 KiB
Raw Blame History

Context: cp1-agents

Repository-wide facts for coding agents. Pattern- and agent-specific context lives in individual-agents/<Feature>/.agents/ and in <agent>/.agents/.

Layout

  • <pattern>/<Feature>/<agent>/. The patterns are sub-agents and individual-agents. A Feature folder is named ALZ-F0N: <Feature> 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 <Feature folder> (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/.

MCP servers

mcp-servers/ holds rendered servers: never edit server.py by hand. See mcp-servers/README.md. azure-discovery, aws-discovery and gcp-discovery take a customer credential per project; cloud-knowledge takes Kyndryl's, tenant-wide. They're deployed to mcp-servers on public Python images (not hardened; no customer data yet), are registered in the CP1 Agentic Landing Zone tenant (6ae37d13999438461a529409), aren't tested on a real cloud, and no agent declares them.

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: <agent>/docs/adr/. Individual agents: individual-agents/<Feature>/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/<component>:<version>.
  • 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/<profile>.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 <agent>-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://<agent>.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/<engagement>/<run>/
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