DOCS · REFERENCE · PLUGIN ARCHITECTURE

Plugin architecture

Synthex began as a Claude Code plugin. It is now a Claude-first Agent Skills distribution: the same command and specialist Markdown drives Claude Code, Codex, Grok, Gemini CLI, OpenCode, and any compatible future harness—without maintaining parallel copies of the prompts.

Repository layout

The Synthex plugin directory has a canonical workflow layer and a generated compatibility layer:

plugins/synthex/
├── .claude-plugin/
│   └── plugin.json               # Claude Code plugin manifest
├── .codex-plugin/
│   └── plugin.json               # Codex plugin manifest
├── .grok-plugin/
│   └── plugin.json               # Grok plugin manifest (shared skills only)
├── agents/                       # canonical specialist definitions
│   ├── architect.md
│   ├── code-reviewer.md
│   └── …
├── commands/                     # canonical workflow definitions
│   ├── init.md
│   ├── next-priority.md
│   └── …
├── skills/                       # generated Agent Skills entrypoints
│   ├── architect/SKILL.md
│   ├── review-code/SKILL.md
│   └── …
├── config/
│   └── defaults.yaml             # plugin-shipped configuration defaults
├── hooks/                        # Claude Code event hooks where applicable
└── scripts/                      # helpers, including skill generation

Three properties matter:

  • One behavioral source of truth. agents/*.md and commands/*.md contain the identities, review criteria, and workflows. They are ordinary Markdown, reviewable in a git diff.
  • Generated entrypoints, not copied prompts. Each skills/*/SKILL.md gives an Agent Skills host a name and discovery metadata, then tells it to load the matching canonical Markdown file. Updating a workflow changes every supported integration.
  • Harnesses own their native features. A manifest, slash-command UI, plugin hook, or sub-agent primitive belongs to the harness that implements it. Synthex adapts the workflow's intent to the closest available mechanism rather than pretending every harness is Claude Code.

Canonical agent and command files

Each specialist is a Markdown file with YAML frontmatter and a 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.

Each command describes parameters, workflow, delegation, and outputs:

---
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. Delegate the work and run the review gates…

For Claude Code, invoking next-priority/synthex:next-priority resolves the command through the native plugin. In Codex and Grok, the generated next-priority skill loads the same file. In Gemini CLI and OpenCode, their skill mechanisms discover the same entrypoint. The surrounding interaction changes; the decision procedure does not.

The Agent Skills adapter

A generated SKILL.md contains no duplicate workflow prose. Its job is deliberately narrow:

  1. Give the harness a stable skill name and description for discovery.
  2. Point to the canonical command or agent Markdown.
  3. Require the host to read that source before acting.
  4. Translate host-specific tools and delegation primitives without changing the workflow's safety constraints or provider-specific behavior.

The Synthex build checks that every manifest entry has an entrypoint and that generated skills have not drifted from their canonical source. This prevents a Claude-only change from silently leaving other harnesses behind.

AGENTS.md and project context

Synthex is a reusable workflow layer, not a replacement for your project instructions. Keep your architecture, coding conventions, test commands, and local guardrails in AGENTS.md (or your harness's equivalent instruction file). A harness that honors those project rules applies them to a Synthex skill just as it would any other agent session; Synthex adds a disciplined delivery workflow on top.

Configuration resolution

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

  1. Plugin defaults — plugins/synthex/config/defaults.yaml.
  2. Project overrides — .synthex/config.yaml.
  3. Per-command overrides — for example, a command-specific review_loops: block.
  4. Per-invocation parameters — arguments supplied through the harness interface.

See the Configuration reference for the full key list.

Native and portable capability boundaries

Claude Code is still Synthex's primary environment. Its native plugin install supplies namespaced slash commands, plugin agents, event hooks, and native looping. Codex and Grok also have native plugin installations, exposing Synthex entries as skills. Gemini CLI and OpenCode use the portable Agent Skills bundle.

The portable layer makes the workflows available; it does not claim that every host exposes every native Claude primitive. For example, native looping and Claude-specific hooks remain available only where the host supports their equivalent. Synthex preserves the workflow's review and safety requirements while the harness supplies its own tools, permissions, and delegation interface.

Versioning

Synthex uses semantic versioning at the marketplace level. Version 1.0 marks the first release where the shared Agent Skills distribution is supported across multiple harnesses. Breaking changes to workflow contracts or support boundaries are called out in the changelog; non-breaking prompt improvements and new specialists remain ordinary releases.

Next