Quick start

1. Choose a built-in act, for example unit-tests, or create my-review.toml in your configured acts directory.
2. Run the act by name and optionally add a request after it. For example: unit-tests Focus on the parser package.
3. The text after the name is the requested task. When the act has not already supplied public.prompt (including through a default), it becomes the user prompt available to the TOML template as ${public.prompt}.
4. The act loads its instructions, tools, inputs, defaults, and any parent act. It then processes the selected project files or project-level episodes.
5. Review the result. In interactive acts, continue the conversation or end it using the commands described below.

A command beginning with > is shorthand for the generic task act. For example, > summarize the project structure is treated as task summarize the project structure. If no act is named, Ghostwriter uses help.

Act TOML anatomy

A simple act has an optional description, instructions for the AI, and one or more inputs:

description = "Review a project area."

instructions = '''
Explain findings clearly and make only necessary changes.
'''

inputs = '''
---
enabledTools:
  - org.example.ProjectTools:read_project
---
Review ${public.prompt}.
'''

[default]
public.prompt = "the project structure"

[gw]
interactive = true

instructions provide stable, system-level guidance. inputs hold the prompt sent for an act or episode. [gw] settings configure Ghostwriter behavior, including path, interactive, threads, excludes, and nonRecursive. Other string settings are made available through the configurator. A TOML inputs value can be a single string or an array of strings.

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

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

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

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

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

Episodes and input parameters

When inputs is an array, every item is an episode: an ordered prompt in one larger workflow. This supports staged work—for example, inspect first, make changes second, and validate third. An act can also use a single input, which becomes the default prompt.

Select particular episodes by adding # to the act name. Episode numbers are comma-separated, and ! prevents normal sequential processing after the requested episodes:

review#1,3! Check concurrency and error handling

This runs episodes 1 and 3 with the supplied request, then stops rather than continuing in normal order. Without !, selected episodes run and normal ordering may continue. Episodes can also request movement to another episode during processing.

The YAML input parameters recognized specially by AIFileProcessor are:

• gw.model — overrides the configured AI model/provider for the prompt.
• enabledTools — a string or YAML list of regular-expression patterns controlling registered tools.
• Other YAML values are retained as prompt configuration; string values are resolved through the active configurator, but they do not by themselves change processing behavior.

For every processed item, Ghostwriter also sends JSON process information containing PROCESSED_FILE_REL_PATH, PROCESS_MODE (INTERACTIVE or NOT-INTERACTIVE), and OS_NAME. Project-context tools receive the project name, IDs, directories, source/test/document folders, modules, and operating-system context.

Interactive and non-interactive acts

A non-interactive act is a predefined command: it can run from its configuration without asking for extra data. This is useful for repeatable tasks such as generating documentation or tests. Add request text only when you need to narrow or customize the work.

Set gw.interactive = true when the act should operate as a chat. Interactive mode is useful when the desired action is not fully known at the beginning: the AI responds, then you can provide the next instruction. After a response:

• Enter > (AIFileProcessor.CONTINUE_SPECIAL_PROMPT_COMMAND) to accept the current response and continue processing without another AI prompt.
• Enter . (AIFileProcessor.EXIT_SPECIAL_PROMPT_COMMAND) to terminate the act successfully.
• Enter >> to accept the current response and switch the remaining work to non-interactive processing.
• An empty entry has no special command meaning; when the hosting environment supplies it, it is treated as ordinary follow-up input rather than as a continue or exit command.
• Enter any other text to send it as the next chat prompt.

Interactive input requires an environment that supports it. In a non-interactive execution environment, acts proceed without chat input; use a predefined non-interactive act when the task must run unattended.

Inheritance, overrides, and defaults

An act may inherit another act using basedOn:

basedOn = "base-review"

instructions = "${super.value}\nAlso check public APIs."
inputs = [
  "${super.value}\nReport a concise summary.",
  "Run validation."
]

[default]
gw.threads = 2

The child definition is read and its basedOn parent is then loaded into the same property map. During this merge, the value already in the map is the overriding value. For strings, ${super.value} in that overriding value is replaced with the inherited value; without the placeholder, the overriding value remains unchanged. Input arrays are handled by position: an entry containing ${super.value} incorporates the corresponding inherited episode, while entries beyond the other array are kept. A custom act with the same name as a built-in act is also loaded and can override or extend the bundled definition.

[default] entries are fallbacks. A default.some.key value is copied to some.key only when no non-default act value exists; an existing configurator value can replace that fallback. When string act data is later applied, ${super.value} can also be resolved from the current configurator value. In practice: use basedOn for reusable templates, ${super.value} to preserve or append inherited/configured content, and [default] for values that should be available only when no direct value was set.

For example, this child keeps the parent's instructions and adds one rule:

basedOn = "base-review"
instructions = '''
${super.value}
Also check public APIs.
'''

If base-review says Review carefully., the effective instruction includes both sentences. Replacing the child value with instructions = "Check public APIs." deliberately discards the inherited instruction.

Create and run a custom act

1. In the configured acts directory, create doc-audit.toml.

2. Add a description, stable instructions, an inputs prompt, and any [gw] settings. Keep runtime variables such as ${public.prompt} exactly as written.

3. Start with a small, safe scope and tools that the act genuinely needs:

   description = "Checks Markdown documentation for clarity."
   instructions = "Explain suggestions in plain language."
   inputs = '''
   ---
   enabledTools:
     - org\.machanism\..*:read_file
   ---
   Review the Markdown files in ${public.prompt}.
   '''
   
   [gw]
   path = "glob:src/site/**/*.md"
   interactive = true
   

4. Run --act doc-audit src/site. Ghostwriter loads the TOML file, resolves allowed configuration values at runtime, selects matching files, and starts the workflow. Because it is interactive, use > to continue after a response or . to end it.

5. If the workflow later needs separate analysis and editing stages, change inputs to a TOML array; each array item becomes an episode.

Finding act files

Built-in acts are classpath resources under /acts/ and end in .toml. External acts can be loaded from a configured local acts directory or an HTTP(S) location. Relative local locations are resolved from the project root. You can also use an absolute path to a TOML file as the act name, for example C:\work\acts\my-review.toml. In that case, the file is loaded directly; classpath-resource hierarchy is not supported for that file.

Built-in acts

Key API responsibilities

For integrators, ActProcessor is responsible for selecting an act, loading TOML from built-in, local, remote, or explicit-file sources, applying defaults and inheritance, selecting episodes, and collecting outputs through getResults(). AIFileProcessor performs provider execution, reads front matter, applies tool filtering and public-value substitution, processes includes, and produces per-file process information. Together they provide Ghostwriter’s reusable, project-aware automation layer.