Overview

An Act is a reusable task definition for Ghostwriter. It is stored in a small TOML file and tells Ghostwriter how to run a predefined AI-assisted workflow.

An act usually contains:

• a description for humans,
• instructions that define the AI assistant's role,
• an inputs template that becomes the prompt,
• optional Ghostwriter settings such as gw.scanDir, gw.interactive, gw.nonRecursive, or gw.threads.

Acts make repeated work easier. Instead of rewriting the same long prompt each time, you can run a named act and let Ghostwriter load the saved template for you.

Acts are loaded by ActProcessor. This class reads the TOML file, merges inherited values, applies act settings to the processor, prepares episode execution, and then runs the prompt against the project.

What an Act Does

At a high level, an act helps Ghostwriter do four things:

1. Load a named workflow from a TOML file.
2. Prepare the final prompt by combining the act template with the user request.
3. Apply runtime settings such as scan rules or interactive mode.
4. Execute one or more episodes in the configured order.

The normal command format is:

gw --act <name> [your request text]

You can also point directly to a TOML file:

gw --act C:\path\to\my-act.toml [your request text]

When an absolute TOML path is used as the act name, Ghostwriter uses that file only. In that case, lookup through bundled classpath resources is not used.

How Act Loading Works

ActProcessor.setAct(String) is the main entry point for act loading.

In simple terms, it does this:

1. If no act name is provided, Ghostwriter uses help.
2. It separates the act name from the optional user prompt.
3. It detects optional episode selection syntax such as help#2 or task#1,3!.
4. It calls ActProcessor.loadAct(...) to load and merge act data.
5. It applies the user prompt into the inputs template.
6. It applies act properties to the processor.
7. It runs the selected episode flow.

Act File Structure

A typical act file can look like this:

description = '''
Short explanation of what this act does.
'''

instructions = '''
You are an expert assistant.
'''

inputs = '''
# Task

%s
'''

prompt = "Default prompt text"
# basedOn = "task"

[gw]
scanDir = "glob:."
interactive = true

Common top-level properties:

Common gw.* properties used by the built-in acts include:

Interactive and Non-Interactive Mode

Acts can run in two different styles.

gw --act commit

Default Prompt with prompt

An act can define a default user prompt with the prompt property. This value is used when the user runs the act without providing extra request text.

Example:

description = "Simple project summary"
instructions = "You are a project analyst."
prompt = "Summarize this project for a new developer."
inputs = '''
# Task

%s
'''

Behavior:

• gw --act describe "focus on the API layer" uses focus on the API layer.
• gw --act describe uses Summarize this project for a new developer.

This is handled during setAct(...), where the processor falls back to the current default prompt when the command does not include one.

Episodes

An act can contain one prompt or multiple prompts.

When inputs is a single string, the act has one main prompt. When inputs is a TOML array of strings, each array item becomes a separate episode.

Example:

inputs = [
    '''
# Analyze
Review the code and list the most important issues.

%s
''',
    '''
# Fix
Apply the approved changes.
'''
]

In this case, Ghostwriter runs a sequence of episodes rather than a single step. The Episodes helper manages the order and provides episode information to the processor.

Inheritance and Value Merging

Acts can inherit from other acts with the basedOn property.

Example:

basedOn = "task"

This allows one act to reuse another act and override only the parts that need to change.

instructions = '''
You are helping with %s.
'''

instructions = "documentation tasks"

instructions = '''
You are helping with documentation tasks.
'''

instructions = '''
You are working on the %s project.
'''
inputs = '''
# Task
%s
'''

basedOn = "base"
instructions = "Ghostwriter"
inputs = '''
Create a summary.
%s
'''

instructions = '''
You are working on the Ghostwriter project.
'''
inputs = '''
# Task
Create a summary.
%s
'''

Placeholder Variables in ${...} Format

Act files may contain placeholders such as ${sonar.host} or ${sonar.token}. These placeholders must stay exactly as written.

They are intended for dynamic substitution by functional tools at runtime. They can be resolved from sources such as:

• environment variables,
• Java system properties,
• action properties,
• configurator properties,
• other runtime configuration sources.

Important rules:

• ${...} placeholders are not for the LLM to resolve,
• they must not be edited, expanded, renamed, or removed,
• they should be passed through unchanged until runtime substitution happens.

Example from the built-in sonar-fix act:

${sonar.host}/api/issues/search?componentKeys=...

In this example, ${sonar.host} is kept unchanged in the act definition and is resolved later by the application environment.

Using an Act Step by Step

A simple real-world workflow looks like this:

1. Start with help

   gw --act help
   

   This opens the built-in help act and explains available act behavior.

2. Run a task-oriented act

   gw --act code-doc "add missing API documentation"
   

   Ghostwriter loads code-doc.toml, injects the request into inputs, and processes matching files.

3. Use interactive mode if needed

   For acts such as help, task, or commit, you can continue the session, refine the request, type > to continue, or type . to finish.

4. Create a custom act

   Put a file such as my-act.toml into the directory configured by gw.acts. A simple example is:

   basedOn = "task"
   description = "My custom project workflow."
   prompt = "Analyze the current folder and suggest improvements."
   

5. Run the custom act

   gw --act my-act
   

6. Use a direct TOML file path for one-off usage

   gw --act C:\temp\custom.toml "review this module"
   

Built-in Acts

Ghostwriter includes several built-in act files in src/main/resources/acts.

Key Methods and Project Role

The Act feature is a core way to use Ghostwriter. It turns repeatable AI tasks into named, version-controlled definitions that can be shared and reused.

Important implementation points include:

• ActProcessor.setAct(String) parses the act command and applies prompt and episode selection.
• ActProcessor.loadAct(...) loads acts from custom and built-in sources and resolves basedOn inheritance.
• ActProcessor.setActData(...) and related merge helpers combine TOML values.
• ActProcessor.applyActData(...) transfers resolved values into runtime processor settings.
• Episodes manages episode naming, ordering, selection, repetition, and jumps.

Together, these parts let Ghostwriter run anything from a simple one-step prompt to a guided multi-step workflow.

Summary

The Act feature gives Ghostwriter a structured and reusable way to perform work. It is useful because it combines:

• reusable prompt templates,
• optional inheritance,
• configurable runtime settings,
• interactive and non-interactive execution,
• multi-step episode workflows,
• support for runtime placeholders in ${...} format,
• built-in and user-defined act definitions.

For new users, the easiest place to start is:

gw --act help

From there, you can explore built-in acts, run them directly, or create your own custom act files for repeatable project workflows.