team-home
Scalable Team Infrastructure

Architecture Blueprint — August 2026
A CLI that lets any organization set up standardized team workspaces, ship automation skills, and track adoption — without cloning a monolithic repo.
2
commands to set up
0
repos to clone manually
3
architecture layers
10
CLI commands
01 / 09

The Problem: Hub = Workspace

Today, every user clones the entire hub repo. The CLI, shared modules, docs, and team repos all live in one place.
Cloning pulls 20+ items — most irrelevant to the user
No dynamic team discovery — manual tracking
Hub folders mixed with team repos — unclear boundaries
Some teams are real repos, others are 4-file stubs
External orgs can't adopt without org-specific content
4 commands needed to get a working workspace
02 / 09

Three-Layer Architecture

1
Hub
Universal. One for everyone. Never cloned by users. Serves CLI + templates on demand.
team-home CLI templates/ install.sh
2
Group Context
One per organization. Teams discovered dynamically from GitLab namespace.
group.md spoke.yaml context/ CONSTITUTION.md
3
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
03 / 09

Setup: Two Commands

From zero to a working workspace in under two minutes. No cloning, no repo knowledge needed.
1
Install CLI
curl install.sh | bash
Single script, no dependencies
→
2
Initialize
team-home init
Interactive — new group or join existing
→
3
Add Your Team
team-home team add crimson
Clones or creates team repo
rhoai-dashboard/
├── .team-home/
│   └── config.yaml ← hub + group URLs
├── group-context/
│   ├── group.md ← org handbook
│   ├── CONSTITUTION.md
│   └── context/ ← jira.md, product.md, release-calendar.md
└── teams/
    └── crimson/
       ├── team.md ← team config
       ├── skills/generate-360-report/
       └── spoke.yaml
04 / 09

Two Personas, Right-Sized Workspaces

Dana — Senior Manager (Org Lead)
  • Owns group-context/
  • Clones team repos on demand via team add
  • Runs team list to see all teams
  • Sees full org status at a glance
Avik — Developer (Crimson Team)
  • Has group-context/ as read-only reference
  • Only his own team cloned locally
  • Edits team.md, runs skills
  • Never sees other teams' repos
graph TB
  subgraph avik ["👨‍💻  Avik — Developer"]
    direction TB
    A_GC("📋 group-context/ · read-only"):::readonly
    A_T("📂 teams/crimson/ · his team only"):::team
  end
  subgraph dana ["👩‍💼  Dana — Org Lead"]
    direction TB
    D_GC("📋 group-context/"):::group
    D_T("📂 teams/ · clones on demand"):::team
  end

  classDef group fill:#fef3c7,stroke:#f59e0b,stroke-width:2px,color:#78350f,rx:10
  classDef team fill:#ede9fe,stroke:#8b5cf6,stroke-width:2px,color:#3b0764,rx:10
  classDef readonly fill:#f1f5f9,stroke:#94a3b8,stroke-width:2px,color:#475569,rx:10
05 / 09

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"| 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
$ 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
06 / 09

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
Use As-Is
Fill in team.md, never touch the skill
Most teams
Light Tweaks
Add or remove report sections
Some teams
Heavy Rewrite
Completely different report
Rare
07 / 09

CLI Reference

10 commands. Noun-verb convention modeled on gh CLI. Single bash script — dependencies: bash, git, curl.
08 / 09
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

Before & After

Before: Hub-Clone Model
  • Clone entire hub to get started
  • 20+ items in workspace root
  • Manual team tracking
  • Mixed stubs and real repos
  • 4 commands to get a workspace
  • Org-specific — can't scale to other orgs
After: CLI-Assembled Model
  • curl + init — no clone needed
  • Only group-context + your team
  • Dynamic discovery from GitLab
  • Every team is a real GitLab repo
  • 2 commands to get a workspace
  • Any org, same CLI, same schema
team-home Architecture Blueprint — RHOAI Dashboard — August 2026
Avik Kundu — Crimson Team
09 / 09