GitHub Profile References: Enable Remote Profile Sharing

[fgrehm]

Motivation

Agent OS has a powerful profile inheritance system, but it's currently limited to local profiles in ~/agent-os/profiles/. As the community grows, there's an opportunity to enable profile sharing - allowing developers to reference and inherit from profiles hosted in GitHub repositories.

This would enable:

• Community-driven profiles for popular tech stacks (Rails, Django, Laravel, etc.)
• Organization-wide standards shared across teams via private repos
• Profile ecosystems where specialized profiles build on community bases
• Version pinning to ensure reproducible installations

Proposed Syntax

In agent-os/config.yml

version: 2.0.5
profile:
  source: github:username/repo/profiles/rails-fullstack
  ref: v1.2.0 # optional: branch, tag, or commit SHA
multi_agent_mode: true

In profile-config.yml (for inheritance)

inherits_from: github:communityorg/agent-os-web/profiles/base-api@v2.0

exclude_inherited_files:
  - standards/testing/*

Backward Compatibility

# Old format still works (treated as local)
profile: custom

# Equivalent to:
profile:
  source: local:custom

How It Works (High Level)

1. During installation, project-install.sh detects GitHub profile references
2. Fetches the profile to a local cache at ~/.agent-os/cache/github/user/repo/
3. Resolves inheritance chains that may span GitHub and local profiles
4. Compiles normally using the existing profile resolution logic

Updates are hybrid: cached locally but manually updated via update-github-profiles.sh or prompted during project-update.sh.

Relationship to Discussion #200 (Project Mixins)

This proposal is complementary to the Project Mixins discussion:

• Mixins enable composability of local components
• GitHub references enable distribution and sharing of those components
• Combined: --profile github:user/base --mixins github:otheruser/auth-mixin

Implementation Details

Cache Structure

Profiles are cached at ~/.agent-os/cache/github/:

~/.agent-os/cache/github/
├── username/
│   └── reponame/
│       ├── .metadata          # tracks ref, last_fetch, etag
│       └── profiles/
│           └── rails-fullstack/
│               ├── profile-config.yml
│               ├── agents/
│               ├── commands/
│               ├── roles/
│               ├── standards/
│               └── workflows/

Profile Resolution Algorithm

resolve_profile(source):
  if source starts with "github:":
    parse -> user, repo, path, ref
    cache_path = fetch_or_use_cache(user, repo, ref)
    return cache_path + path
  else if source starts with "local:" OR is simple name:
    return ~/agent-os/profiles/{name}

Inheritance Chain Resolution

The existing get_profile_file() function already walks inheritance chains. This extends it:

get_profile_file(profile_source, file_path):
  current = profile_source
  visited = []

  while true:
    if current in visited:
      error "Circular inheritance"

    visited.append(current)
    base_path = resolve_profile(current)

    if file exists at base_path/file_path:
      return it

    config = read base_path/profile-config.yml
    if config has "inherits_from":
      if file_path matches exclusion patterns:
        return not found
      current = config.inherits_from
      continue
    else:
      return not found

Example chain:

github:user1/rails/profiles/fullstack@v2
  ↓ (inherits_from)
github:user2/web/profiles/base-api@v1.5
  ↓ (inherits_from)
local:default

GitHub Integration Details

Fetching Profiles

Use GitHub's raw content API (no authentication needed for public repos):

# Fetch a single file
https://raw.githubusercontent.com/user/repo/ref/profiles/name/profile-config.yml

# For entire profile, recursively fetch directory structure:
# 1. Use GitHub API to list directory contents (requires traversal)
# 2. Download each file to cache

Version References

Support multiple ref types:

# Branch (tracks latest)
source: github:user/repo/profiles/rails@main

# Tag (pinned version)
source: github:user/repo/profiles/rails@v1.2.0

# Commit SHA (exact snapshot)
source: github:user/repo/profiles/rails@a1b2c3d

# Default (no ref = main branch)
source: github:user/repo/profiles/rails

Update Strategy

Initial fetch: During project-install.sh, download and cache

Metadata tracking in ~/.agent-os/cache/github/user/repo/.metadata:

ref: v1.2.0
last_fetch: 2025-10-17 14:30:00
etag: "abc123..." # GitHub's ETag for conditional requests
resolved_sha: a1b2c3d # what the ref resolved to

Update paths:

1. Manual: ~/agent-os/scripts/update-github-profiles.sh [profile-source]
2. Prompted: During project-update.sh, check if cache is stale (>7 days) and prompt
3. Force: project-update.sh --update-github-profiles

Private Repositories (Future)

For v1, support public repos only. Future enhancement:

# Store token in ~/.agent-os/github-token
echo "ghp_yourtoken" > ~/.agent-os/github-token
chmod 600 ~/.agent-os/github-token

# Installation scripts check for token when fetching

New Scripts and Functions

New File: scripts/github-functions.sh

Core functions for GitHub integration:

# Parse github:user/repo/path@ref format
parse_github_source() {
  local source=$1
  # Returns: user, repo, path, ref
}

# Fetch profile from GitHub to cache
fetch_github_profile() {
  local user=$1
  local repo=$2
  local path=$3
  local ref=${4:-main}

  # Downloads to ~/.agent-os/cache/github/user/repo/
  # Updates .metadata file
}

# Get local path to cached profile
get_cached_profile_path() {
  local user=$1
  local repo=$2

  echo "$HOME/.agent-os/cache/github/$user/$repo"
}

# Check if cached profile needs update
is_cache_stale() {
  local cache_path=$1
  local max_age_days=${2:-7}

  # Reads .metadata, checks last_fetch
}

# Update cached profile from GitHub
update_github_profile() {
  local source=$1

  # Re-fetches, uses ETag for conditional request
}

New Script: scripts/update-github-profiles.sh

#!/bin/bash
# Update cached GitHub profiles

# Usage:
#   update-github-profiles.sh                    # update all cached profiles
#   update-github-profiles.sh user/repo/path     # update specific profile

Modified: scripts/common-functions.sh

Extend existing functions to handle GitHub sources:

# Modified to call resolve_profile() first
get_profile_file() {
  local profile_source=$1
  local file_path=$2
  local base_dir=$3

  # NEW: Resolve GitHub or local source
  local resolved_path=$(resolve_profile_source "$profile_source" "$base_dir")

  # EXISTING: Walk inheritance chain
  # ... rest of function unchanged
}

# NEW: Resolve source to filesystem path
resolve_profile_source() {
  local source=$1
  local base_dir=$2

  if [[ "$source" == github:* ]]; then
    parse_github_source "$source"
    ensure_cached "$user" "$repo" "$path" "$ref"
    get_cached_profile_path "$user" "$repo"
  else
    # Local profile
    echo "$base_dir/profiles/$source"
  fi
}

Modified: scripts/project-install.sh

# In load_configuration(), after reading config:
if [[ "$EFFECTIVE_PROFILE" == github:* ]]; then
  print_status "Fetching GitHub profile..."
  fetch_github_profile "$EFFECTIVE_PROFILE"
fi

# Rest of installation proceeds normally

Modified: scripts/project-update.sh

# In perform_update(), before updating files:
if [[ "$PROJECT_PROFILE" == github:* ]]; then
  if is_cache_stale "$(get_cached_profile_path ...)"; then
    print_warning "GitHub profile cache is stale"
    read -p "Update from GitHub? (y/n): " -n 1 -r
    if [[ $REPLY =~ ^[Yy]$ ]]; then
      update_github_profile "$PROJECT_PROFILE"
    fi
  fi
fi

Example Use Cases

Use Case 1: Community Rails Profile

Someone creates a comprehensive Rails profile:

# github.com/railscommunity/agent-os-rails/profiles/fullstack/profile-config.yml
inherits_from: github:buildermethods/agent-os/profiles/default
# Adds Rails-specific standards, agents, workflows

Users install it:

cd my-rails-app
~/agent-os/scripts/project-install.sh \
  --profile github:railscommunity/agent-os-rails/profiles/fullstack@v2.1.0

Use Case 2: Organization Standards

A company maintains private profile:

# github.com/acmecorp/engineering-standards/agent-os/rails-api/profile-config.yml
inherits_from: github:railscommunity/agent-os-rails/profiles/api@v1.0
# Adds Acme-specific standards, naming conventions, etc.

Teams use:

~/agent-os/scripts/project-install.sh \
  --profile github:acmecorp/engineering-standards/agent-os/rails-api@main

Use Case 3: Versioned Upgrades

Pin to specific version initially:

profile:
  source: github:community/profiles/nextjs@v1.0.0

Later, upgrade explicitly:

profile:
  source: github:community/profiles/nextjs@v2.0.0

Run project-update.sh --re-install to apply new profile version.

Use Case 4: Forking and Customizing

1. Fork a community profile on GitHub
2. Customize standards/workflows
3. Reference your fork:

profile:
  source: github:myusername/agent-os-rails/profiles/custom@main

Your fork can still inherit from the original:

inherits_from: github:railscommunity/agent-os-rails/profiles/fullstack@v2.0

Migration Path

For Existing Installations

No breaking changes - all existing profiles continue working:

# These all work:
profile: default
profile: navigator
profile: chezmoi

# Automatically treated as:
profile:
  source: local:default

Gradual Adoption

1. Phase 1: Add GitHub functions, update resolution logic (backward compatible)
2. Phase 2: Community creates and shares profiles
3. Phase 3: Documentation and best practices emerge
4. Future: Registry/discovery mechanism for popular profiles

Security Considerations

Trust Model

Users explicitly specify sources: No automatic discovery prevents supply chain attacks

Version pinning: Commit SHAs provide immutability

# Can't be changed without user updating config
source: github:user/repo/profiles/name@a1b2c3d4e5f6

Validation

Before using cached profile:

1. Verify profile-config.yml exists and is valid YAML
2. Check inheritance chains for cycles
3. Validate file paths don't escape profile directory

Private Repos (Future)

If implementing private repo support:

• Token stored in ~/.agent-os/github-token with 600 permissions
• Read-only scope only
• Token never committed or shared
• Clear documentation about token security

Questions for the Community

1. Profile discovery: Should there be a registry or list of recommended community profiles?
2. Caching strategy: Is 7-day staleness check the right default? Configurable?
3. Monorepo support: Should we support github:user/monorepo/packages/agent-os-profiles/rails?
4. Shorthand syntax: Should we support github:user/repo defaulting to profiles/default?
5. Mixed sources: Should a single project support multiple GitHub sources (for mixins)?

Next Steps

If there's interest in this feature:

1. Implement core GitHub functions in a branch
2. Add tests for profile resolution with GitHub sources
3. Update documentation with examples
4. Create a few example community profiles for testing
5. Consider integration with the Project Mixins proposal

---

Feedback welcome! This is a draft proposal to start the conversation.