Fork me on GitHub

GW Maven Plugin

Maven Central bindex

Introduction

GW Maven Plugin is the primary Maven adapter for the Ghostwriter application. It brings Machai Ghostwriter automation into Maven-based projects so teams can scan, analyze, and update project assets using embedded guidance comments and explicit act prompts.

The plugin is built around Guided File Processing, where instructions live close to the files they govern. Ghostwriter works with all types of project files, including source code, documentation, site content, configuration, generated metadata, and other relevant artifacts. In a Maven project, this plugin supplies project layout awareness, reactor/module traversal, Maven settings integration, class-introspection tools, and convenient goals for both guidance-tag processing and user-directed act execution.

The implementation provides two main goals:

  • gw:gw scans project files for guidance comments and processes matching content with Ghostwriter.
  • gw:act runs a named act or a user prompt across selected project content. For an act with additional prompt text, use a value such as -Dgw.act="review Focus on public APIs"; when supplying only a user prompt instead of an act name, start the prompt with >, for example -Dgw.act=">Add missing Javadocs".

Both goals can run without a pom.xml, are safe for threaded execution, and coordinate multi-module traversal through Ghostwriter. When Maven parallel execution is enabled, module processing is handled by gw rather than by the Maven reactor, with sub-modules processed before parent modules.

Overview

GW Maven Plugin enhances project workflows by making documentation and maintenance automation repeatable from standard Maven commands. It resolves configuration from Maven parameters and settings, initializes Ghostwriter processors, supplies Maven project context, and registers helper tools for class-level project analysis when a Maven project is available.

The plugin is especially useful for keeping documentation synchronized with implementation details, applying consistent review or generation rules across modules, and automating edits requested through guidance tags. Because it operates on the full project tree, teams can use it for source code, tests, documentation, site pages, configuration, and other project assets.

Project structure overview

The project structure centers on a Maven plugin layer that adapts Maven execution context to Ghostwriter processors. Shared base behavior resolves configuration, credentials, project roots, scan paths, exclusions, and class-analysis tooling. Goal-specific implementations then either process guidance comments found in project files or execute an act prompt against selected content. Supporting tooling exposes project-class information to the AI workflow so generated changes can be informed by the current codebase.

Key Features

  • Maven-native goals for guidance-tag processing and act-driven Ghostwriter automation.
  • Works with source code, documentation, site content, configuration, and other project files.
  • Multi-module processing with sub-modules handled before parent modules.
  • Parallel execution support through Maven, for example mvn -T 4 gw:gw or mvn -T 4 gw:act.
  • Optional execution without a pom.xml for non-standard or lightweight workspaces.
  • Maven settings integration for AI provider credentials via a configurable server id.
  • Configurable scan paths, exclusions, model selection, and additional instructions.
  • Interactive prompting for gw:act when an act prompt is not supplied.
  • Class-introspection tools registered during Maven project execution to improve context-aware processing.
  • Usage statistics lifecycle hooks around processing execution.

Getting Started

Prerequisites

  • Apache Maven with access to the project where Ghostwriter processing should run.
  • Java runtime compatible with the plugin and the Maven build.
  • Network access to the configured AI provider, when the selected provider requires remote API calls.
  • AI provider credentials configured through environment variables, Maven settings, or provider-specific configuration supported by Ghostwriter.
  • Optional Maven settings.xml server entry when using -Dgenai.serverId=... to resolve credentials.
  • Project files containing @guidance: comments for gw:gw, or an act prompt/act definition for gw:act.

Java Version

The build configuration defines <maven.compiler.release>8</maven.compiler.release>, so the plugin source is compiled for Java 8 bytecode compatibility. Actual functional requirements may differ depending on the Maven runtime, Ghostwriter dependency, AI provider client, and any project-specific tooling invoked during processing; verify the runtime requirements of the complete toolchain used in your environment.

Basic Usage

Run guidance-tag processing over the current Maven project:

mvn org.machanism.machai:gw-maven-plugin:gw

Run a user prompt against a specific path:

mvn org.machanism.machai:gw-maven-plugin:act -Dgw.act=">Add missing Javadocs" -Dgw.path=src/main/java

Run a predefined act with additional prompt text:

mvn org.machanism.machai:gw-maven-plugin:act -Dgw.act="review Focus on public APIs" -Dgw.path=src/main/java

Use Maven parallel execution for larger multi-module projects:

mvn -T 4 org.machanism.machai:gw-maven-plugin:gw

Typical Workflow

  1. Add or update @guidance: comments near the project content that needs automated maintenance.
  2. Configure AI provider credentials using the supported Ghostwriter configuration method or a Maven settings.xml server entry.
  3. Choose the appropriate goal: gw:gw for embedded guidance comments or gw:act for a named act/free-form prompt.
  4. Limit scope when needed with -Dgw.path=... and exclusions.
  5. Run the Maven command, optionally with -T for parallel execution.
  6. Review generated changes carefully, run project tests and documentation builds, then commit accepted updates.
  7. Reuse predefined acts by setting -Dgw.acts=... and passing the act name through -Dgw.act=....

Configuration

Parameter Description Default value
gw.model Provider/model identifier used by Ghostwriter. Provider configuration default
gw.path File, directory, glob, or supported path expression to scan. Execution root or base directory
gw.instructions Additional instructions or instruction locations supplied to processing. Not set
gw.excludes Comma-separated paths or patterns to skip during scanning. Not set
gw.act Act name plus optional prompt text, or direct user prompt prefixed with > for gw:act. Prompted interactively or read from configuration
gw.acts Directory or path containing predefined act definitions for gw:act. Ghostwriter default act lookup location
gw.interactive Enables or disables interactive prompting when act configuration is incomplete. Processor default
genai.serverId Maven settings.xml server id used to resolve AI provider username, password, and custom configuration. Not set
basedir Maven module base directory injected by Maven. ${basedir}
project Current Maven project injected by Maven when a project is present. ${project}
session Current Maven session injected by Maven. ${session}
settings Maven settings used to resolve configured server credentials. ${settings}
reactorProjects Reactor project list injected by Maven for multi-module builds. ${reactorProjects}

Debug Logging

The plugin uses SLF4J simple logger configuration conventions. Enable debug or trace logging for a specific component by setting a fully qualified class name level:

mvn gw:gw -Dorg.slf4j.simpleLogger.log.org.machanism.machai.gw.maven.GWMojo=DEBUG

For act processing diagnostics:

mvn gw:act -Dgw.act=review -Dorg.slf4j.simpleLogger.log.org.machanism.machai.gw.maven.ActMojo=DEBUG

Resources