[Bug] 106 agent definitions ship by default — ~300K tokens of context bloat, most agents are non-functional

[roman-rr]

Summary

Ruflo ships 106 agent definition files (1.19MB / ~300K tokens) in .claude/agents/. The majority of these agents reference MCP servers that don't exist in a standard installation, making them dead weight that inflates every conversation's context window.

When you try to use one of these agents (e.g. frontend-design), you get:

Error: Agent type 'frontend-design' not found. Available agents: general-purpose, statusline-setup, Explore, Plan, ...

...followed by a wall of 90+ agent names dumped into the error message and into the system prompt. This list alone costs significant tokens on every single interaction.

The Numbers

Category	Files	Size	Actually functional?
v3/	16	238KB	Partially — references internal v3 architecture
github/	13	186KB	Some work (pr-manager, issue-tracker)
consensus/	7	107KB	References non-existent MCP servers
optimization/	5	95KB	Generic, no project-specific value
swarm/	3	88KB	Partially useful
sparc/	4	70KB	SPARC methodology — niche
core/	5	70KB	Actually useful (coder, reviewer, tester, planner, researcher)
sublinear/	5	55KB	100% non-functional — requires sublinear-time-solver MCP (not installed)
flow-nexus/	9	32KB	100% non-functional — requires flow-nexus MCP (not installed)
hive-mind/	5	25KB	Partially useful with ruflo MCP
payments/	1	5KB	100% non-functional — requires agentic-payments MCP (not installed)
templates/	9	59KB	Template files, rarely used
Others	24	~84KB	Mixed — duplicates, niche specialists

Total: 1,194,421 bytes (~300K tokens) loaded or indexed per session.

Specific Problems

1. Agents reference MCP servers that don't ship with Ruflo

These 15+ agents call tools from MCP servers that are never installed in a standard npx @claude-flow/cli@latest setup:

