team-home — Architecture Blueprint

Three-Layer Architecture

Hub

Universal. One for everyone. Never cloned by users. Serves CLI + templates on demand.

team-home CLI templates/ install.sh

Group Context

One per organization. Teams discovered dynamically from GitLab namespace.

group.md spoke.yaml context/ CONSTITUTION.md

Team Repos

One per team. Independent git repos. Each owns its own skills and context.

team.md skills/ agents/ context/

graph LR
  Hub("🗄️ Hub Repo"):::hub -- "curl install" --> CLI("💻 CLI on laptop"):::cli
  CLI -- "team-home init" --> GC("📋 Group Context"):::group
  CLI -- "team add crimson" --> S1("🔴 Crimson"):::team
  CLI -- "team add zaffre" --> S2("🔵 Zaffre"):::team
  GC -- "namespace lookup" --> API("🔍 GitLab API"):::api
  API -. "discovers" .-> S1
  API -. "discovers" .-> S2

  classDef hub fill:#dbeafe,stroke:#3b82f6,stroke-width:2px,color:#1e3a5f,rx:12
  classDef cli fill:#f0fdf4,stroke:#22c55e,stroke-width:2px,color:#14532d,rx:12
  classDef group fill:#fef3c7,stroke:#f59e0b,stroke-width:2px,color:#78350f,rx:12
  classDef team fill:#ede9fe,stroke:#8b5cf6,stroke-width:2px,color:#3b0764,rx:12
  classDef api fill:#fce7f3,stroke:#ec4899,stroke-width:2px,color:#831843,rx:12

Where Things Live

On GitLab (Remote)

Hub repo — never cloned; serves CLI + templates
Group Context repo — one per org; group.md, context/
Team repos — one per team; independent git repos
GitLab namespace — used for dynamic team discovery

On Your Laptop (Local)

.team-home/config.yaml — hub + group URLs
group-context/ — cloned from GitLab
teams/<name>/ — cloned on demand via team add
CLAUDE.md — auto-generated AI context file

03 / 12

Journey: Setting Up a New Organization

Dana — Senior Manager, RHOAI Dashboard

Dana is the org lead. She needs to set up team-home for the entire RHOAI Dashboard org, then onboard her first team.

Install the CLI

curl -sSL https://gitlab.com/.../install.sh | bash

Downloads the team-home script to ~/.local/bin/. No dependencies beyond bash, git, and curl.

Initialize — Start a new group

team-home init

Selects Path 1: Start a new group. The CLI asks for org details interactively.

$ team-home init ? What would you like to do? [1] Start a new group [2] Set up my workspace (join existing group) ? Organization name: RHOAI Dashboard ? Short name (used in paths): rhoai-dashboard ? GitLab namespace: redhat/ai/rhoai-dashboard-team ? Org lead name: Dana Gutride ✓ Created group-context repo on GitLab ✓ Scaffolded: group.md, CONSTITUTION.md, context/ ✓ Workspace created: ./rhoai-dashboard/ Next: team-home team add <team-name>

Add the first team

team-home team add crimson

Creates the team repo on GitLab, scaffolds team.md, spoke.yaml, and the 360 skill template. Clones it locally.

$ team-home team add crimson ✓ Created team repo: redhat/ai/rhoai-dashboard-team/crimson ✓ Scaffolded: team.md, spoke.yaml, 360 skill template ✓ Cloned to teams/crimson/ ✓ Active team set to: crimson

Fill in team.md

Open teams/crimson/team.md and fill in team members, Jira labels, product repos, and Confluence details. This is the only manual editing required — see the team.md Contract slide for the full schema.

Add more teams as they join

team-home team add zaffre

Repeat for each team. They can also run this themselves — it's not restricted to the org lead.

✓

Done — see the full picture

team-home team list

$ team-home team list RHOAI Dashboard (ODH Dashboard) Lead: Dana Gutride Namespace: gitlab.com/redhat/ai/rhoai-dashboard-team Teams (2 in org, 2 cloned locally): * crimson main clean up to date * zaffre main clean up to date

What if GitLab repo creation fails?

Local scaffolding always completes. If the CLI can't create the GitLab repo (permissions, network), it prints manual instructions:

git remote add origin git@gitlab.com:redhat/ai/rhoai-dashboard-team/crimson.git
git push -u origin main

~5 minutes for first org + first team

05 / 12

Journey: Joining an Existing Team

Avik — New Developer, Crimson Team

