Fork me on GitHub

GW Maven Plugin

Maven Central

Introduction

GW Maven Plugin is the primary adapter for the Ghostwriter application. It integrates MachAI Ghostwriter’s Guided File Processing approach into Maven builds so that project assets (source code, documentation, project site content, and other scanned files) can be evaluated against embedded @guidance: blocks and updated consistently over time.

The plugin provides Maven goals (Mojos) in org.machanism.machai.gw.maven that delegate to Ghostwriter processors:

  • Guided processing (gw:gw, gw:reactor) using GuidanceProcessor for scanning a directory tree and applying guidance-driven updates.
  • Action processing (gw:act, gw:act-reactor) using ActProcessor for applying an interactive or predefined “act” prompt across a scanned document set.

Credentials can optionally be sourced from Maven settings.xml via -Dgenai.serverId=..., keeping secrets out of source control while still enabling CI-friendly execution.

Overview

The GW Maven Plugin makes Ghostwriter execution repeatable and Maven-native:

  • Run documentation and content automation in local development and CI using standard Maven invocations.
  • Choose between aggregator-style processing (CLI-like module discovery and reverse module order) and reactor ordering (standard Maven dependency build order).
  • Configure scan roots, instructions, exclusions, model/provider selection, and logging through system properties (-D...) or plugin <configuration>.
  • Use guided automation for repeatable, embedded rules, or acts for one-off, prompt-driven rewrites.

In practice, you point the plugin at a scan root (commonly src/site, but any folder can be scanned), it discovers files, applies guidance or actions, and writes updates back to disk.

Key Features

  • Guided File Processing integration via Ghostwriter processors.
  • Guided goals:
    • gw:gw: aggregator goal that can run without a pom.xml and processes modules in reverse order (sub-modules first, then parents), similar to the Ghostwriter CLI.
    • gw:reactor: processes projects using standard Maven reactor dependency ordering.
  • Action goals:
    • gw:act: applies an action prompt; prompts interactively if gw.act is not provided.
    • gw:act-reactor: reactor-friendly variant intended to run in the execution-root project context.
  • Configurable scan root, instructions, and exclusions to focus processing on specific trees (for example documentation sources).
  • Credential integration with Maven settings via -Dgenai.serverId=... (forwards server credentials and optional extra fields to the workflow).
  • Optional input logging via -DlogInputs=true.
  • Cleanup support via gw:clean to remove temporary artifacts created during processing.

Getting Started

Prerequisites

  • Java (see version notes below).
  • Apache Maven.
  • A MachAI Ghostwriter-compatible GenAI provider configured via gw.model.
  • Credentials (optional, but typical) stored in ~/.m2/settings.xml:
<settings>
  <servers>
    <server>
      <id>my-genai</id>
      <username>...</username>
      <password>...</password>
    </server>
  </servers>
</settings>

Use them at runtime:

mvn gw:gw -Dgenai.serverId=my-genai

Java Version

  • Build/toolchain requirement (from pom.xml): Java 8 (maven.compiler.release=8).
  • Functional/runtime requirements: The plugin runs inside Maven, so you must also use a Java runtime compatible with your Maven version and the resolved MachAI Ghostwriter/GenAI provider stack. In practice, this may require a newer runtime even if the plugin itself is compiled for Java 8.

Basic Usage

Run guided processing:

mvn gw:gw

Scan a specific directory:

mvn gw:gw -Dgw.scanDir=src\\site

Run with a specific provider/model:

mvn gw:gw -Dgw.model=openai:gpt-4o-mini -Dgw.scanDir=src\\site

Run a one-off action prompt across your documentation tree:

mvn gw:act -Dgw.act="Rewrite headings for clarity" -Dgw.scanDir=src\\site

Typical Workflow

  1. Add or update project content (commonly documentation under src/site, but any scanned tree is supported).
  2. Embed @guidance: blocks in files where you want repeatable automation.
  3. Run a goal:
    • Use gw:gw for aggregator-style processing (reverse module order, CLI-like behavior).
    • Use gw:reactor for reactor dependency ordering.
    • Use gw:act / gw:act-reactor for targeted prompt-driven rewrites.
  4. Review changes in your VCS diff.
  5. Commit updates to keep documentation and other assets synchronized with code.
  6. (Optional) Clean temporary artifacts:
mvn gw:clean

Configuration

Common configuration parameters (usable as -D... system properties or via <configuration> in your pom.xml):

Parameter Description Default
gw.model Provider/model identifier forwarded to Ghostwriter (example: openai:gpt-4o-mini). (none)
gw.scanDir Scan root directory to process. If not provided, defaults to the execution root directory for gw:gw and typically the module base directory for reactor-style usage. (varies by goal)
gw.instructions Instruction locations consumed by the workflow (for example, file paths or classpath locations). (none)
gw.excludes Exclude patterns/paths to skip while scanning. (none)
genai.serverId settings.xml <server> id used to load GenAI credentials (and optional provider-specific fields) into workflow properties. (none)
logInputs Logs the list of input files passed to the workflow. false
gw.act For gw:act / gw:act-reactor: the action prompt to apply (interactive if omitted for gw:act). (none)
gw.acts For gw:act / gw:act-reactor: directory containing predefined action definitions. (none)

Resources