CommunityRAPP

CommunityRAPP Constitution

The governing document for this repository. Read this before contributing.

Article I — Purpose

CommunityRAPP is the Azure Functions backend for the RAPP (Rapid Agent Prototyping Platform) ecosystem. It is the engine that powers agent creation, execution, and orchestration.

This repo does ONE thing well: it takes a transcript, discovery call, or user request and turns it into a production-ready AI agent deployed on Azure — with memory, multi-user support, and Microsoft 365 integration.

This is a community tool. Every file tracked in this repo must serve any user deploying their own instance — not just one project or customer.

Article II — Scope

What Belongs Here

Category Examples
Core Runtime function_app.py, host.json, requirements.txt
Agents Business agents that inherit from BasicAgent and do real work
Utilities Storage, environment, results, Copilot Studio (API, templates, triggers)
Documentation Architecture, API reference, deployment, Copilot Studio guides
Tests Unit tests, integration tests, plumbing tests, live API tests
Demos Scripted demo JSON files for the ScriptedDemoAgent
Deployment ARM templates, .funcignore, CI/CD workflows, deployment configs
RAPP Pipeline The 14-step methodology: discovery → MVP → code → quality gates → deploy
Power Platform Harness MSFTAIBASMultiAgentCopilot_*.zip — the Copilot Studio solution that connects RAPP to Teams/M365 Copilot

What Does NOT Belong Here

Category Why Where Instead
Customer-specific agents or demos Ties the repo to one engagement Your local workspace or private fork
Transpiled output (transpiled/) Generated artifacts — rebuild from source agents Gitignored; lives locally
Project-specific solution ZIPs Binary artifacts tied to one deployment GitHub Releases or private storage
RAPP project workspaces (.rapp/, rapp_projects/) Personal experiment data, archives Gitignored; lives locally
Customer-specific HTML (index-*.html) One-off UIs for specific customers Your local workspace
Credentials or PII Security risk local.settings.json (gitignored)

Article III — Directory Structure

CommunityRAPP/
├── agents/              # Production agents (BasicAgent subclasses)
├── demos/               # Demo script JSON files
│   └── tools/           # Demo capture scripts, HTML tools, bookmarklets
├── docs/                # Documentation, architecture diagrams, PPT templates
├── tests/               # Test suite
├── utils/               # Core utilities
│   ├── copilot_studio/  # Templates, triggers, deploy config
│   └── triggers/        # Trigger engine (router, registry, models)
├── .claude/             # Claude Code configuration
├── .github/             # GitHub workflows, Copilot instructions
├── function_app.py      # Main Azure Function entry point
├── host.json            # Azure Functions host configuration
├── requirements.txt     # Python dependencies
├── azuredeploy.json     # ARM deployment template
├── index.html           # Web chat interface
├── MSFTAIBASMultiAgentCopilot_*.zip  # Copilot Studio harness (community asset)
├── CHANGELOG.md         # Version history
├── CLAUDE.md            # Claude Code guidance
├── CONSTITUTION.md      # This file
├── README.md            # Project readme
└── QUICK_START.md       # Quick start guide

Gitignored (local-only, never tracked):

Article IV — Agent Standards

Every agent MUST:

  1. Inherit from BasicAgent (agents/basic_agent.py)
  2. Define name — a clear, descriptive string
  3. Define metadata — valid JSON schema for OpenAI function calling
  4. Implement perform(**kwargs) — the agent’s core logic
  5. Return a string — the result passed back to the conversation
  6. Be a single file — one agent per .py file in agents/
  7. Be generic — no hardcoded customer names, endpoints, or credentials

Every agent SHOULD:

Agents MUST NOT:

Article V — Community-First Principle

Every file in this repo must pass the “thousand strangers” test:

If a thousand developers cloned this repo tomorrow, would this file help them — or confuse them?