Avik just joined the company. His team already exists on GitLab. He needs a local workspace.

Install the CLI

curl -sSL https://gitlab.com/.../install.sh | bash

Same one-liner as the org lead. Takes seconds.

Initialize — Join existing group

team-home init

Selects Path 2: Set up my workspace. Enters the group context URL (provided by his manager).

$ team-home init ? What would you like to do? [1] Start a new group [2] Set up my workspace (join existing group) ? Group context repo URL: git@gitlab.com:redhat/ai/rhoai-dashboard-team/dashboard-team-context.git ✓ Cloned group context ✓ Workspace created: ./rhoai-dashboard/ Discovered teams: crimson, zaffre, agent-ops, kubeflow-devx Next: team-home team add <team-name>

Add his team

team-home team add crimson

The CLI finds the existing Crimson repo on GitLab and clones it. No scaffolding needed — the repo already has team.md, skills, and config.

$ team-home team add crimson ✓ Found existing repo: redhat/ai/rhoai-dashboard-team/crimson ✓ Cloned to teams/crimson/ ✓ Active team set to: crimson

✓

Done — ready to work

team-home status

$ team-home status team-home workspace: /home/akundu/rhoai-dashboard/ Active team: crimson Group context: group-context/ main clean up to date Team repos: crimson main clean up to date CLAUDE.md: present

What Avik didn't need to do

No GitLab repo creation. No YAML editing. No infrastructure knowledge. Just a URL from his manager and two commands.

~2 minutes

06 / 12

The team.md Contract

Every team repo centers on one file. Skills read from it. Reports generate from it. Fill it once, everything works.

--- team_name: Crimson team_lead: Avik Kundu members: - name: Avik Kundu github: avik-kunduu role: Lead - name: Rizel Scarlett github: blackgirlbytes role: Developer jira_label: dashboard-crimson-scrum jira_boards: doing: "RHOAIENG board" product_repos: - openshift/console - red-hat-data-services/odh-dashboard confluence: space: RHOAIENG parent_page_id: "123456" slack_channel: "#team-crimson" --- # Crimson Team Human-readable description, goals, current focus areas...

Field Reference

Required Fields

team_name — display name, used in reports
team_lead — shown in org views
members — drives per-person activity in 360 reports
jira_label — filters Jira issues for the team

Optional Fields

jira_boards — board data for sprint tracking
product_repos — GitHub repos for PR/commit stats
confluence — auto-publish reports to Confluence
slack_channel — post weekly summaries to Slack

This is the only file you must fill in

Everything else — the 360 skill, the pipeline config, the report templates — works out of the box after scaffolding. team.md is the single source of truth for all automation.

07 / 12

360 Skill: Generic by Default

One generic skill ships with every team repo. It reads everything from team.md — no hardcoded team names.

flowchart LR
  CS("➕ team add"):::cmd --> SK("📦 360 skill scaffolded"):::scaffold
  SK --> TM("📝 Team fills in team.md"):::edit
  TM --> RUN("⚡ 360 automation works"):::run

  classDef cmd fill:#dbeafe,stroke:#3b82f6,stroke-width:2px,color:#1e3a5f,rx:12
  classDef scaffold fill:#ede9fe,stroke:#8b5cf6,stroke-width:2px,color:#3b0764,rx:12
  classDef edit fill:#fef3c7,stroke:#f59e0b,stroke-width:2px,color:#78350f,rx:12
  classDef run fill:#dcfce7,stroke:#22c55e,stroke-width:2px,color:#14532d,rx:12

What the skill reads from `team.md`

members → per-person activity

github_handles → PR queries

jira_boards.doing → board data

jira_label → issue filtering

product_repos → GitHub activity

confluence → report publishing

What It Produces

📊

HTML Dashboard
weekly health report

💬

Slack Message
team channel summary

📝

Confluence Page
published under team space

💾

Git Commit
raw report in repo

Customization Tiers

Use As-Is

Fill team.md, never touch the skill

Most teams

Light Tweaks

Edit sections list in gather_360.py

Some teams

Heavy Rewrite

Fork the skill directory, build your own

Rare

08 / 12

Automation Pipeline

The 360 skill runs weekly via GitLab CI. One pipeline config, team-specific data from team.md.

