Multi-Project Agent Coordination Framework

A portable, provider-agnostic coordination layer for LLM agents working across multiple software projects and Git forges.

Supports: GitHub, GitLab, Gitea, Forgejo, Codeberg, and any Git forge with a compatible API.

---

What Is This?

This is a predictive working framework that gives AI agents persistent memory, explicit project boundaries, and multi-provider Git automation. Instead of re-discovering your codebase every session, agents boot from a structured authority chain and reuse captured knowledge.

Key capabilities:

• Multi-project workspaces — One brain, many repositories
• Multi-provider Git — Works with GitHub, GitLab, Gitea, Forgejo, Codeberg interchangeably
• Persistent agent memory — Handovers, context capsules, and task archives survive across sessions
• Predictive boot — Agents read authority files first, scan code only when necessary
• Provider-agnostic automation — No hardcoded gh, glab, or tea; all resolved through registry
• Portable seed — Bootstrap the same coordination layer into any new project in minutes

---

Quick Start

1. Clone or navigate to your workspace root

This framework lives at the root of your workspace. It governs all projects underneath.

cd ~/projects/ai-talks/brain   # or wherever your workspace is

2. Initialize the coordination layer (first time only)

# Tell your agent:
"Initialize this project using the init-project skill"

The agent will:

1. Detect Git roots under the workspace
2. Auto-detect your Git provider from git remote -v
3. Ask you a few questions (project name, provider, topology)
4. Generate all configuration files
5. Protect secrets in .gitignore

3. Start working

Once initialized, just type your task. The agent will:

1. Boot from .robotz/agents/BOOT_AUTHORITY.yaml
2. Read .robotz/agents/RULES.md and .robotz/agents/GIT_WORKFLOW_POLICY.md
3. Check .robotz/agents/GIT_PROVIDER_CONFIG.yaml if Git automation is needed
4. Load relevant context capsules and handovers
5. Execute within the correct project boundary

---

Architecture

Directory Structure

workspace-root/
├── .robotz/
│   ├── Robotz.yaml                    # Workspace descriptor — projects, repos, topology, providers
│   └── agents/                        # Coordination layer
│       ├── BOOT_AUTHORITY.yaml        # First trust anchor — paths and memory locations
│       ├── BOOT.md                    # Boot procedure for agents
│       ├── RULES.md                   # Global agent rules — edit restrictions, lifecycle
│       ├── CODING_STANDARDS.md        # Engineering standards across all projects
│       ├── GIT_WORKFLOW_POLICY.md     # Authoritative Git safety policy
│       ├── GIT_PROVIDER_CONFIG.yaml   # Multi-provider registry — CLI, API, auth mapping
│       ├── CODE_REVIEW_TEMPLATE.md    # Template for code reviews
│       ├── config.yaml                # Agent execution profile
│       ├── agents_brain.md            # Operational snapshot of current state
│       │
│       ├── skills/                    # Reusable skill definitions
│       │   ├── init-project/
│       │   ├── branch-and-commit/
│       │   ├── merge-work/
│       │   ├── create_task/
│       │   ├── context_dump/
│       │   ├── archive-task/
│       │   └── feature-extract/
│       │
│       ├── TASKS/                     # Active task definitions
│       │   ├── _template.md
│       │   └── archive/               # Completed tasks
│       │
│       ├── HANDOVERS/                 # Persistent cross-session memory
│       │   ├── _template.md
│       │   ├── bootstrap_report.md
│       │   ├── repository_boundaries.md
│       │   └── topology_overview.md
│       │
│       ├── CONTEXT/                   # Architecture capsules
│       │   ├── _template.md
│       │   └── workspace_architecture.md
│       │
│       ├── PROJECT_RULES/             # Per-project specialized rules
│       │   └── _template.md
│       │
│       └── TASK_ARCHIVE/              # Daily completion indexes
│           └── _template.md
│
├── project-a/                         # Actual software project
│   ├── .git/
│   └── AGENTS.md                      # Project-local authority (created during init)
│
├── project-b/                         # Another software project
│   ├── .git/
│   └── AGENTS.md
│
└── docs/                              # Approved technical knowledge

Authority Chain (Boot Order)

When an agent starts work, it reads files in this order:

1. /.robotz/agents/BOOT_AUTHORITY.yaml — Where are templates and memory?
2. /.robotz/agents/RULES.md — What can and can't I do?
3. /.robotz/agents/BOOT.md — What's the full boot procedure?
4. /.robotz/Robotz.yaml — What projects and repositories exist?
5. /.robotz/agents/CODING_STANDARDS.md — What are the engineering standards?
6. /.robotz/agents/GIT_WORKFLOW_POLICY.md — What's the Git safety policy?
7. /.robotz/agents/GIT_PROVIDER_CONFIG.yaml — What Git provider am I talking to?
8. /.robotz/agents/PROJECT_RULES/<project>.md — Any project-specific rules?
9. <project>/AGENTS.md — Project-local authority
10. /.robotz/agents/CONTEXT/ — Relevant architecture capsules
11. /.robotz/agents/HANDOVERS/ — Relevant feature knowledge

