GW Maven Plugin 1.2.0-SNAPSHOT API

GW Maven Plugin

Ghostwriter Maven Plugin is an advanced documentation automation tool for Java projects. It automatically scans, analyzes, and assembles project documentation using embedded guidance tags and AI-powered synthesis. The plugin streamlines the creation and maintenance of high-quality, consistent documentation, ensuring best practices and up-to-date information across all modules.

Overview

GW Maven Plugin integrates Machai Ghostwriter into Maven builds so that guided, AI-assisted updates can be performed directly from standard Maven goals. The plugin is designed for repositories that keep instructions close to the files being maintained through embedded @guidance: blocks. During execution, the plugin scans configured directories, gathers guidance instructions, resolves project context, and delegates file processing to the Ghostwriter engine.

The plugin supports both aggregator-style execution and per-module reactor execution. This makes it suitable for single-module documentation projects, multi-module Maven builds, and repository-wide content maintenance workflows that combine source code, documentation, and project site assets.

Primary responsibilities

• Expose Maven goals for guided file processing and interactive act execution.
• Scan project content for embedded @guidance: instructions.
• Pass shared configuration such as model selection, excludes, instructions, and credentials to the processing engine.
• Integrate with Maven session, project, reactor, and settings metadata.
• Provide class-discovery helper tools so Ghostwriter workflows can inspect project classes and dependencies.
• Clean temporary processing artifacts generated during guided workflows.

Build integration model

A typical execution flow is:

1. Resolve the current Maven session, project, and optional reactor context.
2. Load shared plugin configuration, including optional credentials from settings.xml.
3. Determine the scan root, instructions, excludes, and logging options.
4. Construct a GuidanceProcessor or ActProcessor for the requested goal.
5. Register project-aware helper tools when Maven project metadata is available.
6. Scan files for embedded guidance and apply updates through the Ghostwriter engine.

Goals

gw:gw

Aggregator goal for guided file processing. It can run without a local pom.xml and processes modules in reverse order, with sub-modules handled before parent modules.

gw:gw-per-module

Reactor-oriented guided processing goal that executes per module according to standard Maven dependency ordering.

gw:act

Interactive action goal that runs a predefined or user-supplied prompt over scanned files. It can prompt for the action text when one is not supplied through configuration.

gw:act-per-module

Per-module variant of the act goal intended for standard reactor execution, typically acting from the execution-root project context.

gw:clean

Cleanup goal that removes temporary files created during Ghostwriter processing.

Shared configuration concepts

Model selection

Goals can forward a provider/model identifier to the Ghostwriter engine so a specific GenAI backend can be selected.

Scan directory

A configurable scan root determines where files containing @guidance: blocks are searched.

Instructions

Additional instruction sources can be supplied to complement embedded guidance blocks.

Excludes

Exclude patterns allow builds to skip generated folders, dependencies, or other irrelevant paths.

Credentials

Provider credentials can be loaded from Maven settings.xml using a configured server identifier, allowing builds to reuse standard Maven credential management.

Class helper tools

The plugin can register reflection-based helper tools that locate project classes and return structured metadata such as modifiers, members, classpath origins, source paths, and dependency artifact coordinates.

Package structure

org.machanism.machai.gw.maven

This package contains the Maven mojos and shared goal infrastructure. Its central abstraction is the common base class used to collect parameters, resolve configuration, read Maven settings, and coordinate document scanning. Concrete goals build on this infrastructure to support guided scanning, interactive acts, reactor-aware execution, and cleanup.

• AbstractGWMojo centralizes shared configuration and scan execution.
• GWMojo implements aggregator-style guided processing.
• GWPerModuleMojo implements per-module guided processing within the reactor.
• ActMojo provides interactive or configured action execution.
• ActPerModuleMojo adapts act execution to standard reactor processing.
• CleanMojo removes temporary processing artifacts.

org.machanism.machai.gw.maven.tools

This package contains helper types that expose Java class discovery and reflection metadata as function tools for Ghostwriter workflows. It scans a Maven project's classpath and output directories, finds classes by simple-name pattern, and returns structured metadata that can be used during AI-assisted processing.

• ClassFunctionalTools registers function tools such as class lookup and reflective inspection.
• ClassInfoHolder builds project-specific class loaders and stores class origin metadata.

Typical usage

Common command-line invocations include:

• mvn gw:gw
• mvn gw:gw-per-module -Dgw.path=src/site
• mvn gw:act -Dgw.act="Rewrite headings for clarity"
• mvn gw:act-per-module -Dgw.acts=src/site/acts
• mvn gw:clean

Class diagram

The following diagram summarizes the main goals and supporting types in the plugin.

Packages

Package	Description
org.machanism.machai.gw.maven	Maven plugin goals (Mojos) for running Machai Ghostwriter (GWMojo) guided document processing.
org.machanism.machai.gw.maven.tools	Provides helper types that expose Java class discovery and reflection metadata as function tools for the Ghostwriter Maven plugin.