Multi-Repository Support - Cross-repo workflows

[circus-chimp]

Support working across multiple repositories:

• Repo switcher in sidebar
• Per-repo branch/commit tracking
• Cross-repo diffs
• Cross-repo PR support

[circus-chimp]

👋 I'm starting triage on this multi-repository support feature. I'll assess the requirements and hand off to a specialized team for implementation planning and development.

[circus-chimp]

✅ Enhancement label added. Architecture team is now designing the implementation plan for this multi-repo feature.

[circus-chimp]

Architectural Design: Multi-Repository Support

After a thorough analysis of the codebase, here's the architectural plan for multi-repository support. The design is phased to deliver incremental value while building toward the full feature set.

---

Current State Analysis

What exists today:

• Repos are implicitly encoded in GitHub topic keys (github.{owner}.{repo}.{type}.{number}) in the topic_subscriptions table
• The dashboard is chimp-centric: Home → Chimps list → Chimp activity
• The NATS subject hierarchy naturally groups by repo: events.github.{owner}.{repo}.*
• Chimps clone repos via clone-repo/gh-clone-repo commands, but git state is local to the pod and never reported back

What doesn't exist:

• No first-class repository entity
• No git state tracking (branches, commits)
• No repo-scoped views in the dashboard
• No concept of related/grouped PRs across repos
• No sidebar navigation

---

Architecture Decision Records

ADR-1: Repo Discovery — Derive from topics, don't add a table (Phase 1)

Repos can be extracted from topic_subscriptions by parsing GitHub topic keys. This avoids a new table, a migration, and a sync problem. A repositories table can be added later if we need to store repo metadata (description, default branch, settings).

ADR-2: Git State Tracking — New protocol output + Redis storage (Phase 2)

Branch/commit tracking requires chimps to actively report their git state. This is runtime state that changes frequently, making Redis the right store. Key pattern: chimp:{chimpId}:git:{owner}/{repo} → {branch, commitSha, commitMessage, clean, updatedAt}.

ADR-3: Cross-Repo Diffs — GitHub API-based, dashboard-aggregated (Phase 3)

Rather than chimps reporting diffs, the dashboard fetches them from GitHub using the installation ID already stored in event contexts. This uses GitHub as the source of truth and keeps chimps lightweight.

ADR-4: Cross-Repo PR Groups — Shared group ID via chimp handoff lineage (Phase 4)

When chimps hand off work across repos via chimp_request, the spawning chimp creates a work group. Child chimps inherit the group ID. The dashboard aggregates PRs by group.

---

Phase 1: Repo-Centric Dashboard Views

Scope: Dashboard + shared package. No protocol changes.

This phase reorganizes the dashboard around repos using data that already exists in topic subscriptions.

1a. Backend — Repo aggregation service & endpoints

New method on TopicRegistry:

async listRepositories(): Promise<RepoSummary[]>
// Queries topic_subscriptions, parses github topic keys,
// returns distinct {owner, repo} with counts of PRs, issues, active chimps

New type in shared/standards/topic.ts:

interface RepoSummary {
  owner: string;
  repo: string;
  prCount: number;
  issueCount: number;
  activeChimpIds: string[];
}

New dashboard endpoints:

Endpoint	Returns
GET /api/repos	List of repos with summary stats
GET /api/repos/:owner/:repo	Repo detail: all topics, chimps, activity counts
GET /api/repos/:owner/:repo/topics	All topics (PRs/issues) for this repo
GET /api/repos/:owner/:repo/chimps	Chimps working on this repo

1b. Frontend — Sidebar layout & repo views

Layout restructure:

• Replace the current top-nav-only layout with a sidebar + content layout
• Sidebar contains: repo list (grouped by owner), quick-access to Chimps and Profiles
• Repos are fetched from /api/repos on mount, updated via SSE

New routes:

Route	Page
/repos	All repos grid view
/repos/:owner/:repo	Repo detail: PRs/issues cards with chimp assignments
/repos/:owner/:repo/pr/:number	Filtered chimp activity for a specific PR

Sidebar component:

Sidebar
├── 🎪 Circus (home link)
├── Repositories
│   ├── tonyd33/circus (3 PRs, 1 issue)
│   ├── tonyd33/other-repo (1 PR)
│   └── ...
├── All Chimps
└── Profiles

1c. Files to create/modify

File	Change
shared/src/standards/topic.ts	Add RepoSummary type
shared/src/components/topic-registry.ts	Add listRepositories(), listForRepo(owner, repo)
dashboard/src/App.tsx	Restructure with sidebar layout
dashboard/src/components/Sidebar.tsx	New — sidebar with repo list
dashboard/src/pages/RepoList.tsx	New — all repos grid
dashboard/src/pages/RepoDetail.tsx	New — repo detail with PR/issue cards
dashboard/src/routes/repos.ts	New — repo API routes
dashboard/src/services/chimp-service.ts	Add repo-scoped queries
dashboard/src/hooks/useRepos.ts	New — repo list hook (SSE or polling)

---

Phase 2: Per-Repo Branch/Commit Tracking

Scope: Protocol extension + chimp changes + dashboard.

This phase adds git state awareness to the system.