Agents scan code only when this authority chain doesn't have the answer.

---

Multi-Provider Git Support

This framework is forge-agnostic. It doesn't assume GitHub. It detects your provider and adapts.

Supported Providers

Provider	CLI Tool	Code Review Term
GitHub	gh	Pull Request
GitLab	glab	Merge Request
Gitea	tea	Pull Request
Forgejo	tea	Pull Request
Codeberg	tea	Pull Request

How Provider Detection Works

git remote -v
       |
       v
Inspect origin URL
       |
       +-- github.com --------> provider: github
       +-- gitlab.com --------> provider: gitlab
       +-- codeberg.org ------> provider: codeberg
       +-- other host --------> probe /api/v1/version (Gitea/Forgejo)
                            -> probe /api/v4/version (GitLab)
                            -> fallback: ask human
       |
       v
Read .robotz/agents/GIT_PROVIDER_CONFIG.yaml
       |
       v
Resolve CLI tool, API base, auth method, code-review terminology

Example: Creating a Code Review

Instead of hardcoding gh pr create, agents follow this flow:

1. Detect provider from git remote -v or .robotz/Robotz.yaml
2. Read .robotz/agents/GIT_PROVIDER_CONFIG.yaml for provider config
3. Check if CLI tool is installed: command -v <cli_tool>
4. Execute provider-specific command from registry
5. Report using provider's terminology ("Opened pull request" vs "Opened merge request")

This means the same agent logic works identically across GitHub, GitLab, and self-hosted Forgejo instances.

---

CLI-First Execution Policy

Agents use CLI tools for ALL Git and forge operations. Direct API calls are forbidden.

This is a non-negotiable framework rule that protects your tokens and ensures predictable behavior.

Why CLI-First?

Concern	CLI Approach	API Approach
Security	Tokens stay in your CLI config/keyring	Tokens pass through agent context
Auditability	Every operation in shell history	Hidden HTTP requests
Reliability	CLIs handle auth refresh, rate limits	Agent must reimplement error handling
Consistency	Same as human developer workflow	Different behavior, unexpected results
Trust	You control auth, scopes, and sessions	Agent handles tokens opaquely

What This Means in Practice

✅ Agent WILL do:

• git push origin main
• gh pr create --title "feat: add auth"
• glab mr create --title "fix: bug"
• tea pulls list

❌ Agent will NEVER do:

• curl -H "Authorization: token $TOKEN" https://api.github.com/...
• Construct HTTP requests to create pull requests
• Use language HTTP libraries to interact with Git providers
• Handle raw tokens in agent logic

Missing CLI Tool?

If a CLI is not installed, the agent stops immediately and tells you exactly how to install it:

⚠️  Provider 'github' requires CLI tool 'gh' (min version 2.0).

Install it:
  brew install gh        # macOS
  sudo apt install gh    # Ubuntu/Debian
  winget install GitHub.cli  # Windows

Then authenticate:
  gh auth login

After that, re-run your request.

Provider CLI Quick Reference

Provider	CLI	Install	Login
GitHub	gh	Install Guide	gh auth login
GitLab	glab	Install Guide	glab auth login
Gitea	tea	go install code.gitea.io/tea@latest	tea logins add
Forgejo	tea	go install code.gitea.io/tea@latest	tea logins add
Codeberg	tea	go install code.gitea.io/tea@latest	tea logins add

---

Using This Framework in a New Project

Method A: Bootstrap a Fresh Project

# Navigate to the new project root
cd ~/projects/my-new-app

# Download and extract the framework ZIP
curl -fsSL -o aibook-framework.zip <distribution-url>
unzip aibook-framework.zip

# Tell your agent to initialize
"Initialize this project with the Robotz coordination layer"

The agent will:

1. Download and extract the framework ZIP (if not already done)
2. Run the init-project skill
3. Detect Git roots and provider
4. Ask you about project boundaries and topology
5. Write .robotz/Robotz.yaml and materialize .robotz/agents/ files
6. Verify your CLI tool is installed and authenticated
7. Create project rule stubs and initial memory

Method B: Using the Installer

For automated setup, use the INSTALLATION.md installer:

curl -fsSL https://git.atomika.io/atomika/aibook/raw/branch/main/INSTALLATION.md

Follow the instructions in the installer to bootstrap the framework into your project. The installer will:

