Package org.machanism.machai.gw.processor

package org.machanism.machai.gw.processor

Ghostwriter processors and command-line orchestration.

This package contains the filesystem-oriented execution pipeline used by the Ghostwriter CLI. It provides the command-line bootstrap, common project traversal support, AI-backed processors for @guidance: and act-driven workflows, and supporting types for episode sequencing, constants, and runtime exceptions.

Processing in this package is based on ProjectLayout metadata. Implementations inspect the current project directory, discover source, test, documentation, and module structure from the detected layout, select matching files or folders, and prepare prompts for a configured Genai provider. The package works directly against the filesystem and project-layout metadata rather than compiling code or resolving dependencies.

Primary processor types

• AbstractFileProcessor defines shared traversal, path filtering, exclusion handling, and module-recursion behavior for concrete processors.
• AIFileProcessor adds prompt preparation, provider initialization, request logging, interactive execution hooks, and function-tool integration.
• GuidanceProcessor reads reviewer-supported files, extracts embedded @guidance: directives, and submits the resulting work to the AI provider.
• ActProcessor loads TOML-defined acts, resolves inheritance and external act locations, and executes prompt episodes against matching files or directories.

Supporting types

• Ghostwriter is the CLI entry point that parses arguments, loads configuration, selects the processing mode, and starts scans.
• Episodes manages ordered or explicitly selected act episodes, including repeat and move-to-episode control flow.
• GWConstants centralizes property names and other constants shared across the processing pipeline.
• ActNotFound and EpisodeNotFoundException report invalid act or episode lookups during execution.

Typical usage

A Ghostwriter invocation constructs either a GuidanceProcessor or an ActProcessor, applies runtime settings such as model selection, instructions, excludes, interactive mode, and scan targets, and then scans one or more project-relative paths or path patterns. Matching files are processed individually, while project-level context is injected into prompts so downstream AI providers can make repository-aware decisions.

Class	Description
AbstractFileProcessor	Base implementation for processors that traverse a project directory and perform work on files and folders.
ActNotFound	Exception thrown when a requested act definition cannot be found.
ActProcessor	Processor that runs Ghostwriter in "Act" mode.
AIFileProcessor	File processor implementation that prepares project context and prompts for a configured AI provider and optionally supports interactive execution.
EpisodeNotFoundException	Exception thrown when an episode cannot be resolved by name.
Episodes	Maintains ordered act episodes and provides execution helpers for normal, selected, repeated, and redirected episode flow.
Ghostwriter	Command-line entry point for the Ghostwriter application.
GuidanceProcessor	Scans a project tree, extracts per-file @guidance directives through Reviewers, and dispatches the resulting prompts to a configured Genai.
GWConstants	Central constants used by Ghostwriter configuration and runtime processing.