2a. Protocol extension

New output message type in protocol.ts:

// Chimp reports its git state for a repo
{
  type: "git-state-report",
  owner: string,
  repo: string,
  branch: string,
  commitSha: string,
  commitMessage: string,
  clean: boolean,    // working tree clean?
  aheadBy: number,   // commits ahead of remote
}

New meta event type:

// Broadcast when git state changes
{
  type: "git-state",
  chimpId: string,
  owner: string,
  repo: string,
  branch: string,
  commitSha: string,
  timestamp: string,
}

2b. Storage

Redis hash per chimp per repo:

• Key: chimp:{chimpId}:git:{owner}.{repo}
• Fields: branch, commitSha, commitMessage, clean, aheadBy, updatedAt

Why Redis, not Postgres: This is ephemeral runtime state tied to pod lifecycle. When a chimp stops, its git state becomes stale. Redis TTL or cleanup-on-stop is natural.

2c. Chimp-side reporting

• After clone-repo / gh-clone-repo commands complete: emit initial git state
• After any agent tool use that modifies files (detected via git status): emit updated state
• Optionally: periodic heartbeat with git state (every 60s while running)

2d. Dashboard integration

Repo detail page additions:

• Branch badges on each chimp card
• Commit timeline showing recent commits per chimp per repo
• "Dirty" indicator when working tree has uncommitted changes

New API endpoint:

• GET /api/repos/:owner/:repo/git-state — all chimps' git states for a repo

---

Phase 3: Cross-Repo Diffs

Scope: Dashboard service + new UI component.

3a. Diff fetching service

New dashboard service: DiffService

• Fetches PR diffs from GitHub API using installation tokens
• Caches diffs in Redis with TTL (diffs change infrequently)
• Supports fetching diffs for multiple PRs and merging into a unified view

Token management:

• Event contexts already carry installationId
• Dashboard needs a GitHub App private key to mint installation tokens
• Add GITHUB_APP_ID and GITHUB_PRIVATE_KEY to dashboard config

3b. Unified diff viewer

New component: CrossRepoDiff

• File tree grouped by repo
• Side-by-side or unified diff view
• Syntax highlighting
• Collapsible file sections

New routes:

Route	Page
/repos/:owner/:repo/diff	Aggregated diff of all open PRs in repo
/diff?repos=owner1/repo1,owner2/repo2	Cross-repo diff view

---

Phase 4: Cross-Repo PR Support

Scope: Protocol + DB + ringmaster + dashboard.

This is the most architecturally significant phase.

4a. Work Groups

New DB table:

CREATE TABLE work_groups (
  group_id TEXT PRIMARY KEY,
  name TEXT,
  created_by TEXT NOT NULL,  -- chimpId that created the group
  created_at TIMESTAMP DEFAULT NOW()
);

CREATE TABLE work_group_members (
  group_id TEXT REFERENCES work_groups(group_id),
  chimp_id TEXT NOT NULL,
  owner TEXT NOT NULL,
  repo TEXT NOT NULL,
  pr_number INTEGER,         -- NULL until PR is created
  role TEXT DEFAULT 'member', -- 'lead' | 'member'
  PRIMARY KEY (group_id, chimp_id)
);

4b. Protocol additions

// New output: chimp declares a work group
{ type: "create-work-group", groupName: string }

// New output: chimp links a PR to its group
{ type: "link-pr-to-group", owner: string, repo: string, prNumber: number }

// Extended chimp_request: include group ID for child chimps
{ type: "chimp-request", ..., workGroupId?: string }

4c. Dashboard — Group view

New route: /groups/:groupId

Shows:

• All repos involved in the group
• PR status for each repo (open/merged/checks passing)
• Combined diff across all repos
• Aggregate review status
• Bulk actions: "Merge all", "Request review on all"

---

Implementation Priority & Dependencies

Phase 1 (Repo Views)          ← No dependencies, start here
  └── Phase 2 (Git State)     ← Depends on Phase 1 for UI
        └── Phase 3 (Diffs)   ← Depends on Phase 2 for state
        └── Phase 4 (Groups)  ← Depends on Phase 2, independent of Phase 3

Estimated scope:

• Phase 1: ~15 files changed/created, dashboard + shared only
• Phase 2: ~20 files, touches chimp package + protocol
• Phase 3: ~10 files, dashboard + new GitHub API integration
• Phase 4: ~25 files, touches all packages + DB migration

Risks & Trade-offs

Decision	Trade-off	Mitigation
Derive repos from topics (no table)	Can't track repos with no active topics	Add explicit registration in Phase 2 if needed
Git state in Redis (not Postgres)	Lost on Redis restart	Chimps re-report on reconnect; state is ephemeral anyway
GitHub API for diffs (not chimp-reported)	Requires GitHub App credentials in dashboard	Already have installationId in contexts; just need token minting
Work groups via DB table	Extra table to manage	Clean lifecycle: group deleted when all PRs merged/closed

---

Recommendation: Start with Phase 1 immediately — it delivers the most visible value (repo switcher, repo-scoped views) with the least architectural risk (no protocol changes, no new tables, dashboard-only). I can hand this off to a worker profile with a clear implementation plan once the design is approved.