> ## Documentation Index
> Fetch the complete documentation index at: https://docs.pluxx.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Agent mode

# 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

```bash theme={null}
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

```bash theme={null}
npx @orchid-labs/pluxx init --from-mcp https://example.com/mcp
npx @orchid-labs/pluxx agent prepare
```

Then in Claude Code or Codex:

```text theme={null}
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:

```bash theme={null}
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:

```bash theme={null}
--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:

1. refreshes `.pluxx/agent/context.md` and `.pluxx/agent/plan.json`
2. refreshes the selected prompt pack (and after a successful taxonomy run, refreshes all prompt packs so saved packs stay aligned with renamed/merged skills)
3. 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:

```text theme={null}
.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:

```text theme={null}
.pluxx/
└── agent/
    ├── taxonomy-prompt.md
    ├── instructions-prompt.md
    └── review-prompt.md
```

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

```text theme={null}
pluxx.agent.md
```

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

Example:

```md theme={null}
# 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:

```text theme={null}
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:

```text theme={null}
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.