flowchart LR
  SCH("⏰ Weekly Schedule"):::trigger --> PIPE("⚙️ GitLab CI Pipeline"):::pipe
  PIPE --> GATHER("📄 gather_360.py reads team.md"):::gather
  GATHER --> HTML("📊 Generate HTML Report"):::report
  HTML --> CONF("📝 Publish to Confluence"):::output
  HTML --> SLACK("💬 Post to Slack"):::output
  HTML --> GIT("💾 Commit to Repo"):::output

  classDef trigger fill:#fef3c7,stroke:#f59e0b,stroke-width:2px,color:#78350f,rx:12
  classDef pipe fill:#dbeafe,stroke:#3b82f6,stroke-width:2px,color:#1e3a5f,rx:12
  classDef gather fill:#ede9fe,stroke:#8b5cf6,stroke-width:2px,color:#3b0764,rx:12
  classDef report fill:#fce7f3,stroke:#ec4899,stroke-width:2px,color:#831843,rx:12
  classDef output fill:#dcfce7,stroke:#22c55e,stroke-width:2px,color:#14532d,rx:12

Required CI Variables

GITLAB_TOKEN

GitLab API access

Settings → Access Tokens

GITHUB_TOKEN

PR and commit data

GitHub → Developer Settings

JIRA_TOKEN

Board and issue data

Atlassian → API Tokens

CONFLUENCE_TOKEN

Report publishing

Same as Jira token

SLACK_WEBHOOK_URL

Team notifications

Slack → Workflow Builder

Setup Checklist

Fill in team.md with real team data (already done during onboarding)
Set 5 CI variables in GitLab project → Settings → CI/CD → Variables
Pipeline runs automatically on the weekly schedule
First report appears within one week — no other action needed

09 / 12

Incremental Adoption

Teams join at their own pace. The CLI discovers them dynamically from GitLab.

flowchart LR
  N("⬜ Not Created"):::inactive -->|"team-home team add"| O("🟡 Onboarding"):::onboard
  O -->|"team.md filled + CI vars set"| A("🟢 Active"):::active

  classDef inactive fill:#f1f5f9,stroke:#94a3b8,stroke-width:2px,color:#475569,rx:12
  classDef onboard fill:#fef3c7,stroke:#f59e0b,stroke-width:2px,color:#78350f,rx:12
  classDef active fill:#dcfce7,stroke:#22c55e,stroke-width:2px,color:#14532d,rx:12

Not Created

Team exists in org but hasn't run team add. Shows as (not cloned) in team list.

Pending

Onboarding

Repo exists, team.md has template values. 360 skill scaffolded but not yet configured.

In progress

Active

team.md filled with real data, CI variables set, 360 reports generating weekly.

Live

$ team-home team list

RHOAI Dashboard (ODH Dashboard)
  Lead: Dana Gutride
  Namespace: gitlab.com/redhat/ai/rhoai-dashboard-team

Teams (4 in org, 2 cloned locally):

  * crimson           main    clean    up to date
  * zaffre            main    clean    up to date
    agent-ops         (not cloned)
    kubeflow-devx     (not cloned)

  * = cloned locally

Staying Up to Date

CLI Updates

team-home upgrade

Downloads the latest CLI script from the hub. Your workspace and team repos are not affected.

Template Updates

Automatic

Templates are fetched fresh from the hub every time init or team add scaffolds. Never bundled in the CLI.

Existing Teams

Opt-in

Already-scaffolded teams are never force-updated. Future: team-home skill upgrade for opt-in template pulls.

10 / 12

Team Commands — team-home team <verb>

team add <name>

Add a team — clone existing or create new

Checks if a repo exists on GitLab for this team. If yes, clones it. If not, walks you through creating one interactively.

