CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

What This Is

AIBAST Agents Library is the stable Microsoft downstream for the RAPP (Rapid Agent Prototype Pattern) stack. It combines the local Brainstem server, an industry agent-template catalog, the RAPP production guide, Azure deployment assets, and a Power Platform solution.

Philosophy: "engine, not experience" — this is infrastructure, not a consumer product. See CONSTITUTION.md for scope rules and governance.

Product Golden Path

The durable beta product direction is documented in beta/GOLDEN_PATH.md:

• RAPP accelerates learning AI and teaching AI immediately after learning it.
• The resulting skill is a portable single-file agent/RAPP capability that can follow the user for life.
• Chat is the control surface.
• GitHub Copilot Brain Surgeon teaches by doing and visibly drives the beta.
• An external AI can take over the visible Brainstem or Surgeon chat to keep a user unstuck, then hand control back.
• The beta combines global and routed agents in isolated hardlinked AGENTS_PATH workers around an unchanged Grail kernel.
• Screenshots, recordings, source Explorer, tool logs, and real /chat tests make the learning observable.
• Proven RAPP/1 artifacts promote into Hippocampus and the appropriate Microsoft downstream platform without rewriting the skill or wire.

Treat this as a product-lifetime invariant. Do not replace the visible teach-by-doing loop with hidden automation, require VS Code for the golden path, or add beta routing fields/endpoints to brainstem.py.

Repository Layout

• rapp_brainstem/ — The core brainstem server (see rapp_brainstem/CLAUDE.md for deep internals)
• agents/@aibast-agents-library/ — AIBAST-owned industry templates and stacks; never replace this tree from Grail
• registry.json, build_registry.py — generated catalog and its AIBAST-owned builder
• install.sh, install.ps1, install.cmd — One-liner installers (Brainstem path). These are sacred — any change must be tested end-to-end on a fresh machine.
• community_rapp/ — Hippocampus (Tier 2) installer scripts. Parallel path, no dependency on brainstem.
• rapp_ai/ — AIBAST-owned Azure Functions implementation and documentation
• azuredeploy.json, deploy.sh, deploy.ps1 — Azure ARM deployment (Tier 2 cloud)
• MSFTAIBASMultiAgentCopilot_*.zip — Power Platform solution for Copilot Studio (Tier 3)
• index.html — the landing page is the browsable agent catalog (search, vertical filter, per-agent and per-stack install commands); reads registry.json. library.html is a redirect that preserves deep links
• docs/installer.html — the Brainstem installer page (one-liner, manual steps, the three tiers); why.html explains the positioning
• metrics.html, scripts/build_metrics.py, state/metrics*.json — public metrics dashboard and its daily snapshot
• docs/rapp-guide.html — Restored 14-step RAPP production methodology
• docs/ — Quick start, tutorial, production guide, and installer mirrors
• skill.md — Moltbook-pattern onboarding skill (YAML frontmatter, autonomous steps, pause points)

Commands

# Start brainstem server (creates venv, installs deps, launches on port 7071)
cd rapp_brainstem && ./start.sh

# Direct run (assumes deps installed)
cd rapp_brainstem && python brainstem.py

# Run all Brainstem tests
cd rapp_brainstem && python -m pytest tests -v

# Run a single test
cd rapp_brainstem && python -m pytest tests/test_local_agents.py::TestLocalStorage::test_write_and_read -v

# Validate and regenerate the AIBAST registry
python build_registry.py
python -m pytest tests -v

# Refresh the public metrics snapshot (state/metrics.json)
python scripts/build_metrics.py            # live; GITHUB_TOKEN with admin:read unlocks traffic
python scripts/build_metrics.py --offline  # no network, catalog composition only

# Health check (server must be running)
curl -s localhost:7071/health | python3 -m json.tool

# Test installer (bash)
bash tests/test_installer.sh

No linter, formatter, or type checker is configured.

Architecture: Three Tiers

Each tier is self-contained. Users advance when they choose to.

Brainstem Server (rapp_brainstem/)

