Key operations

For users invoking an act through Ghostwriter, the important operation is ActProcessor.setAct(...): it accepts an act name, optional request text, and optional episode selector, then loads and configures the workflow. ActProcessor.getResults() returns the responses collected during the run. Internally, ActProcessor delegates each episode to AIFileProcessor.process(...); that processor prepares the prompt, context, model, and tools before calling the AI provider. These operations separate a repeatable workflow definition (the TOML file) from the project-specific work performed in each run.

What happens when an act runs

At a high level, ActProcessor.setAct(...) interprets the act name, optional request text, and optional episode selection. It then loads the TOML definition (and any parent definition), applies defaults and configuration, and prepares the episodes. During project traversal, ActProcessor runs each selected episode for each matching file. For each episode, AIFileProcessor.process(...) adds project and execution information, reads YAML front matter, resolves permitted tools and runtime substitutions, and sends the resulting instructions and prompt to the configured AI provider. The collected provider responses are available from ActProcessor.getResults().

Default user prompt: the prompt property

The prompt property used by an act is the dotted TOML key public.prompt (not a separate top-level prompt key). Set default.public.prompt in the TOML file to provide the default request used when no direct public.prompt value has already been configured:

[default]
public.prompt = "Review the project for documentation gaps."

inputs = '''
Perform this request: ${public.prompt}
'''

The resulting value is stored as public.prompt and can be inserted anywhere in the prompt with ${public.prompt}. A value already supplied as public.prompt is retained rather than replaced. Defaults are applied before the request text appended to the act name is bound. Consequently, an act that defines default.public.prompt retains that default unless the caller supplies public.prompt through configuration; appended request text does not replace it. If an act must use the text appended after its name, do not set a competing default.public.prompt, or arrange for the caller to set public.prompt explicitly.

For example, gw --act doc-audit uses the configured default when no public.prompt has been supplied. A caller that needs a different default can set public.prompt through its configuration before starting the act; keep ${public.prompt} unchanged in the TOML template so that runtime substitution can occur.

Prompt front matter and tools

An input may start with YAML front matter between --- lines. gw.model selects a model/provider for that prompt. enabledTools can be a whitespace-, comma-, or semicolon-separated value or a YAML list:

inputs = '''
---
gw.model: ${public.reviewModel}
enabledTools:
  - org.machanism.machai.gw.tools.ProjectContextFunctionTools:get_project_context_variable
  - org\.machanism\..*:read_file
---
Inspect ${public.prompt}.
'''

Each enabledTools item is a regular-expression pattern. A tool is identified internally as <ClassName>:<toolName>—for example, org.example.Tools:read_file; the tool name is its declared name, or the method name when no explicit name exists. A tool is registered only when its full identifier matches at least one pattern. If enabledTools is null or omitted, all available tools are registered without filtering. Use precise patterns when an act needs limited capabilities. The patterns are not display labels: write the fully qualified implementation-class name followed by : and the declared tool or method name.

Prompt and instruction lines can include content using >>> URL or >>> file://relative/path; included UTF-8 content is processed recursively. Public configuration values can be substituted in prompt metadata and text.

Automatic tool selection: enabledTools: auto

An act can ask Ghostwriter to choose tools for an episode instead of maintaining a fixed pattern list. Put enabledTools: auto in that episode's YAML front matter:

inputs = '''
---
enabledTools: auto
---
Review the selected files and make the required changes.
'''

Before running the episode, Ghostwriter asks the configured AI provider to select the relevant tools from the available set using the act instructions and episode prompt. The resulting selection is cached for that act and episode, then only those tools are registered for the actual request. To give the selector an additional constraint, use an auto mapping:

inputs = '''
---
enabledTools:
  auto: Don't use web access and system command tools.
---
Analyze the local implementation.
'''

The mapping value guides selection; it is not a hard tool denylist. Use explicit regular-expression patterns when a strict, predictable tool boundary is required.

If automatic selection returns no enabledTools value or cannot be completed, Ghostwriter falls back to the normal unfiltered behavior, so all available tools may be registered. Use explicit regular-expression patterns rather than auto whenever a restricted tool boundary is required.

Placeholders

Write dynamic placeholders exactly as ${...}, such as ${public.prompt}, ${sonar.host}, ${sonar.token}, and ${super.value}. They are runtime substitution points for the configurator and functional tools: environment values, system properties, action properties, and similar configured sources can provide their values. The LLM must not edit, resolve, rename, or otherwise modify these placeholders in an act template; they must remain intact until the runtime component performs substitution.

code-doc

Adds or improves documentation comments in code files, using the language-appropriate format such as Javadoc or docstrings. Use it when documentation is missing, unclear, or incomplete; it is limited to documentation changes and ignores .machai.

commit

Analyzes pending Git or SVN changes, groups them into logical commits, creates messages matching the repository style, and executes the commits. Use it only when you want the act to stage and commit project changes automatically; it runs interactively and uses command tools.

grype-fix

Uses Syft and Grype scan output to find dependency vulnerabilities, update dependencies with available fixes, build the Maven project, and document remediation. Use it when Syft and Grype are installed and dependency security findings need practical fixes.

help

Provides interactive help for Ghostwriter acts and episodes, including how to locate an act, inspect its properties, understand inheritance, and invoke it. Use it when you are unsure which act to choose or how an existing act is configured.

sonar-fix

Retrieves SonarQube findings, fixes eligible quality and security issues, adds or updates tests, validates the build, and records changed files in UPDATED_FILES_REPORT. Use it for an available, configured SonarQube service; it deliberately does not change SonarQube configuration or quality gates.

task

Provides the minimal general-purpose project-aware assistant workflow. Use it for a custom request that does not need a specialized act; the > shorthand selects this act automatically.

unit-tests

