# @template-name: Users/samhenry/tailwind-ai-workspace/roadcrew/templates/repos.yml
# @version: 1.0.0
# @release-date: 2025-10-25
# repos.yml - Multi-Repo Orchestration Configuration
#
# This file enables Mode 2 (multi-repo orchestration) where Roadcrew manages
# releases across multiple microservice repositories from a central location.
#
# Usage:
#   /scope-release --project backend
#   /enrich-release --project frontend
#   /sync-release-to-github --project database
#
# For more information, see: docs/multi-repo.md

# Organization name (GitHub org that owns all projects)
organization: {{GITHUB_ORG}}

# GitHub API configuration
github:
  # Environment variable name for GitHub token (default: GH_TOKEN)
  # Create token at: https://github.com/settings/tokens
  # Required scopes: repo, read:org
  token_env: GH_TOKEN

# Project configurations (one entry per microservice/repository)
projects:
  # Example: Frontend service
  {{PROJECT_NAME_1}}:
    # GitHub repository in "org/repo" format
    repo: {{GITHUB_ORG}}/{{REPO_NAME_1}}
    
    # Path to release file in this roadcrew repo (relative to repo root)
    release_file: memory-bank/releases/{{PROJECT_NAME_1}}-release.md
    
    # If not specified, falls back to memory-bank/techContext.md
    technical_context: config/repos/{{GITHUB_ORG}}-{{REPO_NAME_1}}/techContext.md (or memory-bank/techContext.md)
    
    # Default labels to apply to created issues (optional)
    default_labels:
      - enhancement
      - {{PROJECT_NAME_1}}

  # Example: Backend service
  {{PROJECT_NAME_2}}:
    repo: {{GITHUB_ORG}}/{{REPO_NAME_2}}
    release_file: memory-bank/releases/{{PROJECT_NAME_2}}-release.md
    # If not specified, falls back to memory-bank/techContext.md
    technical_context: config/repos/{{GITHUB_ORG}}-{{REPO_NAME_2}}/techContext.md
    default_labels:
      - enhancement
      - {{PROJECT_NAME_2}}

  # Example: Database service
  {{PROJECT_NAME_3}}:
    repo: {{GITHUB_ORG}}/{{REPO_NAME_3}}
    release_file: memory-bank/releases/{{PROJECT_NAME_3}}-release.md
    # If not specified, falls back to memory-bank/techContext.md
    technical_context: config/repos/{{GITHUB_ORG}}-{{REPO_NAME_3}}/techContext.md
    default_labels:
      - enhancement
      - {{PROJECT_NAME_3}}

# ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
# CONFIGURATION EXAMPLES
# ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

# Example 1: Single-repo project (Mode 1 - submodule mode, no repos.yml needed)
# When repos.yml doesn't exist, commands operate on the local repository only.

# Example 2: 3-repo microservices architecture
# organization: acme-corp
# projects:
#   frontend:
#     repo: acme-corp/web-app
#     release_file: memory-bank/releases/frontend-v2.md
#     technical_context: config/repos/acme-corp-web-app/techContext.md
#     default_labels: [enhancement, frontend]
#   backend:
#     repo: acme-corp/api-server
#     release_file: memory-bank/releases/backend-v2.md
#     technical_context: config/repos/acme-corp-api-server/techContext.md
#     default_labels: [enhancement, backend]
#   database:
#     repo: acme-corp/db-migrations
#     release_file: memory-bank/releases/database-v2.md
#     technical_context: config/repos/acme-corp-db-migrations/techContext.md
#     default_labels: [enhancement, database]

# Example 3: Monorepo with multiple release streams
# organization: startup-inc
# projects:
#   mobile:
#     repo: startup-inc/monorepo
#     release_file: memory-bank/releases/mobile-v1.md
#     technical_context: config/repos/startup-inc-monorepo/mobile-techContext.md
#     default_labels: [enhancement, mobile]
#   web:
#     repo: startup-inc/monorepo
#     release_file: memory-bank/releases/web-v1.md
#     technical_context: config/repos/startup-inc-monorepo/web-techContext.md

# ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
# FIELD REFERENCE
# ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

# organization (required)
#   GitHub organization name that owns all repositories
#
# github.token_env (optional, default: GH_TOKEN)
#   Environment variable containing GitHub personal access token
#   Token must have 'repo' and 'read:org' scopes
#
# projects (required)
#   Map of project names to project configurations
#   Project name is used with --project flag in commands
#
# projects.<name>.repo (required)
#   GitHub repository in "org/repo" format
#   This is where issues will be created
#
# projects.<name>.release_file (required)
#   Path to release markdown file in this roadcrew repository
#   Used to track release progress and scope
#
# projects.<name>.technical_context (optional)
#   Path to technical context file (e.g., memory-bank/techContext.md) for this project
#   Falls back to memory-bank/techContext.md if not specified
#   Enables project-specific framework/deployment detection and enrichment
#
# projects.<name>.default_labels (optional)
#   Array of label names to apply to all created issues
#   Labels must exist in target repository
#
# ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
# TROUBLESHOOTING
# ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

# Error: "GitHub authentication failed"
#   → Set GH_TOKEN or GITHUB_TOKEN environment variable
#   → Verify token has 'repo' and 'read:org' scopes
#
# Error: "Project 'xyz' not found in repos.yml"
#   → Check project name spelling (case-sensitive)
#   → Verify repos.yml is in config/ directory
#   → Run: grep -A 5 "projects:" config/repos.yml
#
# Error: "Permission denied to create issues in org/repo"
#   → Verify GitHub token has write access to target repository
#   → Check that you're a member of the GitHub organization
#
# Error: "Label 'xyz' does not exist in repository"
#   → Create missing labels in target repository first
#   → Or remove from default_labels list
#