All three hit the same wall: the AI has no idea what the platform is.

Every session starts with re-explaining. What repos exist. What each service does. Where authentication lives. What happens when a stack deploys. Whether you're in a browser tab or an AI-powered editor, you're burning the first five exchanges just getting the assistant up to speed — and then starting over tomorrow.

cpa is how we fix that for everyone, regardless of which tool they use.

The Problem With Cold AI Sessions​

AI assistants are stateless by default. Every new session, they know nothing about your platform. They don't know that control-plane handles provisioning, that cluster-agent-python runs inside tenant clusters, or that AWS credentials flow through SSO profiles named after accounts.

So you spend the first few exchanges teaching. Then you ask your actual question. Then the session ends, and tomorrow you do it again.

There's a second problem: every AI tool has its own convention for context files. CLAUDE.md for Claude Code. .github/copilot-instructions.md for Copilot. .cursor/rules/ for Cursor. GEMINI.md for Gemini. If you maintain them separately, they drift. They go stale. They start contradicting each other. Pick one to update and the others rot.

Introducing cpa — The Cogrion Platform Agent CLI​

We replaced our old bootstrap script with a proper CLI tool: cpa. Same outcome, zero curl-pipe anxiety, and a set of day-two commands that actually make the tool useful beyond the first setup.

Here's how to get from zero to a fully context-aware AI workspace in under two minutes.

Step 1 — Install​

pipx install "git+https://github.com/cogrion/cogrion-platform-agent.git#subdirectory=src/agent-server"
cpa install

cpa install writes a default config to ~/.config/cogrion/cogrion.env, auto-detects your git identity and GitHub username, and registers the MCP server with Claude Code — so the platform agent is available as a tool the moment you open your editor.

Step 2 — Create a Workspace​

Create a dedicated empty folder first. cpa setup clones repos and generates a VS Code-compatible workspace file at the working directory level — don't run it inside an existing project.

mkdir ~/cogrion-workspace && cd ~/cogrion-workspace
cpa setup

The setup wizard walks you through three things:

1. Prerequisites check — confirms Claude Code is installed and your AWS SSO session is active
2. Persona selection — are you a CPA Developer, Platform/DevOps, or Fullstack engineer? This determines which skill file gets loaded into your AI context
3. Workspace generation — picks up your editor (VS Code, Cursor, or Windsurf) and creates the matching workspace file

When it's done, you have:

• A .agents/ folder with AGENTS.md (platform context) and your persona's skill file
• Root symlinks so every AI tool reads the same source: CLAUDE.md, GEMINI.md, .github/copilot-instructions.md — all pointing to one file, no drift
• A workspace file with .agents/ listed first so Claude Code loads context automatically on open

Step 3 — Open and Ask​

code ./cogrion-<suffix>.code-workspace

Then type this in Claude Code:

getting started

That's your trigger phrase. Claude reads your persona, follows the matching skill file, validates your setup, and orients you to the platform based on your role. If anything is missing (AWS profile, GitHub token), it tells you exactly what to do.

What the AI Gets​

AGENTS.md is the cross-tool standard under the Linux Foundation's AAIF. Every AI tool in your workspace reads it. It gives the assistant:

• What Cogrion is and how the BYOC model works
• The full repo map with what each service does
• Where to look for answers — platform-docs for behavior, service repos for implementation
• Global code conventions, commit rules, and pre-commit checklist

Skill files go deeper per persona. A CPA Developer gets step-by-step validation for the agent server. Platform/DevOps gets cluster registry navigation and EKS tooling. Each skill is a compact, role-specific runbook.

Per-repo AGENTS.md files handle the rest. The proximity rule means the closest AGENTS.md to the file you're editing wins. When you're in cogrion-platform-agent/, that repo's rules take over — lazy gateway pattern, CPA_ constants prefix, structlog over print, the full context — without you doing anything.

Day Two: Status and Upgrades​

Setup is a one-time thing. Here's what you reach for day-to-day:

Check your environment is healthy:

cpa status

Runs readiness checks across config, AWS SSO, GitHub auth, and MCP registration. Shows exactly what's broken and how to fix it — no guessing.

Stay current:

cpa upgrade

Pulls the latest version via pipx. New rules in AGENTS.md, new skills, new integrations — everything updates in one command. Re-run cpa setup afterward to re-seed the context into your workspace.

The Shift This Creates​

The goal isn't to make AI faster at answering questions you already know how to answer. It's to make it genuinely useful for questions you'd otherwise have to context-switch to answer yourself — live cluster state, GitHub repo structure, which stack a tenant is running.

When the AI already knows the platform, those questions become cheap. You stop re-explaining. You start getting answers.

The full setup guide lives in Developer Setup.