Skip to main content

AI-Assisted Development Setup

How we bootstrap AI context across all tools from a single source of truth.

The problem​

Every AI coding assistant — Claude Code, GitHub Copilot, Cursor, Gemini CLI, Windsurf — needs context about the platform to be useful. Without it, developers spend the first part of every session explaining the same things: what repos exist, what each one does, where to look for what.

Worse, each tool has its own file convention: CLAUDE.md, .github/copilot-instructions.md, .cursor/rules/, GEMINI.md. Maintaining separate files for each tool means drift, duplication, and context that goes stale.

The decision​

Use a single AGENTS.md as the source of truth. All tool-specific filenames are symlinks to it. One update propagates everywhere.

The file lives in .agents/ at the workspace root and is distributed by cpa setup — the platform agent CLI that developers run to bootstrap their workspace.

What this looks like​

~/cogrion-workspace/                        ← dedicated workspace folder (created by developer)
  .agents/
    AGENTS.md                               ← platform context (bundled with cpa, seeded on setup)
    CLAUDE.md                               ← @ import of AGENTS.md + persona tag + skill import
    skills/
      cpa-developer.md                      ← setup + end-of-cycle workflow for agent developers
      devops.md                             ← setup + patterns for platform/ops engineers
      fullstack.md                          ← setup + patterns for app developers
  AGENTS.md                                 ← symlink → .agents/AGENTS.md
  CLAUDE.md                                 ← symlink → .agents/AGENTS.md
  GEMINI.md                                 ← symlink → .agents/AGENTS.md
  .github/
    copilot-instructions.md                 ← symlink → ../.agents/AGENTS.md
  platform-docs/                            ← cloned by cpa setup
  cogrion-<suffix>.code-workspace           ← generated by cpa setup

The source of truth is cogrion-platform-agent, not platform-docs. AGENTS.md and skill files are bundled with the cpa package and seeded into .agents/ on cpa setup. Upgrading cpa and re-running setup refreshes the context.

Persona-based setup​

Developers have different needs. A blanket getting-started flow produces noise for most of them. Instead, cpa setup captures the developer's role at workspace creation:

  1. CPA Developer — working on cogrion-platform-agent itself. Needs a dev install of cpa, AWS credentials, and an end-of-cycle commit workflow.
  2. Platform / DevOps — operating or observing live infrastructure. Needs cpa installed globally and AWS credentials.
  3. Fullstack / App Dev — building features on the platform. Needs cpa installed globally; no AWS required.

cpa setup writes two lines to .agents/CLAUDE.md after the @ import:

# developerPersona
This developer's persona is: CPA Developer
@skills/cpa-developer.md

When a developer types getting started, Claude reads the persona tag and the pre-loaded skill — and jumps straight to the relevant steps without asking.

The cpa tool and live infrastructure​

AGENTS.md alone cannot answer questions about live infrastructure. The platform agent (cogrion-platform-agent) exposes real-time tools — cluster state, services, tenant deployments — to Claude Code via MCP.

cpa install registers the MCP server with Claude Code. cpa status validates the full chain is working.

Why .agents/ as a folder​

  • IDE workspace files list .agents first so CLAUDE.md auto-loads as the primary context
  • Clear home for context files that aren't part of any repo
  • Keeps the workspace root clean — symlinks are the only visible files there
  • No editor-specific folder structures (no .cursor/rules/, no hardcoded paths per tool)

Why cpa as the distribution mechanism​

cpa is a pipx-installable CLI that bundles AGENTS.md and skill files as package data. This replaces the previous init.sh script served from platform-docs.

The key advantages over init.sh:

  • Versioned releases — context updates ship with the package, not as a live curl
  • cpa upgrade to update, cpa setup to re-seed — explicit, auditable, no curl-pipe
  • Day-two commands: cpa status for health checks, cpa upgrade to stay current
  • Persona is stored in ~/.config/cogrion/cogrion.env and persists across workspace re-seeds

Standards basis​

AGENTS.md was pioneered by OpenAI for Codex and donated to the Agentic AI Foundation (AAIF) under the Linux Foundation in December 2025. It is now the cross-tool standard, supported by Claude Code, Cursor, Copilot, Gemini CLI, Windsurf, Aider, Zed, Warp, and others.