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
│   └── …
├── portable-skills/              # generated Agent Skills entrypoints
│   ├── architect/SKILL.md
│   ├── review-code/SKILL.md
│   └── …
├── cursor-agents/                # generated Cursor Task subagent wrappers
├── config/
│   └── defaults.yaml             # plugin-shipped configuration defaults
├── docs/                         # detail that commands load on demand
├── hooks/
│   ├── hooks.json                # Claude Code hook registrations
│   └── codex-hooks.json          # Codex hook registrations (commit lint only)
├── scripts/                      # hook scripts and deterministic helpers
└── workflows/                    # opt-in Claude Code Workflow engines

Skills lists every entrypoint in commands/, portable-skills/, cursor-agents/, and workflows/, and which ones you invoke yourself.

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 portable-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

Settings resolve from lowest to highest precedence:

  1. Plugin defaults — plugins/synthex/config/defaults.yaml.
  2. User config — ~/.config/synthex/config.yaml (honors $XDG_CONFIG_HOME).
  3. Project config — .synthex/config.yaml, committed.
  4. Project-local config — .synthex/config.local.yaml, gitignored.
  5. Per-command overrides — for example, a command-specific review_loops: block.
  6. Per-invocation parameters — arguments supplied through the harness interface.

A few multi-model review keys break this order on purpose. See the Configuration reference for those and for the full key list.

Hooks

On Claude Code, Synthex registers seven hooks in hooks/hooks.json: an upgrade nudge and a loop-recovery notice on session start, the Stop hook that drives --loop, a commit-lint check and the --auto-decide gate before tool calls, and two agent-team gates (TaskCompleted, TeammateIdle). Each one exits quietly when it has nothing to do. On Codex, hooks/codex-hooks.json registers only the commit-lint hook, against Codex's shell tool. Other harnesses don't run these hooks. See the Hooks reference for what each one does, what it writes, and how to turn it off.

Scripts instead of utility agents

Work that needs no judgment runs as a script rather than a model call. Several small Haiku utility agents were retired this way:

Retired agentReplaced by
plan-linterlint-plan.mjs: the same structural checks on a draft plan, returned as JSON
commit-message-authorThe commit-lint.sh hook. The Tech Lead and Lead Frontend Engineer write commit messages themselves
context-bundle-assemblerassemble-bundle.sh: writes the multi-model review context bundle
audit-artifact-writerwrite-audit.mjs: writes the multi-model review audit file
plan-scribeNothing. The Product Manager edits the plan in place

init/synthex:init also does its setup through a script (init-scaffold.sh: copy the config, create the docs directories, detect the commit convention). The init script, the plan linter, and the audit writer each fall back to doing the same work in prose when the harness has no shell tool or no Node.js.

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, OpenCode, and Hermes use the portable Agent Skills bundle. Cursor gets generated Task subagent wrappers in cursor-agents/.

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