Search by

trk / processwire-boost

trk

AI context bridge and MCP server for ProcessWire CMS/CMF.

Package info

github.com/trk/processwire-boost

pkg:composer/trk/processwire-boost

Fund package maintenance!

Patreon

Statistics

Installs: 53

Dependents: 0

Suggesters: 0

Stars: 5

Open Issues: 0

0.4.0 2026-11-18 13:23 UTC

This package is auto-updated.

Last update: 2026-11-18 13:23:56 UTC


README

PHP 8.3+ ProcessWire 3.x Version 0.3.2 MIT License

ProcessWire Boost

AI context bridge for ProcessWire CMS/CMF.

Boost ensures AI coding agents produce expert-level ProcessWire code by providing structured context: guidelines that encode best practices, task playbooks (skills) that teach specific patterns, a schema map for project awareness, and a JSON-RPC (MCP) server for live system access.

This is not a CLI tool collection — Boost is a knowledge layer. It sits between your ProcessWire project and the AI agent, ensuring every code suggestion, module scaffold, and schema change follows established conventions.

Table of Contents

Why Boost?

AI agents can write PHP — but writing correct ProcessWire code requires deep context:

Without Boost With Boost
Agent guesses API methods, often hallucinating Guidelines provide verified API patterns with version-specific signatures
Agent uses raw SQL or incorrect selectors pw-pages skill teaches operator syntax, sanitization, and performance rules
Agent creates fields/templates manually pw-migrations skill guides the agent through safe, versioned schema changes
Agent has no idea what templates or fields exist map.json provides a complete schema snapshot — no guessing
Agent cannot inspect live data MCP server exposes real-time queries, logs, and module info

Boost turns a general-purpose AI into a ProcessWire specialist.

How It Works

Architecture

Four context layers, each serving a different purpose:

Layer Format Purpose When Used
Guidelines Markdown in agent config Encode rules, conventions, API patterns Every prompt — always-on context
Skills SKILL.md playbooks Teach step-by-step workflows On-demand — agent activates when task matches
Schema Map map.json Project-specific templates, fields, roles Code generation — agent knows what exists
MCP Server JSON-RPC over stdio Live queries, logs, module info Runtime — agent inspects real data

Runtime Flow

Here is a brief outline of how an AI works under the hood at runtime with these layers:

  1. User asks for a task (e.g., "Create a migration to add a blog template").
  2. Agent reads Guidelines (e.g., AGENTS.md) for base framework rules & conventions.
  3. Agent activates relevant Skill (like pw-migrations) providing the specific, step-by-step workflow required.
  4. Agent reads Schema Map (map.json) to learn the existing project templates, roles, and fields.
  5. Agent queries MCP Server (pw_schema_read etc.) for live configurations or logs natively inside the ProcessWire environment.
  6. Agent generates the code, reliably completing the task with full system awareness.

Requirements

Dependency Version
PHP >= 8.3
ProcessWire 3.x
processwire-console ^0.2.2 (peer dependency)

Installation

composer require trk/processwire-boost --dev

Note: processwire-console provides the vendor/bin/wire CLI runner. Boost commands are auto-discovered via Composer extra metadata — no manual registration needed.

Quick Start

1. Run the Installer

# Interactive mode — prompts for features, agents, and modules
php vendor/bin/wire boost:install

# Flag mode — skip prompts
php vendor/bin/wire boost:install \
  --guidelines --skills --mcp \
  --agents="Cursor,Claude Code,Gemini CLI" \
  --modules="ShopCatalog,CustomAnalytics"

2. What Gets Generated

project-root/
├── AGENTS.md                    # Universal guidelines block for AGENTS-based agents
├── CLAUDE.md                    # Claude Code specific guidelines
├── GEMINI.md                    # Gemini CLI specific guidelines
├── .mcp.json                    # Claude Code MCP config
├── .claude/
│   └── skills/                  # Claude Code exported skills
├── .cursor/
│   ├── mcp.json                 # Cursor MCP config
│   ├── rules/                   # Cursor MDC rules (processwire-boost.mdc)
│   └── skills/                  # Cursor exported skills
├── .gemini/
│   └── settings.json            # Gemini CLI MCP config
└── .agents/
    ├── boost.json               # Installation state
    ├── map.json                 # Schema snapshot (templates, fields, roles)
    └── skills/                  # Canonical skill staging area
        ├── pw-pages/SKILL.md
        ├── pw-module-development/SKILL.md
        └── ...