Builds the project, analyzes JaCoCo coverage, and creates or improves unit tests for under-covered code. Use it when you need meaningful test coverage improvements, especially for a specified source area.

Mental model: two orthogonal loops

It helps to think of the processing as two nested loops that are deliberately kept independent:

1. The traversal loop (outer, deterministic). Walk the project — recurse into modules, list files, filter them. This loop is pure filesystem and project-layout logic. No model is involved in deciding which files exist or whether to visit a module; that is derived from ProjectLayout and configuration.
2. The reasoning loop (inner, model-driven). For each matched file, run the Act's episodes. Here the GenAI provider does the “thinking” — reading, editing, reviewing, or generating content — but always within the bounds of the current file and the episode's prompt.

Keeping these loops orthogonal makes runs reproducible (the same project produces the same set of work items), parallelizable (modules are independent), and bounded (the model cannot wander off to arbitrary parts of the repository unless a tool explicitly allows it).

1. Entry point — scanFolder(projectDir)

Processing begins in AbstractFileProcessor.scanFolder(File projectDir). It first resolves the project structure by calling getProjectLayout(projectDir), which returns a ProjectLayout describing the project's sources, tests, docs, and — importantly — its modules.

The processor then decides whether to recurse into modules based on the non-recursive flag:

• If non-recursive mode is enabled, module recursion is skipped entirely, and only the current project's own files are processed.
• Otherwise, it proceeds to module discovery.

2. Module discovery and recursion

The processor reads the module list via projectLayout.getModules(). If one or more modules exist, they are processed using one of two strategies, controlled by the threads setting:

• Sequential (threads <= 1): Each module is processed one at a time in a simple loop, calling processModule(projectDir, module).
• Multi-threaded (threads > 1): processModulesMultiThreaded() submits a processModule task for every module to a fixed-size thread pool. It then waits for all Future results and safely shuts down the executor (bounded by moduleThreadTimeoutMinutes). Interruptions and execution failures are surfaced as IllegalStateException.

Crucially, processModule recursively re-enters scanFolder for each sub-module directory. This means the entire logic (module discovery + file processing) repeats for every module, producing a full recursive traversal of a multi-module project tree.

Why modules are the unit of parallelism. Modules in a well-structured project are largely independent (their own sources, tests, and build unit). Treating each module as an isolated work item means concurrency is safe by construction — two threads rarely touch the same file — without needing locks or a shared task queue. This is a much simpler concurrency model than the task-graph schedulers used by many autonomous multi-agent systems, and it maps cleanly onto real project topology.

3. Parent (non-module) file processing

After all modules are handled, scanFolder calls processParentFiles(projectLayout). The base class provides an empty hook, but ActProcessor overrides it to perform the actual Act work on files that belong directly to the current project (not to its modules).

The steps are:

1. List candidate files — listFiles(projectDir) recursively collects files, excluding known build/tooling directories, and sorts them deepest-first (by path depth).
2. Filter the list — entries are removed if they are module directories (isModuleDir) or if they fail the match() test.
3. Fallback — if no files match, the processor falls back to processing the project directory itself (so the act still runs once).

The match() method decides file inclusion using several rules:

• Rejects null files and any path under excluded directories (ProjectLayout.isExcludedPath).
• If a pathMatcher is configured, the file's project-relative path must match the glob/regex pattern; otherwise the file must equal the explicit scan path.
• Applies user-supplied excludes[] patterns (glob, regex, or exact path).

Why deepest-first ordering matters. Sorting files by descending path depth means leaf files are handled before their parent directories. For documentation and aggregation acts this is useful: a parent (e.g. a package README or an aggregator pom) can be generated after its children exist, letting a later step summarize work that earlier steps produced. It is a lightweight, filesystem-level form of dependency ordering, achieved without a planner.

4. Per-file Act (episode) execution

For each surviving file, if it matches and a default prompt is present, the Act's episodes are executed via the Episodes component:

• Requested (selected) order — when a subset of episodes was selected (e.g. act#1,3), requestedOrder() runs just those episodes in the requested sequence. If the ! stop flag (disableNormalOrder) is set, processing of that file stops afterward; otherwise the normal order resumes from the next episode ID.
• Regular order — regularOrder(startId, callback) runs episodes sequentially. Each episode invokes ActProcessor.process(), which prepends the act-execution metadata JSON, resolves the enabled tools (including auto tool selection), and sends the prompt to the GenAI provider via AIFileProcessor.

Each episode's output is appended through addResults(perform).

Episodes as an explicit, inspectable plan. In most agent frameworks the plan is produced by the model at runtime and is therefore opaque and non-repeatable. In Ghostwriter the plan is the Act definition: an ordered list of episodes written in TOML, versioned in the repository, reviewable, and reusable. The model still reasons freely inside an episode, but the sequence of steps, their instructions, and their allowed tools are authored by a human. This makes Act execution closer to a declarative pipeline with LLM-powered stages than to an autonomous agent.

5. Control-flow and termination

During episode execution, several signals influence the flow:

• RepeatEpisodeException — re-runs the current episode (iteration count increments).
• MoveToEpisodeException — jumps to another episode by numeric ID or by heading name.
• EndTaskException — records the message and stops parent-file processing for the current run.

When all modules and matching files have been processed, the collected outputs are available through getResults().

Bounded, model-triggered control flow. These exceptions give the model some dynamic control — it can loop, jump, or stop — but only over a finite, named set of episodes that already exist. This is a deliberate middle ground: it keeps the adaptiveness that makes agents useful (retrying, branching on results) while removing the unbounded, potentially runaway behavior of fully autonomous loops. The set of reachable states is always known ahead of time.

Comparison with other AI agent strategies

Ghostwriter's model is best understood by contrasting it with the common patterns used to build AI agents and LLM applications.