1. Detect your Git provider
2. Verify CLI authentication
3. Run the init-project skill
4. Materialize .robotz/ and AGENTS.md
5. Delete itself after setup

Method C: Manual Setup

1. Download and extract the framework ZIP, then copy these files to your new project root:

   • .robotz/agents/BOOT_AUTHORITY.yaml
   • .robotz/agents/BOOT.md
   • .robotz/agents/RULES.md
   • .robotz/agents/CODING_STANDARDS.md
   • .robotz/agents/GIT_PROVIDER_CONFIG.yaml
   • .robotz/agents/CODE_REVIEW_TEMPLATE.md
   • .robotz/agents/config.yaml
   • .robotz/agents/agents_brain.md
   • .robotz/agents/skills/ (all skills)
   • .robotz/agents/TASKS/_template.md
   • .robotz/agents/HANDOVERS/_template.md
   • .robotz/agents/CONTEXT/_template.md
   • .robotz/agents/PROJECT_RULES/_template.md
   • .robotz/agents/TASK_ARCHIVE/_template.md
   • AGENTS.template (materialized as AGENTS.md in host project)

2. Create .robotz/Robotz.yaml from the descriptor schema

3. Run git init if needed and set remotes

4. Install and authenticate your provider's CLI tool (gh, glab, or tea)

5. Create AGENTS.md in project root (see INSTALLATION.md for template)

6. Tell your agent to fill in the placeholders

---

Key Concepts

Handovers (.robotz/agents/HANDOVERS/)

Cross-session memory. When an agent completes a feature or discovers something important, it writes a handover. The next agent reads it instead of re-analyzing code.

Use for:

• Feature documentation
• Repository boundaries
• Topology overviews
• Bootstrap reports
• Cross-project knowledge transfer

Context Capsules (.robotz/agents/CONTEXT/)

Architecture memory. Detailed descriptions of how systems work, stored as semantic capsules. Agents load these instead of scanning code.

Use for:

• Service architectures
• API contracts
• Database schemas
• Integration flows
• Runtime behavior

Tasks (.robotz/agents/TASKS/)

Scoped work definitions. Every non-trivial task gets a task file with status, constraints, acceptance criteria, and completion follow-up.

Lifecycle: todo -> in_progress -> done -> archived in .robotz/agents/TASKS/archive/

Skills (.robotz/agents/skills/)

Reusable workflows. Each skill is a structured procedure for a common operation.

Skill	Purpose
init-project	Bootstrap coordination layer in a new project
branch-and-commit	Create branches and conventional commits
merge-work	Rebase and fast-forward merge to main
create_task	Generate structured task files
context_dump	Capture architecture into context capsules
archive-task	Move completed tasks to archive with daily index

---

Git Workflow Safety

All Git operations are governed by .robotz/agents/GIT_WORKFLOW_POLICY.md.

Core principles:

• Deterministic behavior over convenience
• No history rewrite on shared branches
• No force-push
• Fast-forward only for autonomous merges
• Repository boundary verification is mandatory
• Controlled rebase only for local task branches

State classification:

State	Meaning	Action
CLEAN	Baseline	Proceed
READY_TO_BE_REBASED	Clean branch, can rebase	Enter rebase flow
BEHIND	Remote has new commits	git pull --ff-only
DIRTY_SAFE	Only lockfiles changed	Stage allowlist files
AHEAD	Local has unpushed commits	Escalate
DIVERGED	Both local and remote have unique commits	Escalate
CONFLICT	Merge/rebase conflicts	Escalate to human

---

Configuration Files

Robotz.yaml — Workspace Descriptor

Defines your workspace structure:

version: 1
name: my_workspace
authority:
  project_identity_and_pathing: authoritative

project_structure:
  standalone_repository_names:
    - frontend
    - backend
    - shared-lib
  repository_paths:
    frontend: ./frontend
    backend: ./backend
    shared-lib: ./shared-lib
  repository_project_names:
    frontend: acme/frontend
    backend: acme/backend
  repository_remote_uris:
    frontend: https://git.example.com/acme/frontend.git
    backend: https://git.example.com/acme/backend.git
  repository_providers:
    frontend:
      provider_type: forgejo
      provider_host: https://git.example.com
      forge_family: forgejo

system_topology:
  frontend:
    role: React SPA
    relates_with:
      - backend
  backend:
    role: Go API server
    relates_with:
      - shared-lib

Authentication — Handled by CLI Tools

This framework does not store tokens. Authentication is handled entirely by your provider's CLI tool:

• gh auth login → stores token in ~/.config/gh/
• glab auth login → stores token in ~/.config/glab-cli/
• tea logins add → stores token in OS keyring or ~/.config/tea/

Agents never read, store, or handle your tokens. They simply invoke the CLI tool, which manages its own authentication.

.robotz/agents/config.yaml — Agent Execution Profile

