# repo-architect

repo-architect maps how your repositories are laid out and proposes a cleaner shape: a shared project template plus file sync across repos through GitHub MCP.

- subagent · `type=agent` · Claude Code, Codex, Cursor · ★ 850 repo stars
- Author: ruvnet
- License: not stated · policy=link-only · description only; the file stays with the author
- Source: https://github.com/ruvnet/agentic-flow/tree/HEAD/.claude/agents/github/repo-architect.md
- Updated: 2026-10-26
- Security check: automated, 2026-11-16 (text) — no signs of malicious code found.
- HTML: https://affpapa.org/en/nevibecode/agents/repo-architect

## What it does

The agent inspects repository layout and comes back with a restructuring plan: where packages belong, which files should move into a shared template, what to keep in sync between related repos. It spreads the work across a `claude-flow` swarm with analyst, architect, optimizer and coordinator roles.

Hooks ride on `npx ruv-swarm`. One runs a structure pass before the task starts, one checks edits afterwards, one assembles recommendations at the end, and a notification hook fires separately. So `ruv-swarm` has to resolve through `npx` on the machine running Claude.

On the tool side it has file work (`Bash`, `Read`, `Write`, `Edit`, `Glob`, `WebFetch`, `Task`) plus GitHub MCP calls for creating, forking and searching repositories and pushing files. Those calls only land when the `github` and `claude-flow` MCP servers are connected, otherwise it can touch local files and nothing more.

## Requirements
- Works with: GitHub

## Install

### Claude Code (native platform)

**Manually: put the files in place**
- File: `.claude/agents/repo-architect.md` — For all projects use ~/.claude/agents/. Claude delegates by the description field or an @-mention

### Codex

**Manually: put the files in place**
- File: `.codex/agents/repo-architect.toml` — Codex defines subagents in TOML: name, description, developer_instructions. Move the Markdown text into developer_instructions by hand. For all projects use ~/.codex/agents/

### Cursor

**Manually: put the files in place**
- File: `.cursor/agents/repo-architect.md` — Cursor also reads .claude/agents/

Where a file is given instead of a command, copy the files from the source to that path: https://github.com/ruvnet/agentic-flow/tree/HEAD/.claude/agents/github/repo-architect.md

## When to use it
- align the layout of several repositories to one template
- place packages sensibly before they pile up in the root
- keep CI configs identical across related repos
- spin up a new repository from a ready-made template
- get a written list of structural problems

## Example prompts
- Walk the structure of this repo and tell me what to move so new packages stop landing in the root.
- Build a project template with `.claude/config.json` and `CLAUDE.md`, then push it to a fresh repo using `mcp__github__create_repository`.
- Compare the layout of `claude-code-flow` and `ruv-swarm` and sync the files they share.

## Similar
- [GitHub Analytics MCP — Repo & Trend Research](https://affpapa.org/en/nevibecode/mcp/github-analytics-mcp-repo-trend-research.md) — MCP server · 8233 installs
- [om-verify-in-repo](https://affpapa.org/en/nevibecode/skills/om-verify-in-repo.md) — skill · 3500 installs
- [github-multi-repo](https://affpapa.org/en/nevibecode/skills/github-multi-repo.md) — skill · 1200 installs
- [repo-research-analyst](https://affpapa.org/en/nevibecode/skills/repo-research-analyst.md) — skill · 524 installs
- [github-repo-candidate-quality-gate](https://affpapa.org/en/nevibecode/skills/github-repo-candidate-quality-gate.md) — skill · 254 installs
- [make-repo-contribution](https://affpapa.org/en/nevibecode/skills/make-repo-contribution.md) — skill · 11073 installs

From the same set: [ruvnet/agentic-flow](https://affpapa.org/en/nevibecode/by/ruvnet/agentic-flow.md) — 76 cards

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md
