Ecosystems & Provisioning

Ecosystems are the top-level organizational unit in AMOF. They group repositories, define infrastructure targets, and establish safety guardrails -- all in a single YAML manifest.

What is an Ecosystem?

An ecosystem is a declarative configuration that represents a logical grouping of repositories that work together. Each ecosystem is fully isolated through Git worktrees, so multiple ecosystems can be active simultaneously.

A product: frontend + backend + infrastructure repos
A customer environment: customer-specific Helm charts + shared libraries
A platform: Supabase stack + custom extensions

Creating an Ecosystem

Via CLI

amof ecosystem create my-project

Manifest Example

ecosystems/<name>/ecosystem.yaml

name: my-project
description: "My multi-repo project"
workspace_dir: "worktrees/my-project"
provisioner: "k3d"

workspace:
  branch_prefix: workspace
  repo_branch_prefix: feature

devcontainer:
  enabled: true

context:
  max_files: 200
  summary_tokens: 2000

guardrails:
  no_touch_paths:
    - "*.pem"
    - "secrets/"
    - "**/credentials/**"

repos:
  - name: frontend
    url: "git@github.com:org/frontend.git"
    branch: main
    path: "repos/frontend"
    readonly: false
    enabled: true

  - name: backend
    url: "git@github.com:org/backend.git"
    branch: main
    path: "repos/backend"
    readonly: false

  - name: shared-infra
    url: "git@github.com:org/infra.git"
    branch: main
    path: "repos/infra"
    readonly: true

Manifest Reference

Top-Level Fields

Field	Type	Required	Description
name	string	Yes	Unique ecosystem identifier
description	string	No	Human-readable description
workspace_dir	string	No	Worktree directory (default: worktrees/<name>)
provisioner	string	No	Provisioner name (e.g., k3d, aws-spin, gcp-gke)

repos Array

Field	Type	Required	Description
name	string	Yes	Repository identifier
url	string	Yes	Git clone URL
branch	string	Yes	Base branch to track
path	string	No	Local path (default: repos/<name>)
readonly	boolean	No	If true, AI agent cannot modify files
enabled	boolean	No	If false, repo is skipped during sync
include	list	No	Only these paths are included in context generation
exclude	list	No	These paths are excluded from context generation

Manifest Validation

amof -e my-project manifest validate            # Standard validation
amof -e my-project manifest validate --strict   # Warnings become errors

Provisioners

Provisioners are pluggable infrastructure backends that create and destroy environments for ecosystems. Each provisioner is a self-contained directory under provisioners/ with a spin.sh entry point.

Provisioner	Target	Technology	What It Creates
k3d	Local	k3d CLI	Kubernetes-in-Docker cluster, ports 8081:80 and 8443:443
local-k3d	Local	k3d CLI	Development variant, ports 80:80 and 443:443
aws-spin	AWS	Terraform	VPC (10.0.0.0/16) + S3 artifact bucket
gcp-gke	GCP	Terraform	GKE cluster with preemptible e2-medium pool
azure-aks	Azure	Terraform	AKS cluster with Standard_B2s nodes
digitalocean-k3s	DigitalOcean	Terraform	Droplet with k3s via cloud-init
hetzner-k3s	Hetzner	Terraform	Cloud server with k3s, European region

# Deploy infrastructure
amof -e my-project spin deploy

# Tear down infrastructure
amof -e my-project spin destroy

Writing a Custom Provisioner

provisioners/my-provisioner/spin.sh

#!/usr/bin/env bash
set -euo pipefail

ACTION=$1
ECOSYSTEM_REF=$2

case $ACTION in
    deploy)
        echo "Creating infrastructure for $ECOSYSTEM_REF..."
        # Your deployment logic here
        ;;
    destroy)
        echo "Destroying infrastructure for $ECOSYSTEM_REF..."
        # Your teardown logic here
        ;;
    *)
        echo "Unknown action: $ACTION"
        exit 1
        ;;
esac

Set provisioner: my-provisioner in your ecosystem.yaml. AMOF will look for provisioners/my-provisioner/spin.sh.

Ecosystem Directory Structure

ecosystems/my-project/
  ecosystem.yaml        # Manifest (source of truth)
  spin.tfvars           # Terraform variables (if applicable)
  index/
    merkle-tree.json    # Merkle tree state
    codebase-index.json # AI codebase index
  archives/
    <ticket>.json       # Archived workspace states
  audit/
    *.md, *.json        # Session audit records
  journal/              # AI decision journals
  kb/                   # Knowledge base articles
  playbooks/            # Operational playbooks