Scaffolds team.md, spoke.yaml, 360 skill template
Creates GitLab repo (best-effort — gives manual instructions if it can't)
Offers to clone product repos listed in team.md
Sets as active team + rebuilds CLAUDE.md

$ team-home team add agent-ops ✓ Created team repo on GitLab: redhat/ai/rhoai-dashboard-team/agent-ops ✓ Scaffolded: team.md, spoke.yaml, 360 skill template ✓ Cloned to teams/agent-ops/ ✓ Active team set to: agent-ops

Who uses it: Any team member. Not restricted to org leads.

team remove <name>

Remove a team from your local workspace

Removes the local clone only. The GitLab repo is never touched. Warns about uncommitted/unpushed changes before removing.

$ team-home team remove zaffre teams/zaffre/ has 2 unpushed commits. Remove locally? (GitLab repo is not affected.) [y/N] y ✓ Removed 'zaffre' locally. Run 'team-home team add zaffre' to re-clone anytime.

team list

List all teams in your org (local + remote)

Shows the full org picture: group info from group.md, all teams discovered from GitLab, and git state for locally cloned ones.

$ team-home team list RHOAI Dashboard (ODH Dashboard) Lead: Dana Gutride Namespace: gitlab.com/redhat/ai/rhoai-dashboard-team Jira: RHOAIENG, RHAISTRAT Teams (4 in org, 2 cloned locally): * crimson main clean up to date * zaffre main dirty(3) 2 ahead agent-ops (not cloned) kubeflow-devx (not cloned)

team use <name>

Set your active team

Switches the active team context. Updates .team file and rebuilds CLAUDE.md so AI assistants know which team you're working with.

$ team-home team use crimson ✓ Active team set to: crimson

Follows nvm use / kubectl config use-context convention.

Workspace Commands — team-home <command>

init

Set up a new group or join an existing one

Interactive, two paths:

Path 1 — Start a new group: collects org info, creates group context repo on GitLab, scaffolds files locally.
Path 2 — Set up my workspace: asks for group context URL, clones it, shows available teams, lets you pick or create one.

Local scaffolding always completes — if GitLab fails, you get clear manual instructions.

$ team-home init ? What would you like to do? [1] Start a new group [2] Set up my workspace (join existing group) ✓ Created group context on GitLab ✓ Set up workspace: ./rhoai-dashboard/ Next: team-home team add crimson

sync

Pull latest for all cloned repos (ff-only, safe)

Syncs group-context + all team repos under teams/. Uses git pull --ff-only. Skips repos that are dirty, on a different branch, or have unpushed commits.

$ team-home sync Syncing workspace... group-context: updated (a1b2c3d → e4f5g6h) crimson: up to date zaffre: skipped — 3 uncommitted change(s) agent-ops: updated (1234567 → 89abcde) 3 synced, 1 skipped.

status

Show local workspace state

Fast, no network needed. Shows workspace root, active team, and git state for all local repos. For org-wide view, use team list.

$ team-home status team-home workspace: /home/dgutride/rhoai-dashboard/ Active team: crimson Group context: group-context/ main clean up to date Team repos: crimson main clean up to date zaffre main dirty(3) 2 ahead CLAUDE.md: present

upgrade

Update the team-home CLI to latest version

Downloads the latest CLI script from the hub repo. Templates are not bundled — they are fetched on demand when init or team add scaffolds, so they are always fresh.

$ team-home upgrade Current version: v1.2.0 Latest version: v1.3.0 Upgrading team-home CLI... ✓ Upgraded to v1.3.0

context refresh

Rebuild CLAUDE.md from current state

Regenerates the AI context file at the workspace root. Runs automatically after team add, team remove, team use, sync. Rarely needed manually.

CLAUDE.md tells AI assistants (Cursor, Claude) what's in your workspace and where to find things.

help

Show usage and getting-started guide

$ team-home help team-home — workspace CLI for team context-as-code Team commands: team add <name> Add a team (clone or create) team remove <name> Remove a team locally team list List all teams in your org team use <name> Set your active team Workspace commands: init Set up a new group or join existing sync Pull latest for all cloned repos status Show local workspace state upgrade Update the CLI to latest version context refresh Rebuild CLAUDE.md help Show this help

team-home
Scalable Team Infrastructure

The Problem: Hub = Workspace

Three-Layer Architecture

Where Things Live

Getting Started: Three Steps

Which path is yours?

Journey: Setting Up a New Organization

Journey: Joining an Existing Team

The team.md Contract

Field Reference

360 Skill: Generic by Default

What the skill reads from `team.md`

What It Produces

Customization Tiers

Automation Pipeline

Required CI Variables

Setup Checklist

Incremental Adoption

Staying Up to Date

CLI Reference

Before & After

team-homeScalable Team Infrastructure

The Problem: Hub = Workspace

Three-Layer Architecture

Where Things Live

Getting Started: Three Steps

Which path is yours?

Journey: Setting Up a New Organization

Journey: Joining an Existing Team

The team.md Contract

Field Reference

360 Skill: Generic by Default

What the skill reads from team.md

What It Produces

Customization Tiers

Automation Pipeline

Required CI Variables

Setup Checklist

Incremental Adoption

Staying Up to Date

CLI Reference

Before & After

team-home
Scalable Team Infrastructure

What the skill reads from `team.md`