Single-file server: All logic lives in brainstem.py (~3,300 lines) — auth, routing, streaming, diagnostics, LLM calls, and agent orchestration. Keep it that way.

Request flow (POST /chat and POST /chat/stream): Load soul.md -> discover agents from agents/*_agent.py -> call Copilot API with tools -> execute tool calls via agent .perform() -> loop up to 3 rounds -> return JSON or server-sent events.

Agent system: Files matching agents/*_agent.py are auto-discovered (flat directory only, experimental/ excluded). Each extends BasicAgent with metadata (OpenAI function schema) and perform(**kwargs). Agents reload from disk every request — no restart needed.

Auth chain (priority order): GITHUB_TOKEN env var -> .copilot_token file -> gh auth token CLI -> device code OAuth via /login. Copilot API tokens are short-lived with auto-refresh.

Import shims: _register_shims() injects sys.modules so agents written for CommunityRAPP (cloud) work locally — utils.azure_file_storage maps to local_storage.py.

Memory agents: ManageMemory and ContextMemory get special handling — user_guid arg is stripped, and /chat auto-injects <memory> context if ContextMemory is loaded.

Branching and Release Model

main is production. The install one-liners (curl ... install.sh | bash) pull from main. Users get whatever is on main.

Staging is the fork. A maintainer's fork provides the staging ring: its staging branch serves its own Pages site with installers rendered to install the staging kernel, and its main is a fast-forward mirror of production kept by .github/workflows/sync-upstream.yml. Feature work lands in staging by pull request and is gated by preflight, the Pages deploy, and the clean-runner one-liner smoke (ring-smoke.yml). Do not hardcode a personal fork into Microsoft-facing source or documentation.

Promotion path:

1. Merge to staging on the fork; let the gates run.
2. tools/promotion_check.sh must report GREEN.
3. One pull request from <fork-owner>:staging to microsoft:main, opened and merged by a human.
4. Add the release to docs/RELEASES.md and keep adding its post-release issues.

Kernel updates come from the Grail source recorded in rapp/GRAIL-SPECIES.json only, through a kernel-sync pull request that refreshes that contract and rapp/KERNEL-DRIFT.md in the same commit. Never edit rapp_brainstem/ or the installers for a fix that belongs to every Brainstem user; send it to the Grail first.

Do not push directly to either main. Full process: docs/RELEASE-PROCESS.md.

Grail Downstream Boundary

Shared Brainstem releases flow from the pinned Grail source, but this repository is not a mirror. Preserve these AIBAST-owned surfaces during every sync:

• agents/@aibast-agents-library/, registry.json, and build_registry.py
• index.html, library.html, docs/installer.html, why.html, metrics.html, scripts/build_metrics.py, and state/ (the catalog browse page, the metrics dashboard, and its snapshots)
• rapp_ai/
• README.md, index.html, CLAUDE.md, docs/index.html, docs/tutorial.html, and docs/rapp-guide.html
• .github/, LICENSE, SECURITY.md, CONTRIBUTING.md, .vscode/, and tools/

Only repository-identity references are rewritten mechanically: Grail product/support identity becomes microsoft/aibast-agents-library, and Brainstem support drafts target that Microsoft repository. The pinned upstream provenance stays truthful. Content repositories such as CommunityRAPP are separate dependencies and must be reviewed rather than globally replaced. Installer mirrors under docs/install.* must remain byte-identical to their root counterparts.

Key Conventions

• Python 3.11 target; venv at ~/.brainstem/venv
• No API keys for local dev — GitHub Copilot token exchange handles auth
• Config via .env in rapp_brainstem/ — GITHUB_TOKEN, GITHUB_MODEL (default auto), SOUL_PATH, AGENTS_PATH, PORT, BRAINSTEM_LAN_MODE, BRAINSTEM_ALLOWED_HOSTS, and VOICE_ZIP_PASSWORD
• Two install paths exist and must never cross-contaminate: brainstem (install.sh) and hippocampus (community_rapp/install.sh)
• The landing page (index.html) and docs/ are static HTML — no build step