Rules:

  1. No hardcoded resource names — use YOUR_* placeholders in docs, environment variables in code
  2. No customer-specific content — agents, demos, and UIs must be generic or serve as reusable examples
  3. No binary artifacts except the Copilot Studio harness (MSFTAIBASMultiAgentCopilot_*.zip) which is a community asset needed for Power Platform integration
  4. Generated output is gitignored — transpiled/, rapp_projects/, .rapp/ live locally
  5. Templates over instances — provide local.settings.template.json, not local.settings.json

Article VI — Contributing

Before You Commit

Ask yourself:

  1. Does this change serve the RAPP pipeline or agent runtime? → ✅ Proceed
  2. Does this add RAPPverse, RAPPbook, or social features? → ❌ Wrong repo
  3. Does this add a new agent? → ✅ Follow Article IV standards
  4. Does this add a new top-level directory? → 🤔 Probably wrong — discuss first
  5. Does this include customer-specific content? → ❌ Strip it or gitignore it

Pull Request Standards

Branch Naming

feature/agent-name        # New agent
fix/issue-description     # Bug fix
docs/topic                # Documentation
refactor/component        # Code improvement

Article VII — Deployment Contract

The production deployment target is Azure Functions (Flex Consumption) with:

The main API contract:

// Request
POST /api/businessinsightbot_function
{
  "user_input": "string",
  "conversation_history": [],
  "user_guid": "optional-guid"
}

// Response
{
  "assistant_response": "formatted markdown |||VOICE||| concise voice text",
  "voice_response": "concise voice text",
  "agent_logs": "what agents did",
  "user_guid": "the-user-guid"
}

Do not change this contract without updating all consumers.

Article VIII — Memory & Storage

The default GUID (c0p110t0-aaaa-bbbb-cccc-123456789abc) is intentionally invalid — it’s a guardrail against accidental database insertion. See CLAUDE.md for details.

Article IX — What “Clean” Means

This repo follows the standards:

  1. Root is scannable — you can understand the project from ls
  2. No orphan files — every file has a clear purpose and home
  3. No ecosystem sprawl — RAPP ecosystem components live in their own repos
  4. No project baggage — customer data, experiments, and generated output stay local
  5. Agents are agents — they follow BasicAgent, they do one thing
  6. Docs match reality — if code changes, docs change
  7. Gitignore is the gatekeeper — anything project-specific is blocked at the gate, not cleaned up later

Article X — Community Contributions

This repo welcomes contributions from community forks. When integrating external contributions:

  1. Attribution required — use Co-authored-by: trailers in commits
  2. No customer data — strip customer directories, PII, and credentials
  3. No customer-specific transpiled agents — only generic templates and structure
  4. Demo captures with customer data — excluded (screenshots, recordings)
  5. Generic examples welcome — agent names as examples in code are fine
  6. Document what was included and excluded — in the commit message and CHANGELOG

Contributors

Contributor Fork Contributions
Bill Whalen CommunityRAPP-BillWhalen Agent transpiler, Copilot Studio integration, performance optimizations, trigger system, MCS templates, architecture diagrams

Article XI — Data Protection

Never commit:

Safe to include:

Article XII — Copilot Studio Transpilation Fidelity

When transpiling Python agents (.py) to Copilot Studio native solutions, all metadata MUST be sourced directly from the original .py agent files — never invented, abbreviated, or left empty. This ensures no fidelity is lost between the Python agent and its Copilot Studio counterpart.

Required Mappings (Python → Copilot Studio)

Python Agent Field Copilot Studio Target Notes
self.metadata["description"] bot.xml <description> tag AND botcomponent.xml <description> tag This is what the orchestrator sees when adding sub-agents. If empty, the orchestrator cannot pick the agent.
self.metadata["description"] GPT component displayName Short name shown in UI
System prompt / docstring / self.metadata GPT component instructions field in data file Full detailed instructions — must match the depth of the .py agent’s behavior
self.metadata["parameters"]["properties"] Topic trigger phrases + question nodes Each parameter becomes a data collection step
self.metadata["parameters"]["properties"]["action"]["enum"] Individual topics (one per action) Each action in perform() maps to a topic
Class docstring Agent description in solution manifest High-level purpose

