goodreason

GoodReason Agent Topology for Claude Code

A systems-thinking framework that organizes Claude Code custom agents into four specialized roles with strict boundaries and coordinated workflows.

What Is This?

Instead of one AI agent doing everything, GoodReason splits complex work across four subagents — each governing a specific dimension of the problem:

Agent	Dimension	Role	Tools
Strategist	Purpose + Information	Verifies build/test foundations, generates competing hypotheses for diagnostic tasks, flags goal/reality conflicts	Read, Glob, Grep, Bash, SendMessage
Architect	Theory + Structure	Designs structure and interfaces; when hypotheses exist, designs a diagnostic experiment (Phase 0) before a fix	Read, Glob, Grep, SendMessage
Implementer	Action + Integration	Writes code under strict TDD phasing; when stuck, uses the phi-stuck protocol with probe tests instead of grinding	Write, Read, Edit, Bash, Glob, Grep, SendMessage
Evolution	Feedback + Change	Runs tests, verifies the fix works for the right reasons, flags causal-mismatch and unverified-mechanism risks	Bash, Read, Glob, Grep, SendMessage

SendMessage lets the agents talk to each other directly in team mode. It is only active when Claude Code's experimental Agent Teams feature is enabled (CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1); without that flag it is simply inert and the agents work exactly as they always have.

Why Separate Agents?

Single-agent development blurs roles. The agent that writes code also evaluates it, which produces blind spots. GoodReason enforces separation of concerns:

• Strategist cannot write code — only validate goals and gather facts
• Architect cannot write code — only design structure and diagnostic experiments
• Implementer cannot assess quality — only build
• Evolution cannot fix code — only identify what is broken and why

This mirrors real engineering teams where architects don't code and QA doesn't design.

The Workflow Cycle

Strategist ──> Architect ──> Implementer ──> Evolution
    ^                                           │
    └───────────────────────────────────────────┘

1. Strategist assesses the situation (what do we want vs. what exists?)
2. Architect creates a structural plan (how should it be built?)
3. Implementer writes the code under TDD discipline
4. Evolution tests and evaluates (does it work, and for the right reasons?)
5. Feedback flows back to the Strategist for the next iteration

The main agent (Claude Code itself) acts as coordinator: routing information between subagents, pacing the cycle, and preventing the disconnections that arise when a single agent both writes code and judges its own work.

Installation

Primary: install from the Softagram marketplace (recommended)

/plugin marketplace add softagram/claude-plugins-marketplace
/plugin install goodreason@softagram-plugins

Once installed, the plugin loads automatically in every Claude Code session — no per-session flags, no manual file copies. You get:

• Four subagents via /agents: Strategist, Architect, Implementer, Evolution
• Workflow skills: /goodreason:cycle, /goodreason:cycle-review, and /goodreason:cycle-team-experimental
• The GoodReason ontology reference as an on-demand skill

Run the full cycle on any task:

/goodreason:cycle Add rate limiting to the public API

Team mode (/goodreason:cycle-team-experimental) runs the same cycle, but keeps the four agents alive as a named team for its whole duration. They retain context across phases and ask each other direct clarifying questions via SendMessage — instead of being re-spawned fresh each phase — while the coordinator still owns phase transitions and the gates.

⚠️ Requires Claude Code's Agent Teams feature, which is experimental and off by default. Enable it with CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 (Claude Code ≥ 2.1.32) — e.g. { "env": { "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1" } } in ~/.claude/settings.json. Without it, the team tools are absent and the skill falls back to the standard /goodreason:cycle. The mainline /goodreason:cycle and /goodreason:cycle-review need no flags and work everywhere.

Alternative: --plugin-dir (useful for development)

Clone the repo and point Claude Code at it directly. This is the right path when you are modifying the plugin itself, or when you cannot use a marketplace.

git clone https://github.com/softagram/goodreason-agents-setup.git
cd your-project
claude --plugin-dir /path/to/goodreason-agents-setup

You will need to pass --plugin-dir on every session unless you configure it in your Claude Code settings.

Alternative: fork and adapt to your project