DOCS · REFERENCE · PLUGIN ARCHITECTURE

Plugin architecture

Synthex is a Claude Code plugin: a directory of markdown and YAML that Claude Code reads at install time. Everything that defines an agent's identity or a command's workflow is plain text, checked into the source repository at

bluminal/lumenai/plugins/synthex

.

Repository layout

The synthex plugin's directory tree:

plugins/synthex/
├── README.md                     # plugin overview
├── agents/                       # one .md file per agent
│   ├── architect.md
│   ├── code-reviewer.md
│   ├── tech-lead.md
│   └── … (15 total)
├── commands/                     # one .md file per slash command
│   ├── init.md
│   ├── next-priority.md
│   ├── write-implementation-plan.md
│   └── … (11 total)
├── config/
│   └── defaults.yaml             # plugin-shipped configuration defaults
├── hooks/                        # session and event hooks (optional)
└── scripts/                      # helper scripts the plugin ships with

Three properties follow:

  • Plain text source-of-truth. Every agent identity, every command workflow is reviewable in git diff. No compiled artifact masks what the plugin actually does.
  • No framework. The plugin doesn't depend on a Synthex-specific runtime. Claude Code reads the markdown directly; the plugin imports nothing of its own at runtime.
  • No code generation. What you read in the repo is what runs.

Agent file shape

Each agent is one markdown file with YAML frontmatter and a system prompt body:

---
model: sonnet
---

# Tech Lead

## Identity

You are a senior Tech Lead orchestrating implementation tasks.
Your scope is one task, in one worktree, at a time.

## Core responsibilities

…

The frontmatter sets the model (opus, sonnet, haiku) and any plugin-level metadata. The body is the system prompt. There is no JSON schema for the prompt itself — the prose is the contract.

When an orchestrating agent (Tech Lead, Product Manager) needs a sub-agent, it invokes Claude Code's Task primitive with the agent's name; Claude Code resolves it to the corresponding file and applies the prompt.

Command file shape

Each command is one markdown file describing parameters, workflow, and sub-agent invocations:

---
model: opus
---

# Next Priority

## Parameters

| Parameter           | Description                                        | Default |
| ------------------- | -------------------------------------------------- | ------- |
| `concurrent_tasks`  | Maximum tasks to execute in parallel               | 3       |

## Workflow

1. Read the implementation plan…
2. Pick the next batch of unblocked tasks…
3. For each task, create a git worktree…
4. Delegate each task to a Tech Lead instance…

…

When you invoke /synthex:<verb>, Claude Code looks up the command's markdown and uses it as the system prompt for the orchestrating agent. The "implementation" is just the prompt itself — a procedure described in clear English rather than executed by a runtime.

Tier system

Agents are tiered by role:

  • Orchestration tier (Tech Lead, Lead Frontend Engineer, Product Manager) — runs Sonnet, coordinates other agents, owns lifecycle hand-offs.
  • Specialist tier (Architect, Code Reviewer, Security Reviewer, Quality Engineer, Design System, Performance Engineer, SRE, Technical Writer, Terraform Reviewer) — runs Sonnet, owns a domain.
  • Research tier (UX Researcher, Metrics Analyst, Retrospective Facilitator) — runs Sonnet, produces inputs to the next planning cycle.

Plus a small set of utility agents (Findings Consolidator, Context Bundle Assembler, Commit Message Author, review-prompter agents) that run Haiku because their job is structural rather than synthetic.

The tier is metadata, not a runtime mechanism — every agent is callable directly. The hierarchy informs which agents naturally invoke which others when an orchestrator delegates.

Configuration resolution

.synthex/config.yaml in the project root overrides plugin defaults. Resolution order:

  1. Plugin defaults — plugins/synthex/config/defaults.yaml shipped with the plugin.
  2. Project overrides — your .synthex/config.yaml.
  3. Per-command overrides — the review_loops: block under a specific command's section.
  4. Per-invocation parameters — args passed to the slash command itself.

See the Configuration reference for the full key list.

How Claude Code consumes the plugin

When you run init/synthex:init or any other Synthex command, Claude Code:

  1. Resolves synthex to the installed plugin directory.
  2. Loads the matching commands/<verb>.md as the system prompt for the orchestrating agent.
  3. Reads .synthex/config.yaml (project) on top of config/defaults.yaml (plugin) to derive the runtime configuration.
  4. Spawns the orchestrating agent with the merged prompt + config in scope.
  5. The agent invokes sub-agents via Claude Code's Task primitive; each sub-agent is resolved to its agents/<name>.md file the same way.

Nothing about the plugin is privileged. You can read the same files Claude Code reads, write your own variants, and ship your own plugin alongside Synthex. See authoring agents and authoring commands.

Versioning

The plugin is versioned at the marketplace level. The marketplace itself is just a Git repository (bluminal/lumenai), so you can pin a project to a specific commit if you need to freeze the agent set against drift. /plugin update synthex pulls the latest revision.

Next