Ghostwriter

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

The application supports source code, documentation, project site content, and other relevant repository files, enabling documentation-oriented and workflow-oriented updates directly from the filesystem.

Purpose

Ghostwriter is a filesystem-oriented documentation and prompt-execution tool for repositories that embed author instructions inside project files. It discovers @guidance directives, gathers project layout metadata, builds repository-aware prompts, and applies generated output back to matching files.

In addition to guidance-driven updates, Ghostwriter supports reusable Act templates that define structured prompt workflows for repeated maintenance, review, and content-generation tasks.

Architecture overview

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

The runtime is organized around cooperating processor, reviewer, and tool packages. Command-line orchestration selects scan targets, traverses the detected project layout, delegates file inspection to format-aware reviewers, composes prompts, and executes them through a configured org.machanism.machai.ai.provider.Genai provider. Optional function tools extend prompt execution with controlled access to project files, command execution, web access, and Act lifecycle operations.

Package overview

`org.machanism.machai.gw.processor`

This package contains the Ghostwriter command-line entry point and the core processing pipeline. It provides filesystem traversal, project layout inspection, prompt preparation, AI provider integration, and execution modes for embedded guidance and Act-based workflows.

org.machanism.machai.gw.processor.AbstractFileProcessor supplies shared traversal, path filtering, exclusion handling, and module-recursion behavior. org.machanism.machai.gw.processor.AIFileProcessor adds provider initialization, request assembly, request logging, and runtime tool integration. Guidance-driven execution is handled by org.machanism.machai.gw.processor.GuidanceProcessor, while org.machanism.machai.gw.processor.ActProcessor resolves and executes TOML-defined Acts and their episodes. Supporting types such as org.machanism.machai.gw.processor.Ghostwriter, org.machanism.machai.gw.processor.Episodes, org.machanism.machai.gw.processor.GWConstants, org.machanism.machai.gw.processor.ActNotFound, and org.machanism.machai.gw.processor.EpisodeNotFoundException provide bootstrap, sequencing, configuration constants, and execution-time error reporting.

`org.machanism.machai.gw.reviewer`

This package defines reviewer components that inspect project artifacts for embedded @guidance directives and convert them into normalized prompt fragments for the Ghostwriter processing pipeline.

The central extension point is org.machanism.machai.gw.reviewer.Reviewer, implemented by file-format-specific reviewers for Java, Markdown, HTML, TypeScript, Python, PlantUML, and dedicated text guidance files. Reviewers interpret syntax appropriate to each file type, resolve stable project-relative paths using detected project layout metadata, and return formatted prompt input only when actionable guidance is present. Special handling includes package-level Java guidance in org.machanism.machai.gw.reviewer.JavaReviewer and directory-scoped guidance file processing in org.machanism.machai.gw.reviewer.TextReviewer.

`org.machanism.machai.gw.tools`

This package supplies host-integrated function tools that can be exposed to the AI provider during prompt execution so workflows can interact with the local environment in controlled ways.

It includes tool registrars and support classes for file-system access, command-line execution, web and REST access, Act management, and project-scoped context variables. The package also contains security checks, bounded output buffering, patch application support, and exception-based control flow used to end tasks, repeat episodes, move between episodes, or terminate execution.

Processing workflow

Select scan targets using directories or path-matcher expressions.
Traverse the project layout across source, test, documentation, and module boundaries.
Inspect files with format-specific reviewers to locate embedded guidance.
Compose prompts from project metadata, extracted instructions, and optional Act templates.
Register tools that expose file, command, web, and Act operations when enabled.
Execute requests through the configured GenAI provider and apply generated results to files.

Usage notes

Ghostwriter operates directly on repository content rather than compiled project models. It is designed for documentation generation, guided maintenance, and structured AI-assisted updates where instructions live next to the files they govern.

A typical invocation starts the CLI entry point and provides a scan directory or matcher expression, for example java -jar gw.jar <scanDir> [options]. Matching targets can be repository-relative paths such as src/main or matcher expressions supported by java.nio.file.FileSystems#getPathMatcher(String).

Ghostwriter 1.1.15-SNAPSHOT API