Controls how agents behave — autonomous mode, timeouts, tool access, command whitelist.

.robotz/agents/GIT_PROVIDER_CONFIG.yaml — Provider Registry

Maps every supported provider to its CLI tool, API endpoints, auth conventions, and code-review workflow. Read this before any provider-specific automation.

---

Example Workflows

Starting a New Feature

User: "Add user authentication to the backend"

Agent:
1. Reads RULES.md -> task required
2. Uses create_task skill -> drafts task file
3. Asks user for completion follow-up (merge / code review / nothing)
4. Creates .robotz/agents/TASKS/feature_user_authentication.md
5. Uses branch-and-commit skill -> creates feat/user-authentication branch
6. Implements the feature
7. Commits with conventional commit style
8. Updates context capsule if architecture changed
9. Writes handover documenting the feature
10. Asks if ready to submit code review
11. If yes: reads GIT_PROVIDER_CONFIG.yaml, detects provider, creates PR/MR

Working Across Multiple Projects

User: "Update the shared library and bump it in all services"

Agent:
1. Reads `.robotz/Robotz.yaml` -> discovers shared-lib, frontend, backend
2. Reads PROJECT_RULES/shared-lib.md
3. Modifies shared-lib, commits, pushes
4. Reads PROJECT_RULES/frontend.md and PROJECT_RULES/backend.md
5. Bumps dependency in both, creates separate commits per repo
6. Writes handover explaining the cross-project change

Code Review on Self-Hosted Forgejo

User: "Submit the auth feature for review"

Agent:
1. Reads GIT_WORKFLOW_POLICY.md
2. Verifies branch is READY_TO_BE_REBASED
3. Rebases onto main
4. Reads GIT_PROVIDER_CONFIG.yaml -> provider: forgejo, cli: tea
5. Checks: command -v tea -> installed
6. Runs: tea pr create --title "feat: add user authentication" ...
7. Reports: "Opened pull request #42 on Forgejo"

---

Adding a New Git Provider

If you use a forge not yet in the registry:

1. Open .robotz/agents/GIT_PROVIDER_CONFIG.yaml
2. Add a new entry under providers:
3. Define:
   • forge_family
   • cli_tool (or null if none exists)
   • code_review terminology and commands
   • auth methods
   • api base URLs
   • merge_methods

Example:

  myforge:
    forge_family: myforge
    cli_tool: myforge-cli
    code_review:
      term: review request
      abbreviation: RR
      cli_create_cmd: "myforge-cli review create --title '<title>'"
      web_create_pattern: "https://myforge.example.com/<owner>/<repo>/reviews/new"
    auth:
      methods:
        - personal_access_token
      token_env_var: MYFORGE_TOKEN
    api:
      rest_base: "https://myforge.example.com/api/v1"

---

Porting to Another Machine

This framework is fully portable:

1. Copy the workspace (only .robotz/ which contains Robotz.yaml and agents/)
2. Install the CLI tools for your providers (gh, glab, tea)
3. Authenticate each CLI tool on the new machine (gh auth login, glab auth login, tea logins add)
4. Done — agents boot identically on any machine

---

Rules for Humans

• Don't edit AGENTS.md without telling the agent. It's an authority file.
• Approve tasks before execution. The agent asks for approval on non-trivial work.
• Review handovers. They're the agent's memory — keep them accurate.
• Use ultrawork or ulw in prompts. It activates the full agent orchestration.

---

Troubleshooting

Agent doesn't detect my Git provider

• Check git remote -v output
• Verify .robotz/Robotz.yaml has repository_providers filled in
• Check that your provider's CLI tool is installed and authenticated

Code review creation fails

• Check that the provider's CLI tool is installed (gh, glab, tea)
• Verify the CLI is authenticated (gh auth status, glab auth status, tea whoami)
• Check GIT_PROVIDER_CONFIG.yaml has the correct provider entry

Agent scans too much code

• Ensure context capsules exist in .robotz/agents/CONTEXT/
• Check that handovers document the relevant features
• Verify BOOT_AUTHORITY.yaml is being read first

Multiple projects confused

• Verify .robotz/Robotz.yaml repository_paths are correct
• Check PROJECT_RULES/ has a file for each project
• Ensure repository_boundaries.md handover is accurate

---

License

This framework is unlicensed boilerplate. Use it, modify it, port it to any project.

---

Contributing

If you add support for a new Git provider, improve a skill, or refine the workflow:

1. Write a handover explaining the change
2. Update agents_brain.md
3. Update context capsules if architecture changed
4. Submit a code review using the provider-agnostic flow

---

Questions? Check .robotz/agents/HANDOVERS/bootstrap_report.md for your workspace's initial setup details, or ask your agent to read BOOT.md and explain the current state.