Rules

  1. Never leave description empty. The orchestrator requires a description to route to sub-agents. Pull it verbatim from self.metadata["description"] in the .py file.
  2. Never abbreviate instructions. The GPT instructions in the data file must be as detailed as the Python agent’s actual behavior — including all parameters, response formats, error handling, and edge cases.
  3. Never invent capabilities. If the .py agent doesn’t do something, the Copilot Studio version must not claim to either.
  4. isAgentConnectable must be true for any agent intended to be used as a sub-agent by an orchestrator.
  5. Test the import. Every solution ZIP must be verified by actually importing into a Copilot Studio environment — not just by checking file structure.

Article XIII — The Hatchery Pattern

This article codifies the relationship between the RAPP Brainstem (T1) and CommunityRAPP (T2/T3), and the bridge between them.

Guiding Principles

Start small, layer up when ready.

Users begin with the brainstem alone. They are never pushed to T2/T3. The hatchery agent is loaded only when the user explicitly asks for the next step.

The one-liner IS the onboarding.

Every tier of the RAPP platform is installed with a single command. Everything after it — starting, authenticating, deploying to Azure — either happens automatically or is guided by the running system. Manual steps exist only as advanced documentation, never as the primary path.

When training users, the instruction is: “run the one-liner.” That’s it. Any change to install scripts must be tested against this path. If the one-liner breaks, nothing else matters.

Rules

  1. The brainstem stays clean. The rapp-installer repo (Brainstem, T1) is the local, on-device AI. CommunityRAPP code and dependencies must never be injected into the brainstem at install time. The only acceptable change to the brainstem is guidance updates to soul.md.

  2. CommunityRAPP is for the customer’s cloud instance. It provides Azure Functions runtime, persistent memory, and enterprise channel integration (T2/T3). It does not run inside the brainstem process.

  3. The hatchery agent is the on-demand bridge. A single-file agent (rapp_hatchery_agent.py) is hosted in this repo and fetched into the brainstem’s agents/ folder when the user is ready. It creates isolated CommunityRAPP project instances — never before the user asks.

  4. Projects are isolated. Each hatched project lives in ~/rapp-projects/{name}/, with its own virtual environment, its own port, and its own configuration. Hatched projects never share state with the brainstem or with each other.

  5. The hatchery agent must be self-contained. It may only use Python stdlib, subprocess, and requests. No Azure SDK, no openai, no imports from utils/. It must run inside the brainstem’s Python environment without additional dependencies.

  6. Progressive disclosure. The hatchery agent shows only the next step, never the full roadmap. Local testing before cloud deployment. Cloud deployment before Copilot Studio. Each layer is offered only when the previous layer is working.

The Hatch Flow

Brainstem (T1)                    CommunityRAPP (T2/T3)
localhost:7071                    ~/rapp-projects/{customer}/
                                  localhost:7072+
   User: "I'm ready to deploy"
         |
         v
   soul.md guidance → one-liner fetch script
         |
         v
   rapp_hatchery_agent.py loaded into agents/
         |
         v
   hatch → clone, venv, configure
         |
         v
   Isolated project ready         Azure Functions deploy
                                  Copilot Studio integration

The brainstem continues running as the user’s local AI. The hatched project runs independently as the customer’s cloud instance. They complement each other — they do not conflict.

Article XIV — Amendments

This constitution can be amended by:

  1. Opening a PR that modifies CONSTITUTION.md
  2. Explaining why the change is needed in the PR description
  3. Getting approval from a repo maintainer

The spirit of this document is focus. If an amendment would broaden scope beyond “Azure Functions backend for RAPP agent pipeline,” it should be a new repo instead.

Ratified on initial repo cleanup. Revised for community-first principles and the Hatchery Pattern.

This site is open source. Improve this page.