Ghostwriter

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

Ghostwriter supports all types of project files, including source code, package documentation, Markdown and HTML documentation, project-site files, PlantUML diagrams, scripts, configuration, and standalone guidance files. It can therefore apply a consistent, project-aware workflow across the complete repository rather than only across Java sources.

Purpose

Ghostwriter is a repository-aware documentation and workflow engine for projects that store author instructions next to the files they govern. It discovers @guidance directives, converts them into structured prompts, enriches those prompts with project-layout and runtime metadata, and applies generated results back to the selected project files.

The same processing foundation also supports declarative Act workflows. Acts define reusable TOML prompt templates, defaults, inherited settings, and ordered episodes so common review, maintenance, documentation, and generation tasks can be executed consistently across a project.

Architecture overview

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

The runtime is organized around three cooperating areas: processors coordinate traversal and AI execution, reviewers extract file-format-specific guidance, and tools expose controlled host capabilities to the configured generative AI provider. Command-line orchestration starts from org.machanism.machai.gw.processor.Ghostwriter, detects project layout information, scans directories or path-matcher expressions, delegates document inspection to reviewers, composes provider requests, and optionally registers function tools for file, command, web, Act, guidance, and context operations.

Package overview

`org.machanism.machai.gw.processor`

This package provides the AI-backed processing layer for Ghostwriter workflows. It connects project-layout metadata, prompt configuration, inline source guidance, declarative Act definitions, episode orchestration, provider selection, and function-tool registration into a single workflow for inspecting or updating project files.

AbstractFileProcessor supplies shared traversal, filtering, exclusion, and module-recursion behavior. AIFileProcessor prepares provider requests for files, project roots, folders, or scanned files selected by directory paths, glob: patterns, or regex: patterns. It assembles requests from project context, instructions, prompts, public configuration values, YAML prompt front matter, included prompt fragments, and registered tools.

GuidanceProcessor scans supported files for @guidance: comments, sends extracted mandatory instructions to the provider, preserves guidance markers in their original locations, can apply a default prompt to files without guidance, and records per-file results. ActProcessor loads TOML Act definitions from built-in resources, local folders, direct TOML paths, or HTTP/HTTPS locations, applies defaults and inheritance, binds user prompt values, and executes one or more prompts against the selected scope. Episodes maintains ordered episode prompts, derives names from Markdown headings, and supports selected, repeated, skipped, and jumped episode execution.

`org.machanism.machai.gw.reviewer`

This package contains file-format-specific reviewers that discover embedded @guidance directives and translate matching artifacts into normalized prompt fragments. The central extension point is Reviewer, which receives the project root and candidate file, determines whether actionable guidance is present, and returns a formatted prompt fragment or null.

Included reviewers cover Java source, Markdown, HTML/XML, TypeScript, Python, PlantUML, and standalone text guidance files. Implementations recognize the comment or marker syntax for their target format, read content as UTF-8, and format output using document-prompt templates. Java package documentation receives special handling through JavaReviewer: a guided package-info.java targets the package rather than only a single class. TextReviewer handles standalone @guidance.txt files and treats the containing directory as the contextual target.

`org.machanism.machai.gw.tools`

This package provides host-integrated function tool implementations used by Ghostwriter to expose local file-system, command-line, web, Act-management, guidance-tag, and project-context capabilities to AI providers. Tool registrar classes attach concrete capabilities to provider instances, while companion specification classes describe available tools for capability discovery and documentation.

The tools support reading, writing, patching, and listing project-relative files; executing validated commands with bounded output capture and deny-list checks; retrieving web content and invoking REST APIs; loading, inspecting, and running Acts; processing guidance-tagged files synchronously or asynchronously; and maintaining project-scoped context variables. Supporting classes implement bounded log buffers, command security, unified-diff patch application, and exception-based control signals for ending tasks, repeating episodes, moving between episodes, or terminating execution.

Processing workflow

Select scan targets from repository-relative paths, directories, or matcher expressions.
Traverse the project layout across source, test, documentation, site, and module boundaries.
Inspect candidate files with format-specific reviewers to locate actionable guidance.
Compose provider requests from extracted instructions, project metadata, prompt templates, and runtime process information.
Register controlled tools for file, command, web, Act, guidance, and context operations when enabled.
Execute prompts through the configured GenAI provider and apply generated output to the intended files or workflow results.

Usage notes

Ghostwriter operates directly on repository content rather than requiring a compiled project model. This makes it suitable for documentation generation, guided maintenance, structured AI-assisted updates, and multi-step prompt workflows where instructions are embedded in source, documentation, or configuration files.

A typical packaged invocation starts the command-line entry point and provides one or more scan targets, for example java -jar gw.jar [paths] [options]. Targets can be paths such as src/main, src/main/javadoc, or matcher expressions supported by java.nio.file.FileSystems#getPathMatcher(String), including glob: and regex: forms.

Prompt content may include external fragments with >>> include markers, use public configuration properties such as ${public.projectName} for template substitution, and receive a process information block that identifies the processed file and whether execution is interactive.

Ghostwriter 1.3.3-SNAPSHOT API