modular-dev

modular-dev

A Claude Code plugin that tames complex projects by breaking them into small, agent-manageable pieces.

AI coding agents are powerful on small, focused tasks — but they fall apart on large codebases. Context windows overflow, changes ripple unpredictably, and one bad edit in module A breaks modules B through Z. modular-dev solves this by decomposing your project into independent packages that agents develop in isolation, with contract-driven testing. Independent packages are built concurrently — in waves — while each agent stays confined to its own package.

---

How it works

You: "Add user authentication with OAuth support"

modular-dev:
  1. Reads the project dependency graph
  2. Routes to the relevant zone manager → analyzes which packages need changes
  3. Writes edge tests from contract definitions, in parallel, for every package in the wave (before any code exists)
  4. Once all tests are committed, spawns an isolated dev agent per package concurrently (each can't see tests or other packages)
  5. Runs tests → passes → commits by logical unit (one package = one commit)
  6. Moves to the next wave of ready packages → repeats until done

You describe what you want. The plugin handles decomposition, test writing, isolated development, verification, and commits — fully automated, building independent packages in parallel waves.

The problem

When AI agents work on large projects:

• Context overflow: the agent can't hold the whole codebase in memory. It forgets what it read 10 minutes ago.
• Cascading errors: a change in one module breaks three others. The agent patches those, breaking two more.
• No isolation: the agent can read and modify anything, so it creates invisible coupling between components.
• Test gaming: if the agent can see the tests while coding, it writes code that passes tests rather than code that solves the problem.

These aren't model limitations — they're architectural failures. A smarter model makes them worse, not better, because it modifies more code with more confidence.

The solution

Treat your project like a package ecosystem, not a monolith.

project/
├── graph.json                 ← dependency graph (source of truth)
├── contracts/auth-api/        ← interface between auth and api packages
├── packages/auth/             ← independent package (high cohesion)
├── packages/api-gateway/      ← independent package (loose coupling)
├── tests/auth-api.test.*      ← edge tests (invisible to dev agents)
├── overviews/                 ← summaries that replace reading source code
└── shared/                    ← cross-cutting concerns (logging, config)

Each package is developed by an isolated agent that can only see:

• ✅ Its own package directory
• ✅ Contract definitions (read-only)
• ✅ Shared modules (read-only)
• ❌ Other packages
• ❌ Test files
• ❌ Git operations

Hooks enforce these boundaries at the tool level — even if the agent ignores prompt instructions, PreToolUse hooks block forbidden operations.

Architecture

┌──────┐
│ User │
└──┬───┘
   │ task
   ▼
┌──────────────────────────────────────────────┐
│              Bus Agent (main session)         │
│  Wave loop: Analyze → Test ∥ → Dev ∥ → Run ∥ │
└──┬──────────┬──────────┬──────────┬──────────┘
   │ spawn    │ spawn    │ spawn    │ spawn
   ▼          ▼          ▼          ▼
┌────────┐ ┌────────┐ ┌────────┐ ┌────────┐
│  Zone  │ │  Test  │ │  Dev   │ │  Test  │
│Manager │ │Writer  │ │ Agent  │ │Runner  │
└────────┘ └────────┘ └────────┘ └────────┘
 analyzes    writes     codes      runs
 & routes    tests      1 pkg      tests
             first      only

• Bus Agent: the main Claude Code session. Routes messages between subagents. Doesn't understand code — only the dependency graph and overviews.
• Zone Manager: dynamically generated per session. Owns a group of related packages. Analyzes requirements, produces development specs.
• Test Writer: writes comprehensive edge tests from contract definitions before any implementation exists. Applies BVA, equivalence partitioning, state transition testing, and error guessing.
• Dev Agent: implements exactly one package. Isolated via hooks. If the contract is insufficient, it stops and escalates rather than working around it.
• Test Runner: executes edge tests. Cannot modify any file.