Workspace Ecosystem Agents

Ecosystem Context-File Architecture (AGENTS.md)

Bismillah! I'll analyze your organization's repositories and help set up an ecosystem-wide context-file architecture — the cross-tool standard where AGENTS.md is the primary file (read by Claude Code, Pi, and any AGENTS.md-aware agent) and CLAUDE.md is Claude Code's legacy name for the same file.

Hub / satellite model. One ecosystem hub AGENTS.md (usually in your org's main/overview repo) carries org-wide context: mission, repo index, cross-repo standards. Each member repo gets a lightweight satellite AGENTS.md that links to the hub and holds only repo-specific content. An agent landing in any repo can orient itself: the satellite points to the hub, the hub indexes everything. This mirrors the workspace-init-agents hub/satellite pattern at org scale.

This command is always safe to run. It detects first, shows analysis, and asks before any changes.

STEP 0 — Normalize legacy CLAUDE.md (host decoupling)

AGENTS.md is the cross-tool standard; CLAUDE.md is CC's legacy name. If both exist in a repo, it double-loads and drifts. Before and while building the ecosystem, normalize each repo to one file:

• CLAUDE.md exists, no AGENTS.md → git mv CLAUDE.md AGENTS.md, then proceed (treat its content as the seed).
• Both exist → ask the user which to keep; default: merge into AGENTS.md, git rm CLAUDE.md.
• AGENTS.md exists → analyze and build on it.
• Neither exists → create from scratch (Step 4+).

When migrating, rephrase any CC-flavored framing host-neutrally ("guidance to Claude Code" → "guidance for AI agents"). This is the same migration the workspace-init-agents skill performs per-repo; run it across every member repo as you wire the ecosystem.

STEP 1: DETECT (Always runs first — completely safe)

1.1 Get Repository Info

# Get organization from git remote
git remote get-url origin 2>/dev/null

# Get current branch
git branch --show-current

# Check which context file exists and count lines (AGENTS.md is primary; CLAUDE.md is legacy)
ls -la AGENTS.md CLAUDE.md 2>/dev/null
wc -l AGENTS.md 2>/dev/null

1.2 Determine Context-File Type

Read the context file (prefer AGENTS.md; fall back to CLAUDE.md only if that's all a repo has) and check for these markers:

Also flag the legacy state: if only CLAUDE.md exists (no AGENTS.md), recommend the Step 0 migration so the repo joins the cross-tool ecosystem cleanly.

1.3 Scan for Related Repositories

Look for related repos:

• Check README.md for mentions of other repos
• Check the existing context file for repo references
• Look for common local paths (same parent directory)
• Parse organization from git remote URL

For each related repo found, check which context file it has and what type.

STEP 2: SHOW ANALYSIS REPORT

Always show this report before any action:

┌─────────────────────────────────────────────────────────────┐
│ ECOSYSTEM CONTEXT-FILE ANALYSIS                             │
├─────────────────────────────────────────────────────────────┤
│ Organization: [org-name]                                    │
│ Current Repo: [repo-name]                                   │
│ Branch: [branch]                                            │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│ THIS REPOSITORY:                                            │
│   Context file: [AGENTS.md / CLAUDE.md (legacy) / Missing]  │
│   Type: [Ecosystem Hub / Satellite / Standard / None]       │
│   Lines: [N]                                                │
│                                                             │
│ RELATED REPOSITORIES:                                       │
│   [repo-1]: [Hub ✅ / Satellite ✅ / Standard ⚠️ / None ❌]  │
│   [repo-2]: [Hub ✅ / Satellite ✅ / Standard ⚠️ / None ❌]  │
│   ...                                                       │
│                                                             │
├─────────────────────────────────────────────────────────────┤
│ ARCHITECTURE STATUS: [✅ Complete / ⚠️ Partial / ❌ Missing]│
│                                                             │
│ [Details about what exists and what's missing]              │
├─────────────────────────────────────────────────────────────┤
│ RECOMMENDATION:                                             │
│                                                             │
│ [Specific actionable suggestion]                            │
└─────────────────────────────────────────────────────────────┘

STEP 3: ASK USER (Interactive decision)

Based on analysis, ask the user which path to take:

If no context file exists:

Question: "What would you like to create?"
Options:
- Ecosystem Hub (this is the main repo for the org)
- Satellite (this links to a hub elsewhere)
- Nothing (just wanted to check status)

If a Standard context file exists:

Question: "Upgrade to ecosystem architecture?"
Options:
- Upgrade to Hub (add ecosystem sections, keep existing content)
- Convert to Satellite (lightweight, links to hub)
- Keep as-is (no changes)

If an Ecosystem Hub exists:

Question: "Ecosystem Hub exists. What would you like to do?"
Options:
- Update entries (refresh repo info, versions, test counts)
- Nothing (just checking status)

If a Satellite exists:

Question: "Satellite exists. What would you like to do?"
Options:
- Update content (refresh info)
- Nothing (just checking status)

If Architecture is Complete:

Just report: "Architecture is complete. All repos have proper context files."
No action needed.

STEP 4: EXECUTE (Only after user choice)

4.1 Commit Strategy

The context file lives in each repo as a regular file. AGENTS.md is the standard name; if a legacy CLAUDE.md exists, migrate it first (Step 0):

# Migrate legacy name if needed (AGENTS.md is the cross-tool standard)
if [ -f CLAUDE.md ] && [ ! -f AGENTS.md ]; then
  git mv CLAUDE.md AGENTS.md
fi

git add AGENTS.md
git commit -m "docs: update ecosystem context file"
git push

4.2 Creating an Ecosystem Hub

Add these sections at the top of AGENTS.md, preserving existing content below:

<!-- Ecosystem hub context file — org-wide context for AI agents (Claude Code, Pi, any AGENTS.md-aware agent). Host-neutral. -->

# AGENTS.md - [Project] Ecosystem

**Organization:** https://github.com/[org]
**Website:** [url]
**Purpose:** Ecosystem-wide context for AI agents working across all [org] repositories

---

## ECOSYSTEM OVERVIEW

[Brief description]

### Related Repositories

| Repo | Purpose | Tech Stack | Version |
|------|---------|------------|---------|
| `org/repo1` | **Core** - [desc] | [stack] | vX.X.X |
| `org/repo2` | [desc] | [stack] | vX.X.X |

**Organization Mission:** [mission]

---

## CROSS-REPO STANDARDS

### Shared Coding Standards
[formatting, quality gates, git workflow]

### Shared AI Agent Guidelines

**DO:**
- [best practices]

**DON'T:**
- [anti-patterns]

### Licenses
[license info]

---

## REPOSITORY INDEX

### 1. [main-repo] (Core) - **YOU ARE HERE**

**Purpose:** [description]
**Tech Stack:** [tech]
**Key Commands:**
\`\`\`bash
[commands]
\`\`\`
**Key Files:**
- [files]

**Full details:** See "[PROJECT] CORE REPOSITORY" section below

---

### 2. [other-repo]

**Purpose:** [description]
**Tech Stack:** [tech]
**Key Commands:**
\`\`\`bash
[commands]
\`\`\`
**Key Files:**
- [files]

**Context file:** [link to repo's AGENTS.md]

---

## CURRENT FOCUS

See [ROADMAP.md](ROADMAP.md) for detailed tracking.

**Cross-Repo Coordination:**
- [notes]

---

# [PROJECT] CORE REPOSITORY

> **Note:** Sections below are specific to this repository.

[EXISTING CONTENT PRESERVED HERE]

4.3 Creating a Satellite

<!-- Satellite context file — extends the ecosystem hub (link below). Host-neutral; repo-specific only. Do not duplicate hub standards here. -->

# AGENTS.md - [Repo Name]

> **Ecosystem Hub:** See [hub-repo/AGENTS.md](link) for full ecosystem context

**Repository:** https://github.com/[org]/[repo]
**Purpose:** [description]

---

## Quick Reference

**Tech Stack:** [tech]
**Deployment:** [if applicable]

**Key Commands:**
\`\`\`bash
[commands]
\`\`\`

---

## Key Files

| Path | Description |
|------|-------------|
| [path] | [desc] |

---

## Repo-Specific Guidelines

**DO:**
- [guidelines]

**DON'T:**
- [anti-patterns]

---

**Last Updated:** [date]

DISCOVERY HELPERS

When gathering info for a repo:

From package.json / Cargo.toml / pyproject.toml:

• name, version, description
• scripts/commands

From README.md:

• Project purpose
• Related repos

From directory structure:

• Entry points (src/index.ts, main.py, cmd/main.go)
• Key directories

From git:

• Organization name (from remote URL)
• Current branch

KEY PRINCIPLES

1. AGENTS.md is the standard — CLAUDE.md is CC's legacy name; migrate it (git mv CLAUDE.md AGENTS.md) so the file works across all agents, not just CC.
2. Always safe — detect first, ask before write
3. User decides — never assume, always ask
4. Hub = full context — an agent can work anywhere with just the hub
5. Satellite = lightweight — only repo-specific info, links to the hub
6. No status fields — avoid things that need constant updates
7. Simple table — | Repo | Purpose | Tech Stack | Version |
8. Regular files — the context file lives in each repo, committed to git normally

Alhamdulillah! Run this command anytime — it's safe and will guide you through building a clean, cross-tool context-file architecture for your whole organization. InshaAllah!