Ghostwriter

Ghostwriter is an advanced documentation engine that automatically scans, analyzes, and assembles project documentation using embedded guidance tags and AI-powered synthesis.

Purpose

Ghostwriter is a filesystem-first documentation and content generation tool. It traverses a project directory tree, discovers embedded @guidance: instructions in supported files, composes provider-ready prompts, and applies generated output back to the original files.

Ghostwriter supports all types of project files—including source code, documentation, project site content, and other relevant files.

High-level architecture

Ghostwriter class diagram — High-level class relationships in the Ghostwriter processing pipeline.

The processing pipeline follows a consistent sequence:

Select scan roots and matching rules.
Traverse the filesystem and choose files to process.
Extract guidance blocks using a file-format-aware reviewer.
Compose prompts (optionally using reusable Act templates).
Dispatch requests via org.machanism.machai.ai.provider.Genai and apply results in-place.

Package overview

`org.machanism.machai.gw.processor`

Ghostwriter CLI processing pipeline.

This package contains the Ghostwriter command-line entry point (org.machanism.machai.gw.processor.Ghostwriter) and the processor implementations that scan a project directory, select matching files, extract prompts (either from embedded @guidance: directives or from Act templates), and execute those prompts against a configured org.machanism.machai.ai.provider.Genai provider.

Core types

org.machanism.machai.gw.processor.AbstractFileProcessor - filesystem traversal, module handling, include matching (glob/regex), and exclude filtering.
org.machanism.machai.gw.processor.AIFileProcessor - prompt composition (project metadata + prompt body), GenAI provider setup (including working directory), function-tool loading, and optional request-input logging.
org.machanism.machai.gw.processor.GuidanceProcessor - guidance mode: uses registered org.machanism.machai.gw.reviewer.Reviewer implementations to extract embedded @guidance: directives per file and runs the derived prompt.
org.machanism.machai.gw.processor.ActProcessor - Act mode: loads TOML Act templates (built-in and/or custom), composes an Act prompt, and executes it across matching files.

Processing is filesystem-based only: projects are not built and dependencies are not resolved.

`org.machanism.machai.gw.reviewer`

File-format-aware components that locate embedded @guidance directives in project files and convert them into normalized prompt fragments for Ghostwriter.

The central extension point is the org.machanism.machai.gw.reviewer.Reviewer service-provider interface (SPI). Each Reviewer implementation targets one or more file types, understands the comment/string literal conventions for that format, and produces a formatted fragment suitable for downstream processing.

How reviewers are used

Read a supported file (typically UTF-8) and detect whether it contains an @guidance directive.
Compute a stable project-relative path via org.machanism.machai.project.layout.ProjectLayout#getRelativePath(java.io.File, java.io.File).
Format the final fragment using templates loaded from the document-prompts resource bundle.

Provided reviewers

org.machanism.machai.gw.reviewer.JavaReviewer - Java source (including package-info.java)
org.machanism.machai.gw.reviewer.MarkdownReviewer - Markdown
org.machanism.machai.gw.reviewer.HtmlReviewer - HTML/XML
org.machanism.machai.gw.reviewer.TypeScriptReviewer - TypeScript
org.machanism.machai.gw.reviewer.PythonReviewer - Python
org.machanism.machai.gw.reviewer.PumlReviewer - PlantUML
org.machanism.machai.gw.reviewer.TextReviewer - Plain @guidance.txt files

`org.machanism.machai.gw.tools`

GenAI provider function-tool registration for Ghostwriter-specific operations. This package supplies tool definitions (for example, Act discovery and Act inspection) that can be exposed to the configured provider during prompt execution.

Processing workflow

Select scan targets (directory roots and/or matchers such as glob: and regex:).
Traverse the filesystem and select files using include/exclude rules.
Extract guidance with a format-specific reviewer.
Compose prompts using extracted guidance and optional Act templates.
Dispatch the request to the configured GenAI provider and apply the result.

Typical usage

java -jar gw.jar <scanDir> [options]

The <scanDir> argument may be a project-relative directory (for example, src/main) or a matcher expression supported by java.nio.file.FileSystems#getPathMatcher(String) (for example, glob:**/*.java).

Ghostwriter 1.1.1 API