3. Verify

# Check installation state
cat .agents/boost.json

# Verify central skill sync
ls .agents/skills/

# Test MCP server
echo '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' | php vendor/bin/wire boost:mcp

Context Layers

Guidelines

Guidelines are the always-on context layer — they are compiled into a single instruction block and embedded in the agent's primary instruction file (e.g., AGENTS.md, CLAUDE.md).

Every time the agent processes a prompt, it reads these rules. This is where conventions, security patterns, and API usage rules live.

What Gets Compiled

Section Content
Foundation System identity, PHP/PW version binding, installed module roster, skill activation menu
Boost CLI & MCP tool reference, dual MCP integration patterns
PHP Strict typing, constructor promotion, PHPDoc, enums, array shapes
ProcessWire Core API variables ($pages, $fields, $users, $input, $config, $sanitizer)
ProcessWire Development Hook system (addHookBefore/addHookAfter), module types, namespaces
ProcessWire Security Input sanitization, RBAC (hasRole, hasPermission, editable), CSRF tokens
ProcessWire Selectors Query syntax, operators, limit=, indexed field priority, selectorValue()

Source Priority

  1. Core — resources/boost/guidelines/*.md (7 files)
  2. Module — {module}/.agents/guidelines/*.md (third-party modules)
  3. Site Overrides — site/.agents/guidelines/*.md
  4. Module Context Index — {module}/AGENTS.md (indexed for on-demand inspection when present in the module root)

Merge Strategy

File State Behavior
File has <processwire-boost-guidelines> tags Replace content between tags only — your custom instructions are preserved
File exists, no tags Append tags after existing content
File doesn't exist Create from scratch with header

This means your custom instructions in CLAUDE.md or AGENTS.md survive across reinstalls.

Skills (Task Playbooks)

Skills are on-demand context — the agent activates a specific skill when the current task matches its domain. Each skill is a SKILL.md file containing a complete workflow guide.

Unlike guidelines (which are always present), skills are loaded only when relevant. This keeps the context window efficient while providing deep expertise when needed.

Built-in Skills (18)

Skill What It Teaches the Agent
pw-admin-ui Building ProcessWire Admin interfaces, Process modules, and Inputfield UIs
pw-brainstorming Validating architecture decisions before implementation (modules/templates/fields/hooks)
pw-custom-page-classes Building strongly-typed Page subclasses bound to specific templates
pw-docs-architect Writing/maintaining module docs, READMEs, architecture guides, CLI references
pw-expert Correct ProcessWire API usage patterns, console workflows, context-safe access to $page/$pages/$user
pw-maintenance Toggling maintenance mode safely (down/up) and managing downtime configuration
pw-migrations Safe, versioned schema changes and rollbacks (fields/templates/pages)
pw-module-development Unified module playbook (Module, ConfigurableModule, Markup) + references/ for Fieldtype/Inputfield, Process, Textformatter, and FileValidatorModule
pw-pages Selectors + Page lifecycle: find/filter/create/edit/trash/delete, performance patterns
pw-queue Creating/dispatching/interacting with Queue jobs in ProcessWire
pw-scheduling Time-based tasks using cron expressions and scheduling wrappers
pw-security-audit Security audits for modules/hooks/templates: OWASP, sanitization, RBAC, CSRF
pw-seeder Database seeding patterns using file-based seeders
pw-systematic-debugging A disciplined approach to diagnosing bugs and unexpected behavior
pw-test Writing and running Pest PHP and Playwright E2E tests in ProcessWire projects/modules
pw-url-routing URL/Path hooks for REST APIs, virtual pages, and custom endpoints
pw-writing-plans Turning specs into safe implementation plans (ProcessWire-native)
pw-writing-skills Creating and improving Boost skills (formatting, testing requirements, conventions)

Module-Provided Skills

Third-party ProcessWire modules can ship their own Boost skills. When selected during boost:install, these are merged alongside the built-in skills:

Module Skill What It Teaches the Agent
ShopCatalog pw-shop-catalog Product schemas, price selectors, and catalog hook workflows

How Skills Guide Agents

When an agent encounters a task like "create a migration to add a blog template", the pw-migrations skill activates and provides:

  • Correct creation order: Field → Fieldgroup → Template → Page
  • Safe rollback order: Page → Template → Fieldgroup → Field
  • Pre-flight safety checks (e.g., "don't delete a field that's still attached to templates")
  • Working stub selection (--type=create-template)

Without this skill, the agent would guess at the API and likely produce unsafe or incorrect migration code.

Skill Sync Model

ProcessWire Boost v0.3.2 stages canonical skills in .agents/skills/{skillName}/SKILL.md and exports per-agent skill directories when an agent declares a dedicated skillsPath():

  • Canonical skills are always written to .agents/skills/{skillName}/SKILL.md first so the foundation guideline {{ SKILLS_MENU }} is populated on fresh installs.
  • Agents with dedicated skill folders (e.g. .cursor/skills, .claude/skills, .trae/skills, .opencode/skills) receive exported skill directories via exportSkill().
  • Agents like Trae and OpenCode apply custom frontmatter and compatibility metadata during export.

Schema Map

The schema map (map.json) gives agents project-specific awareness without requiring a live database connection.

Generated on every boost:install run, it contains:

Section Content
Templates Names, IDs, and assigned field lists
Fields Names, IDs, fieldtype class names, and labels
Modules Installed modules with titles and versions
Roles Names, IDs, and assigned permissions
Permissions Names, IDs, and titles

This map enables agents to:

  • Generate code that references real template and field names instead of placeholders
  • Avoid creating duplicate fields or templates
  • Understand the permission structure before creating access control logic

Field Schema Extenders (Optional)

Boost supports optional field schema extenders so non-core or complex fieldtypes can append additional metadata.

  • Generic metadata is appended under fields.{name}.extra.
  • The extension key fields is reserved and promoted to top-level fields.{name}.fields for nested field definitions.
  • Built-in repeater extender support covers FieldtypeRepeater and FieldtypeFieldsetPage, adding nested field schema entries (id, type, label) keyed by subfield name.

Discovery paths:

  • site/.agents/schema/field-extenders.php
  • site/modules/*/.agents/schema/field-extenders.php
  • wire/modules/*/.agents/schema/field-extenders.php

Each manifest should return an array of extender class names (or instances) implementing Totoglu\Console\Boost\Schema\FieldSchemaExtender. Extenders run in discovery order; if multiple extenders return the same key, the later value wins.

<?php

declare(strict_types=1);

return [
	\Site\Boost\Schema\RepeaterMatrixSchemaExtender::class,
	// or new \Site\Boost\Schema\FieldsetPageSchemaExtender(),
];

Extender failures are non-fatal: Boost keeps generating the base schema and logs errors to processwire-boost.

MCP Server (Live Access)

The MCP server provides real-time access to the running ProcessWire system via JSON-RPC 2.0 over stdio (initialize, ping, tools/list, tools/call).

Every tool exposes a full JSON Schema (inputSchema) with typed properties and required parameter lists so MCP clients and LLMs can validate arguments accurately.

Available Tools (28)

Category Tools Safety
Schema pw_schema_read, pw_schema_field_create, pw_schema_template_create Read + ⚠️ Write
Query pw_query, pw_execute Read + ⚠️ Guarded
Modules pw_module_list, pw_module_info, pw_module_install, pw_module_uninstall, pw_module_refresh, pw_module_upgrade Read + ⚠️ Write
Access pw_access_user_list, pw_access_user_create, pw_access_user_update, pw_access_user_delete, pw_access_role_create, pw_access_role_grant, pw_access_role_revoke, pw_permission_delete Read + ⚠️ Write
System pw_system_get_logs, pw_system_logs_tail_last, pw_system_logs_clear, pw_system_cache_clear, pw_system_cache_wire_clear Read + ⚠️ Write
Backup pw_system_backup, pw_system_backup_list, pw_system_backup_purge, pw_system_restore ⚠️ Write / Guarded

Environment Guards: High-impact runtime tools are disabled by default:

  • Set PW_MCP_ALLOW_EXECUTE=1 in the MCP server "env" block to enable pw_execute.
  • Set PW_MCP_ALLOW_RESTORE=1 in the MCP server "env" block to enable pw_system_restore.

MCP Config Formats

Boost auto-generates MCP configuration in each agent's native format during boost:install:

JSON — Standard Context (Cursor, Antigravity, Factory, Kiro; Claude Code & Zed use the same format without "cwd"):

{
  "mcpServers": {
    "processwire": {
      "command": "php",
      "args": ["vendor/bin/wire", "boost:mcp"],
      "cwd": "/absolute/path/to/project"
    }
  }
}

JSON — ${workspaceFolder} (Trae):

{
  "mcpServers": {
    "processwire": {
      "command": "php",
      "args": ["${workspaceFolder}/vendor/bin/wire", "boost:mcp"],
      "cwd": "${workspaceFolder}"
    }
  }
}

TOML (Codex, Grok Build):

[mcp_servers.processwire]
command = "php"
args = ["vendor/bin/wire", "boost:mcp"]
cwd = "/absolute/path/to/project"

OpenCode (nested command array):

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "processwire": {
      "type": "local",
      "enabled": true,
      "command": ["php", "vendor/bin/wire", "boost:mcp"],
      "cwd": "/absolute/path/to/project"
    }
  }
}

Agent System

Boost uses a polymorphic Agent class hierarchy. Each agent declares how it wants to receive context:

Method Purpose
guidelinesPath() Where the agent reads its instruction file
skillsPath() Where task playbooks are deployed
mcpPathStrategy() How MCP paths are resolved (Relative, Absolute, WorkspaceFolder)
mcpConfigPath() Where MCP server configuration is written
exportSkill() How to format skills (override for YAML frontmatter, etc.)

Supported Agents

Agent Guidelines Path Skills Path MCP Config Path Mode
Amp AGENTS.md — .amp/settings.json Relative
Antigravity AGENTS.md .agents/skills .agents/mcp_config.json Relative
Claude Code CLAUDE.md .claude/skills .mcp.json Relative
Codex AGENTS.md .agents/skills .codex/config.toml Relative
Cursor .cursor/rules/processwire-boost.mdc .cursor/skills .cursor/mcp.json Relative
Factory Droid AGENTS.md .factory/skills .factory/mcp.json Relative
Gemini CLI GEMINI.md .gemini/skills .gemini/settings.json Absolute
GitHub Copilot .github/copilot-instructions.md .github/skills .vscode/mcp.json Relative
Grok Build AGENTS.md .grok/skills .grok/config.toml Relative
Junie AGENTS.md .junie/skills .junie/mcp/mcp.json Absolute
Kiro AGENTS.md .kiro/skills .kiro/settings/mcp.json Relative
OpenCode AGENTS.md .opencode/skills opencode.json Relative
Pi AGENTS.md .pi/skills — Relative
Trae AGENTS.md .trae/skills .trae/mcp.json WorkspaceFolder
Zed AGENTS.md .zed/skills .zed/settings.json Relative

Auto Path Resolution: Each agent declares its mcpPathStrategy() via the McpPathStrategy enum. No manual configuration needed — paths are resolved automatically.

Detection & Filtering: BoostManager auto-detects existing project and system agent footprints and only offers agents compatible with the selected feature set.

Adding a Custom Agent

<?php

declare(strict_types=1);

namespace Your\Namespace;

use Totoglu\Console\Boost\Install\Agents\Agent;

final class MyAgent extends Agent
{
	public function name(): string
	{
		return 'my_agent';
	}

	public function displayName(): string
	{
		return 'My Agent';
	}

	public function mcpConfigPath(): string
	{
		return '.my-agent/mcp.json';
	}
}

Module Integration

Third-party ProcessWire modules in site/modules/<Module>/ follow a Single-Responsibility Contract so documentation is written once without duplicating content across files:

File / Path Level Reader & Load Timing Single Responsibility
API.md Level 1 (Baseline) php index.php docs & Agent (signature lookup) ProcessWire Core Standard. Public class/method signatures, selectors, and settings dictionary (# ClassName H1).
.agents/skills/pw-<slug>/SKILL.md Level 2 (Recommended) Host-project consumer agent (on-demand) Playbook teaching how to use the module (name: pw-<slug>, description: "Use when ...", <= 500 lines, tab-indented PHP).
AGENTS.md Optional (Contributor) Agent developing the module itself Module internal architecture (src/ layers, internal SQL tables, build/test commands). Begins with YAML frontmatter description: "...".
.agents/guidelines/*.md Exceptional (Default: None) Host-project agent (every prompt) Strictly global project-wide invariants (<= 30 non-empty lines).
.agents/schema/field-extenders.php Conditional pw_schema_read & .agents/map.json Returns concrete FieldSchemaExtender classes for compound Fieldtype modules with nested subfields.

Directory Structure

site/modules/YourModule/
├── API.md                     # Public API reference (ProcessWire core standard)
├── AGENTS.md                  # Optional internal contributor architecture (YAML description:)
└── .agents/
    ├── guidelines/            # Optional <= 30-line global invariants
    │   └── global-rules.md
    ├── schema/                # Optional compound Fieldtype schema extenders
    │   └── field-extenders.php
    └── skills/                # Consumer task playbooks (pw-<slug>)
        └── pw-your-module/
            └── SKILL.md

Discovery & Validation

  1. Boost scans site/modules/ for API.md, AGENTS.md, or .agents/ (wire/modules/ is scanned for .agents/ or AGENTS.md without polluting selection lists with core API.md files).
  2. Module Context Index in compiled guidelines lists separate pointers for Public API signatures (API.md) and Internal architecture (AGENTS.md).
  3. Guidelines from .agents/guidelines/*.md are merged into compiled guidelines, and skills from .agents/skills/pw-*/SKILL.md (including references/*.md) are exported to .agents/skills and configured IDE folders.
  4. Validate compliance at any time via php vendor/bin/wire boost:validate --module=YourModule --strict.

Tip: After installing a new module that provides Boost skills, run php vendor/bin/wire boost:update to sync the new guidelines and skills into your workspace.

Site-Level Overrides

site/.agents/
├── guidelines/    # Project-specific guidelines
├── schema/        # Project-specific field-extenders.php
└── skills/        # Project-specific skills

CLI Commands

boost:install

Manage AI helper setup (ProcessWire Boost). Select features to install/update, deselect to remove.

Usage:

php vendor/bin/wire boost:install [options]

Options:

Option Short Default Description
--guidelines false Install AI Guidelines
--skills false Install Agent Skills
--mcp false Install MCP Server Configuration
--modules -m null Comma-separated modules to install
--agents -a null Comma-separated agents to configure
--json false Output structured JSON

Examples:

# Interactive installation
php vendor/bin/wire boost:install

# Flag-based non-interactive installation
php vendor/bin/wire boost:install --guidelines --skills -a "Cursor,Claude Code" -m "ShopCatalog"

boost:update

Re-sync ProcessWire Boost guidelines & skills from saved configuration.

  • Can discover newly available Boost-aware modules and persist them into .agents/boost.json
  • Can skip central skill sync when only guidelines or MCP config need refreshing

Usage:

php vendor/bin/wire boost:update [options]

Options:

Option Default Description
--discover false Auto-add newly discovered module resources in non-interactive mode
--no-discover false Skip discovering newly available module resources
--ignore-skills false Skip updating .agents/skills during the update run
--json false Output structured JSON

Examples:

# Update resources from .agents/boost.json
php vendor/bin/wire boost:update

# Skip skill re-sync
php vendor/bin/wire boost:update --ignore-skills

# Update without prompting for newly discovered modules
php vendor/bin/wire boost:update --no-discover

# Non-interactive discovery: persist newly discovered modules automatically
php vendor/bin/wire boost:update --discover

boost:validate

Validate module (site/modules/*) and project (site/.agents/) Boost resources against the canonical contract (API.md H1 headings, AGENTS.md frontmatter description:, pw-* skill naming & "Use when ..." triggers, <= 500-line skill budget, <= 30-line guideline budget, tab-indented PHP code blocks, symlink rejection, Trojan Source Unicode checks, and FieldSchemaExtender manifests).

Usage:

php vendor/bin/wire boost:validate [options]

Options:

Option Short Default Description
--module -m null Validate only a specific module in site/modules/ (or site-overrides)
--strict false Promote best-practice and context-budget warnings to errors
--json false Output structured JSON

Examples:

# Validate all Boost-aware modules and site overrides
php vendor/bin/wire boost:validate

# Validate a single module strictly in CI
php vendor/bin/wire boost:validate --module=YourModule --strict --json

boost:mcp

Start the ProcessWire MCP server (JSON-RPC over stdio).

Usage:

php vendor/bin/wire boost:mcp

Examples:

# Start the MCP server (Typically invoked by AI agents, not manually)
php vendor/bin/wire boost:mcp

boost:add-skill

Add skills from a remote GitHub repository.

  • Remote repositories must expose skills as SKILL.md.
  • A local heuristic audit runs before installation unless --skip-audit is passed.
  • Successful installs trigger boost:update automatically unless --skip-update is passed.

Usage:

php vendor/bin/wire boost:add-skill [options] [repo]

Arguments:

Argument Required Description
repo No GitHub repository (owner/repo or full URL)

Options:

Option Short Default Description
--list -l false List available skills
--all -a false Install all skills
--skill -s null Specific skills to install (can be used multiple times)
--force -f false Overwrite existing skills
--skip-audit false Skip heuristic audit before installing remote skills
--skip-update false Skip automatic boost:update after installing skills
--json false Output structured JSON

Examples:

# Interactive selection
php vendor/bin/wire boost:add-skill owner/repo

# List available skills from a repo
php vendor/bin/wire boost:add-skill owner/repo --list

# Install specific skills
php vendor/bin/wire boost:add-skill owner/repo -s "skill-1" -s "skill-2"

# Install skills without re-syncing Boost resources
php vendor/bin/wire boost:add-skill owner/repo --skip-update

# Install skills without heuristic audit
php vendor/bin/wire boost:add-skill owner/repo --skip-audit

Configuration

boost.json

The installer stores its state in .agents/boost.json:

{
  "version": "0.3.2",
  "guidelines": true,
  "skills": true,
  "mcp": true,
  "modules": ["ShopCatalog", "CustomAnalytics"],
  "agents": ["cursor", "claude_code", "gemini"],
  "generated_at": "2026-04-08 12:00:00"
}

This file enables incremental updates — rerunning boost:install preserves your selections as defaults.

Troubleshooting

Skills Not Appearing

# Verify central sync
ls -la .agents/skills/pw-pages/SKILL.md

# Reinstall
php vendor/bin/wire boost:install --skills --agents="Cursor"

MCP Server Not Working

# Test manually
echo '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' | php vendor/bin/wire boost:mcp

# Check config path
cat .cursor/mcp.json     # Cursor
cat .mcp.json             # Claude Code
cat .junie/mcp/mcp.json   # Junie (absolute paths)

Guidelines Not Updating

The merge strategy preserves custom content. To force regeneration:

rm AGENTS.md CLAUDE.md GEMINI.md
php vendor/bin/wire boost:install --guidelines --agents="Cursor,Claude Code"

ProcessWire Core Not Found

ls wire/core/
php vendor/bin/wire list

Language Policy

All code, documentation, comments, and variable names must be written in English.

Contributing

  1. Open an issue describing the change
  2. Follow code standards (declare(strict_types=1);, tab indentation, curly braces on all control structures, explicit types)
  3. Run static analysis (vendor/bin/phpstan analyse) and unit tests (vendor/bin/phpunit)
  4. Test generated guidelines, skills, and MCP configuration with at least two agents

License

MIT