Agent Mode

Pluxx has two product layers:

Core: deterministic scaffolding, validation, build, install, and sync
Agent: guided semantic refinement driven by Claude Code, Codex, or another coding agent

Pluxx does not need to become its own AI orchestration runtime to solve the hard part of plugin authoring. The right split is:

let Pluxx own the structure, hard rules, and safe write boundaries
let the host agent own the semantic judgment

That matches how people already work. They are inside Claude Code or Codex anyway, so Pluxx should prepare the scaffold and the prompt/context pack that the agent needs to do high-quality refinement.

Why Agent Mode Exists

pluxx init --from-mcp can always produce a valid scaffold from:

MCP transport + auth
serverInfo
tools/list
tool descriptions and input schemas

That is enough to build:

pluxx.config.ts
baseline INSTRUCTIONS.md
baseline skills/*/SKILL.md
generated hooks / scripts
platform bundles

But complex MCPs need more than valid scaffolding. PlayKit is a good example. Raw introspection can discover the tools, but it does not fully recover the product narrative:

setup vs runtime tools
knowledge tools vs API tools
account/usage/admin surfaces
the way the product is actually explained on its site and docs

That is where Agent Mode comes in.

Product Definition

Core Mode

Core Mode stays deterministic and model-free. It owns:

MCP introspection
config generation
baseline skill generation
lint
build
install
sync
file ownership rules

Agent Mode

Agent Mode prepares the semantic context and prompt pack for the host agent. It owns:

MCP summary for the agent
product/workflow context
prompt packs for taxonomy, instructions, and review
explicit write boundaries
acceptance criteria for the refinement pass

It does not own model execution.

User Flow

Flow A: Core only

npx @orchid-labs/pluxx init --from-mcp https://example.com/mcp
npx @orchid-labs/pluxx lint
npx @orchid-labs/pluxx build
npx @orchid-labs/pluxx test

Use this when a deterministic first pass is enough.

Flow B: Core + Agent

npx @orchid-labs/pluxx init --from-mcp https://example.com/mcp
npx @orchid-labs/pluxx agent prepare

Then in Claude Code or Codex:

Use the Pluxx agent context and taxonomy prompt to refine the generated skills.
Only edit Pluxx-managed sections.
Preserve all custom sections.
Run pluxx lint and pluxx test when done.

That is the intended semantic-authoring flow.

Commands

Phase 1 should support:

pluxx autopilot --from-mcp https://example.com/mcp --runner codex --mode quick --yes
pluxx autopilot --from-mcp https://example.com/mcp --runner codex --mode standard --yes --name acme --display-name "Acme" --author "Acme"
pluxx autopilot --from-mcp https://example.com/mcp --runner codex --mode thorough --yes --review
pluxx agent prepare
pluxx agent prompt taxonomy
pluxx agent prompt instructions
pluxx agent prompt review
pluxx agent run taxonomy --runner claude
pluxx agent run taxonomy --runner cursor
pluxx agent run taxonomy --runner codex
pluxx agent run review --runner opencode --attach http://localhost:4096 --no-verify

--attach is only supported for the opencode runner. Autopilot mode defaults:

quick: keep the run near-deterministic unless metadata warnings force a taxonomy cleanup pass
standard: the default; only invoke expensive passes when metadata quality or extra docs/context suggest they will help
thorough: always run taxonomy and instructions, and include review by default

Optional flags:

--docs https://docs.example.com
--website https://example.com
--ingest-provider auto
--context README.md,docs/overview.md
--json
--dry-run

Provider modes:

auto: use Firecrawl when configured and fall back to the local OSS path when not
firecrawl: require Firecrawl-backed scraping
local: force local fetch + extraction

Runner Adapters

Agent Mode is file-first. The runner layer is optional. pluxx agent run does three things:

refreshes .pluxx/agent/context.md and .pluxx/agent/plan.json
refreshes the selected prompt pack (and after a successful taxonomy run, refreshes all prompt packs so saved packs stay aligned with renamed/merged skills)
invokes a host agent in headless mode against those files

Current built-in runners:

claude
cursor
opencode
codex

If you want the entire deterministic + agent flow in one command, use pluxx autopilot. It composes scaffold import, agent refinement, and final verification without introducing a separate authoring engine.

Verification Contract

For edit-oriented runs like taxonomy and instructions, Pluxx verifies the scaffold after the host agent exits by running the normal Pluxx verification flow. For read-only runs like review, Pluxx disables verification automatically and keeps the host runner in read-only/review mode where supported. Deterministic scaffold rewrites (pluxx sync --from-mcp or taxonomy re-renders) invalidate saved .pluxx/agent/* pack files. Regenerate them with pluxx agent prepare/pluxx agent prompt (or run pluxx agent run / pluxx autopilot, which refreshes them automatically).

Generated Files

pluxx agent prepare generates:

.pluxx/
├── mcp.json
├── docs-context.json     # when website/docs inputs are provided
├── sources.json          # when website/docs/context inputs are provided
└── agent/
    ├── context.md
    └── plan.json

If you pass a specific docs page like https://docs.firecrawl.dev/mcp-server, Pluxx uses that page directly and also infers the broader docs root when it can. That gives Agent Mode both the MCP-specific setup page and the higher-level product docs context. When remote sources are present, .pluxx/sources.json now records the requested and resolved ingestion provider so the provenance trail stays inspectable. Prompt packs are generated separately:

.pluxx/
└── agent/
    ├── taxonomy-prompt.md
    ├── instructions-prompt.md
    └── review-prompt.md

Project-owned overrides live outside the generated .pluxx/agent/ directory:

pluxx.agent.md

Use that file for durable Agent Mode customization. The generated prompt packs are disposable. Example:

# Pluxx Agent Overrides

## Context Paths
- docs/product.md
- notes/playbook.md

## Product Hints
This MCP has a clear split between knowledge tools and runtime API tools.

## Setup/Auth Notes
Knowledge tools work immediately. Runtime API tools require secondary auth.

## Grouping Hints
- setup-and-auth: connect, status
- knowledge: ask, compare, catalog

## Taxonomy Guidance
Prefer product-shaped skills over raw tool buckets.
Reject misleading labels that sound like internal implementation details.
Merge tiny singleton/admin-only skills unless they are a real standalone workflow.

## Instructions Guidance
Use product-facing branded language, not raw MCP server/tool identifiers.
Make setup/admin/account/runtime boundaries explicit in shared instructions.

## Review Criteria
Flag any skill grouping that mixes setup/admin tools with runtime workflows.

`context.md`

The semantic handoff for the host agent. Should include:

MCP identity and auth summary
discovered tool inventory
current generated skills and their tool assignments
optional docs/site summary
known caveats from lint/test
the intended output quality bar

`plan.json`

Machine-readable constraints for the agent. Should include:

editable files
editable sections
non-editable files
success criteria
known caveats

`taxonomy-prompt.md`

Prompt for:

grouping tools into real product/workflow skills
merging/splitting/renaming generated skills
identifying setup/admin/account surfaces
avoiding misleading labels and unnecessary singleton skills

`instructions-prompt.md`

Prompt for rewriting the generated block in INSTRUCTIONS.md. It should use branded product wording and avoid raw MCP-internal naming unless technically required.

`review-prompt.md`

Prompt for evaluating whether the scaffold is actually good after refinement.

Write Boundaries

Agent Mode only works if the write contract is explicit. The host agent may edit:

the generated block in INSTRUCTIONS.md
the generated block in each skills/*/SKILL.md
files under .pluxx/agent/