• flow-nexus/* (9 agents) — call mcp__flow-nexus__* tools. Flow Nexus is a separate SaaS platform. These agents are useless without it.
• sublinear/* (5 agents) — call mcp__sublinear-time-solver__* tools. This MCP server doesn't exist in any standard install.
• payments/agentic-payments — calls mcp__agentic-payments__* tools. Not installed.

These agents will always fail when spawned. They're marketing material, not functional agents.

2. 7 duplicate agent files

Several agents exist twice — once at the category root and once in a nested subdirectory:

analysis/analyze-code-quality.md          ← duplicate
analysis/code-review/analyze-code-quality.md  ← duplicate
architecture/arch-system-design.md
architecture/system-design/arch-system-design.md
development/dev-backend-api.md
development/backend/dev-backend-api.md
devops/ops-cicd-github.md
devops/ci-cd/ops-cicd-github.md
documentation/docs-api-openapi.md
documentation/api-docs/docs-api-openapi.md
specialized/spec-mobile-react-native.md
specialized/mobile/spec-mobile-react-native.md
data/data-ml-model.md
data/ml/data-ml-model.md

3. The agent list bloats every error message and system prompt

When Claude Code lists available agents (on error, or in the system prompt), it dumps all 90+ names. This is pure token waste on every single message in a conversation.

4. Many "agents" are just verbose prompt templates with no differentiation

Agents like trading-predictor (claims to "execute trades before market data physically arrives" via "temporal advantage") and pagerank-analyzer are marketing copy, not useful tooling. A coder agent with a good system prompt can do everything these claim to do.

What's Actually Useful (from real-world usage)

From the 106 agents, roughly 10-15 are genuinely useful for day-to-day development:

• Core: coder, reviewer, tester, planner, researcher
• GitHub: pr-manager, issue-tracker (maybe code-review-swarm)
• Swarm: hierarchical-coordinator
• V3: security-auditor, memory-specialist (if you use AgentDB)
• Misc: sparc-coder, task-orchestrator

Everything else is either non-functional (missing MCP dependencies), duplicated, or a verbose wrapper around a basic prompt that the coder or planner agent could handle.

Proposed Solutions

Option A: Ship a minimal core set (recommended)

Ship only the ~15 agents that work out of the box. Move everything else to an opt-in registry:

ruflo agents install flow-nexus    # only if you have Flow Nexus configured
ruflo agents install sublinear     # only if you have sublinear-time-solver
ruflo agents install github-full   # extended GitHub agents beyond pr-manager

Option B: Lazy loading

Don't register agents in the system prompt until they're first used. Only load the full agent definition when Agent(subagent_type="X") is called.

Option C: At minimum, remove non-functional agents

Delete agents that reference MCP servers not included in the standard install. This alone would remove 15+ agents and ~90KB of dead definitions.

Option D: Deduplication + size audit

1. Remove the 7 duplicate files
2. Trim agent definitions to <2KB each (most are 15-35KB of verbose prompts)
3. Move detailed instructions into the agent's runtime prompt, not the static definition

Environment

• Ruflo v3.5.x (via npx @claude-flow/cli@latest)
• Claude Code (Opus 4.6)
• macOS / Ubuntu 24.04

Impact

Every conversation pays the token tax of 106 agent definitions whether or not you use agents. At ~$0.015/1K input tokens on Opus, that's roughly $4.50 per conversation just for agent definitions that are mostly non-functional. Over a workday of 20 conversations, that's ~$90 in wasted input tokens on agent bloat alone.

[roman-rr]

Update: It's worse — 3 overlapping agent directories + 134 skill definitions

After checking the upstream repo, there are actually three separate directories containing agent/skill definitions, with massive duplication:

Directory inventory

Directory	Entries	Purpose	Overlap
.claude/agents/	33 subdirs + 5 standalone .md files (~106 agent .md files total)	Claude Code agent definitions	Primary source
.agents/skills/	134 entries	Skill definitions (SKILL.md per dir)	~90% overlap with .claude/agents/
agents/	5 YAML files	Minimal agent configs (coder, reviewer, tester, architect, security-architect)	This is the only lean, useful set

The real agents

agents/ has exactly 5 YAML files — these are the actual functional agent definitions:

agents/
├── architect.yaml
├── coder.yaml
├── reviewer.yaml
├── security-architect.yaml
└── tester.yaml

Each is ~10 lines of clean config. This is what a healthy agent registry looks like.

The bloat

Meanwhile, .agents/skills/ has 134 skill definitions that largely duplicate .claude/agents/. Examples of the same agent appearing in multiple places:

Agent	.claude/agents/	.agents/skills/	agents/
coder	core/coder.md (14KB)	agent-coder/SKILL.md (6.5KB)	coder.yaml (10 lines)
reviewer	core/reviewer.md (15KB)	agent-reviewer/SKILL.md (8KB)	reviewer.yaml (10 lines)
trading-predictor	sublinear/trading-predictor.md (11KB)	agent-trading-predictor/SKILL.md (9.8KB)	-
agentic-payments	payments/agentic-payments.md (5KB)	agent-agentic-payments/SKILL.md (5.3KB)	-
pagerank-analyzer	sublinear/pagerank-analyzer.md (11KB)	agent-pagerank-analyzer/SKILL.md (11.4KB)	-

So the coder agent exists in 3 places with 3 different formats and sizes. Non-functional agents like trading-predictor exist in 2 places.

Additional bloat in .agents/skills/ not in .claude/agents/

The skills directory adds even more on top:

• agentdb-advanced (13KB)
• agentdb-learning
• agentdb-memory-patterns
• agentdb-optimization
• agentdb-vector-search
• reasoningbank-agentdb
• reasoningbank-intelligence
• verification-quality
• worker-benchmarks
• worker-integration
• Various v3-* skills duplicating v3 agents

Migration summary reveals intent

.claude/agents/MIGRATION_SUMMARY.md explains this was a migration from commands to agents. But the migration created duplication instead of replacement — old skills weren't removed when new agents were added.

Bottom line

A fresh npx @claude-flow/cli@latest install gets you:

• 5 useful YAML agents in agents/
• 106 verbose markdown agents in .claude/agents/ (~1.2MB)
• 134 skill definitions in .agents/skills/ (~additional ~800KB-1MB estimated)
• Total: ~2MB+ of agent/skill definitions, 90%+ redundant or non-functional

The agents/ directory with its 5 clean YAMLs is the only one that makes sense. Everything else should either be pruned or moved to an opt-in plugin registry.

[ruvnet]

This is a real problem. The numbers are accurate — 106 agent definitions + 134 skill definitions across 3 directories is excessive context bloat, and many reference MCP servers that don't ship with a standard install.

What we agree on

1. flow-nexus/, sublinear/, payments/ agents are non-functional without their respective MCP servers — they shouldn't ship by default
2. Duplicate agents across 3 directories (.claude/agents/, .agents/skills/, agents/) is a migration artifact that was never cleaned up
3. The lean agents/ directory (5 YAML files) is what a healthy agent registry looks like
4. ~300K tokens of agent definitions is too much context for Claude to process usefully

Plan

1. Remove non-functional agents from default distribution: flow-nexus (9), sublinear (5), payments (1) = 15 agents removed
2. Deduplicate — eliminate .agents/skills/ entries that duplicate .claude/agents/
3. Trim remaining agents to essential set: core (5), github (subset), swarm (subset), hive-mind (subset)
4. Move removed agents to an optional plugin or --full init flag for users who want them
5. Audit .agents/skills/ for security risks flagged in Trojan #1509

The agents/ directory with 5 clean YAML files is the right model. The goal is to ship a minimal, functional default set and let users opt into specialized agents.