The host agent must not edit unless explicitly requested:

auth wiring in pluxx.config.ts
target platform configuration
user-owned custom sections
generated platform bundles in dist/
pluxx.agent.md

This lets agents do meaningful semantic work without turning the scaffold into an unreviewable mess.

Prompt Contract

The prompt packs should be constrained, not vague. Example taxonomy prompt:

You are refining a Pluxx-generated plugin scaffold for an MCP.

Inputs:
- .pluxx/mcp.json
- .pluxx/agent/context.md
- INSTRUCTIONS.md
- skills/*/SKILL.md

Your job:
1. Infer the MCP's real product surfaces and workflows.
2. Merge, split, or rename generated skills if needed.
3. Rewrite only Pluxx-managed sections.
4. Preserve all custom-note blocks.
5. Do not change auth wiring or platform config.

Success criteria:
- each skill represents a real user workflow or product surface
- skill names are product-shaped and avoid raw MCP tool/server identifiers when possible
- setup/onboarding, account-admin, and runtime workflows are grouped intentionally
- singleton skills are avoided unless they represent a real standalone user workflow
- examples are concrete and realistic
- wording matches the MCP's product narrative

Steering Complex MCPs With `pluxx.agent.md`

For larger MCPs, use project overrides to steer taxonomy and instructions without editing Pluxx internals:

## Grouping Hints: propose durable product-surface buckets (for example onboarding, account-and-usage, runtime-workflows)
## Taxonomy Guidance: call out anti-patterns (misleading labels, one-tool singleton sprawl, setup/admin mixed into runtime)
## Instructions Guidance: force branded language and explicit setup/admin/account/runtime boundaries

This keeps prompt shaping project-owned, durable, and safe across regenerated prompt packs.

PlayKit Example

The deterministic import of PlayKit produced a working scaffold, but the grouping was still mostly lexical. Agent Mode should help move that scaffold toward a more product-shaped taxonomy like:

setup-and-auth
clay-knowledge
clay-workflow-design
clay-table-operations
account-and-usage

That is the type of semantic refinement Agent Mode is designed to unlock.

Why Not Built-in Smart Mode

Built-in Smart Mode sounds appealing, but it creates a larger product than Pluxx needs right now:

provider abstraction
model auth and billing
retries and fallbacks
nondeterministic support burden
prompt/runtime orchestration inside the CLI

Agent Mode avoids that complexity. Pluxx should remain:

deterministic in Core
agent-native in semantic refinement

If a built-in model layer is ever added later, it should reuse the same context pack and write-boundary model that Agent Mode establishes first.

Phase 1 Scope

Phase 1 Agent Mode should ship:

pluxx agent prepare
prompt pack generation
context pack generation
explicit write boundaries
docs links from README / docs

It does not need:

built-in model execution
provider abstraction
prompt marketplace complexity
automatic commit/publish flows

Success Criteria

Agent Mode is successful when:

a user can scaffold from an MCP in Core mode
run pluxx agent prepare
hand the prompt/context pack to Claude Code or Codex
get a better plugin without losing deterministic safety
preserve custom edits across future syncs

Dogfood Plugin

This repo now ships a repo-local Codex plugin plus marketplace metadata for the local plugin catalog. The dogfood/operator skill pack now centers the main Pluxx jobs:

pluxx-import-mcp
pluxx-migrate-plugin
pluxx-validate-scaffold
pluxx-refine-taxonomy
pluxx-rewrite-instructions
pluxx-review-scaffold
pluxx-build-install
pluxx-sync-mcp

Use it to drive the same Core + Agent workflow from inside Codex instead of remembering raw commands.

Start

Build

Learn

Platform Guides

Examples

Reference

Agent mode

Agent Mode

Why Agent Mode Exists

Product Definition

Core Mode

Agent Mode

User Flow

Flow A: Core only

Flow B: Core + Agent

Commands

Runner Adapters

Verification Contract

Generated Files

`context.md`

`plan.json`

`taxonomy-prompt.md`

`instructions-prompt.md`

`review-prompt.md`

Write Boundaries

Prompt Contract

Steering Complex MCPs With `pluxx.agent.md`

PlayKit Example

Why Not Built-in Smart Mode

Phase 1 Scope

Success Criteria

Dogfood Plugin

​Agent Mode

​Why Agent Mode Exists

​Product Definition

​Core Mode

​Agent Mode

​User Flow

​Flow A: Core only

​Flow B: Core + Agent

​Commands

​Runner Adapters

​Verification Contract

​Generated Files

​context.md

​plan.json

​taxonomy-prompt.md

​instructions-prompt.md

​review-prompt.md

​Write Boundaries

​Prompt Contract

​Steering Complex MCPs With pluxx.agent.md

​PlayKit Example

​Why Not Built-in Smart Mode

​Phase 1 Scope

​Success Criteria

​Dogfood Plugin

Agent Mode

Why Agent Mode Exists

Product Definition

Core Mode

Agent Mode

User Flow

Flow A: Core only

Flow B: Core + Agent

Commands

Runner Adapters

Verification Contract

Generated Files

`context.md`

`plan.json`

`taxonomy-prompt.md`

`instructions-prompt.md`

`review-prompt.md`

Write Boundaries

Prompt Contract

Steering Complex MCPs With `pluxx.agent.md`

PlayKit Example

Why Not Built-in Smart Mode

Phase 1 Scope

Success Criteria

Dogfood Plugin