Guidance Tag
A guidance tag is a plain-language instruction you keep inside the file it concerns. The marker is written as @guidance: inside a supported comment, or supplied by the special @guidance.txt folder file. Machai Ghostwriter reads these instructions during Guided File Processing and uses them to prepare an AI-assisted update. Think of a tag as a note in the margin: it tells the assistant what you want, while you remain responsible for the final result.
Guidance tags help automate routine work such as improving documentation, creating website content, or adding tests. They do not change how your application runs, add dependencies, or affect source data at runtime. Because the instruction lives with the project, it can be reviewed, versioned, reused, and refined by the whole team. You can also use the saved instruction as a checklist for manual work when AI processing is not appropriate.
This is Machai's Guidance-Driven Processing (GDP) approach: the instruction travels with the file instead of being kept in a separate chat or one-off prompt. Ghostwriter acts as a skilled assistant that formats and enriches the ideas you provide; it does not know project-specific intent unless you describe it. The same workflow can be completed manually, or accelerated with AI followed by your final verification.
How it works

- Add an
@guidance:tag in a supported file, or add a folder instruction file named@guidance.txt. - Run Ghostwriter and choose a project folder and, optionally, a scan path.
- Ghostwriter—not the AI—finds matching supported files that contain guidance and gives each file its own processing context. If your run is configured with default guidance, matching files can instead use that default instruction.
- A file reader, called a reviewer, recognizes the tag using the file's supported comment style. It prepares the instruction and file information for the AI service. Depending on the file type, it includes the whole file or extracts the instruction text; the supported styles are listed below. A file named
@guidance.txtsupplies its full contents as guidance for its folder. - Ghostwriter combines this material with its standard processing rules and sends it to your configured GenAI provider. Review the result, then revise the tag and run again if needed.
This follows the Guided File Processing approach: natural-language instructions are treated as maintainable project assets and are kept in context with the files they describe. AI is useful for routine enrichment—explaining existing code, adding examples, or organizing text—but it cannot know your project-specific intent unless you state it in the guidance.
Guidance-driven processing is deliberately an assistant workflow rather than a promise that AI will make every decision for you. The application identifies eligible files and creates a separate context for each one; you remain the author who checks the proposed result. The same instructions can be followed manually when a task should not use AI.
Scope and processing order
The project folder is the base directory Ghostwriter examines. A scan path narrows that work to a file, folder, glob pattern, or regular expression; it can be relative or absolute. A narrow scan is useful when you want to update only one documentation area or module.
Ghostwriter recognizes project modules and processes child modules before the parent project. Files deeper in the directory structure are considered first, which helps when a top-level file relies on information from lower-level files. Child modules may run in declared order or in parallel when multithreading is enabled; a build tool can instead determine the module order from dependencies.
The model is selected for the run, so choose a model that fits the quality, speed, and cost you need. Ghostwriter can be used from the command line or from a Maven build, and is suitable for repeatable local or CI/CD workflows.
Supported files and tag styles
Reviewers recognize these built-in file types:
| File type | Extension(s) | Where to put the tag |
|---|---|---|
| HTML, HTML fragments, and XML | html, htm, xml |
An HTML/XML comment: <!-- @guidance: ... --> |
| Markdown | md |
An HTML comment: <!-- @guidance: ... --> |
| Java | java |
A block or // comment |
| TypeScript | ts |
A block or // comment |
| Python | py |
A # comment or triple-quoted string |
| VBA (Visual Basic for Applications) | bas, cls, frm |
An apostrophe (') or Rem line comment, with the instruction on the same line |
| PlantUML | puml |
Include the marker anywhere in the diagram; a PlantUML comment is the usual choice |
| Folder instruction | exactly @guidance.txt |
Put the instruction in that file |
An ordinary .txt file is not an inline-guidance file: text files have no comment syntax. @guidance.txt is the exception and represents guidance for its folder. Java's package-info.java can also provide package-level guidance.
The exact comment format matters. Markdown, HTML/XML, ordinary Java, and PlantUML files supply their complete contents when recognized guidance is present. Java's package-info.java instead supplies its path for package-level processing. TypeScript, Python, and VBA supply extracted, non-blank instruction text rather than the complete source. @guidance.txt is identified by its exact filename rather than by an inline marker and supplies its complete contents. Tags are retained in the source so they can be found in a later run.
For TypeScript and Python, prefer one clear guidance comment: these readers use the first matching line instruction, or the first matching block or triple-quoted instruction if no line instruction is found. VBA uses the first matching line instruction. Keep a line-comment instruction on the same line as the marker; use a supported block form for longer instructions. These readers do not combine separate guidance comments into one instruction.
Practical usage
Add guidance to a Markdown page
- Open the page you want to update.
- Add an HTML comment near the top.
- State the audience, required content, and anything that must not change.
- Run Ghostwriter for the project or a targeted scan path.
- Ghostwriter reads the page and its instruction, then uses the selected AI service to update the surrounding content—for this example, installation steps, a usage example, and support information. The guidance comment stays in place for future runs.
- Check the update, confirm that license details remain intact, and improve the instruction before rerunning if necessary.
<!-- @guidance:
Update this README for new users.
Include installation, a short usage example, and support information.
Do not remove existing license details.
-->
Add guidance to source files
Use the comment style appropriate to the language. In Java, for example:
/* @guidance:
* Add clear documentation for public methods.
* Include one simple usage example where helpful.
* Do not change method names or behavior.
*/
TypeScript accepts block or // comments. Python accepts either a line comment with text on the same line or a triple-quoted string. Prefer a # comment when you want an instruction that is strictly a comment; a triple-quoted string is Python code and can become a docstring depending on where you place it:
'''
@guidance:
- Follow PEP 257 for docstrings.
- Document public classes and functions.
- Do not change runtime behavior.
'''
For a VBA module, class, or form, use a line comment such as ' @guidance: Document this module without changing its behavior. or Rem @guidance: Document this module without changing its behavior. Keep the full instruction on that line. During processing, the VBA reader passes that instruction and the file's name and path to the AI service.
For a PlantUML diagram, place the marker in a diagram comment:
@startuml
/' @guidance: Keep this diagram consistent with the current workflow. '/
Alice -> Bob: Request
@enduml
Guide a folder
Create @guidance.txt in the folder. Its full content becomes the folder instruction, making it useful for a shared test style, documentation rules, or requirements for related examples.
Create high-quality unit tests in this folder.
Use descriptive test names.
Cover edge cases and error handling.
Follow the Java version configured by the project.
Run Ghostwriter
After configuring access to a GenAI service and selecting a model, run the standalone application or Maven goal:
java -jar gw.jar
mvn gw:gw
Ghostwriter requires a Java 8 JVM; Java 17 or newer is recommended for the best experience. In a CI/CD pipeline, keep provider credentials and tool permissions in the build environment rather than embedding them in guidance comments.
To limit the scan, provide a path or pattern, for example:
java -jar gw.jar "glob:**/*.md"
mvn gw:gw -Dgw.path="glob:**/*.md"
The model selection applies to the run. Run separate scans when different folders need different models or instructions.
What happens during a run?
The GuidanceProcessor is the part of Ghostwriter that coordinates guidance processing. It chooses a file reader, called a reviewer, based on the file's extension. That reader checks for the supported tag style and prepares the instruction and file context described above. Unsupported files, or files without recognized guidance, are normally left alone; a configured default instruction can also be used for matching files. Developers can add readers for other file formats without changing the way users write plain-language instructions.
Ghostwriter sends its standard processing rules and the reviewer's material to your selected AI service. File, command, and web tools let the assistant inspect and update files, run checks, examine logs, and look up information when the task requires it. If the provider has no tools configured, the processor adds its built-in file, command, and web tools. Review your tool settings and permissions before running, especially for actions that change files, execute commands, or access the network.
The processor collects file paths and processing messages in a report and logs the total number of processed files. Use the messages to review the run, but also inspect the actual changes and run any relevant tests: a completion message alone does not prove that the result is correct.
Guidance processing is deliberately focused on the file or folder instruction. It is a lightweight choice for local, repeatable rules. Use an Act instead when you need a reusable, multi-step workflow with explicit sequencing across a wider task.
Why use guidance tags?
- Save time: keep recurring instructions instead of repeatedly writing prompts.
- Reduce manual work: let Ghostwriter handle routine drafting and updates, then focus on review.
- Improve consistency: give related pages, source files, and tests the same clear standards.
- Keep intent visible: the instruction stays beside the work and is easy to inspect in version control.
- Support collaboration: technical and non-technical contributors can use everyday language to describe the outcome they need.
- Keep control: specify project knowledge, protected content, and acceptance criteria; verify every result before accepting it.
Tips for effective guidance
- Start with the intended outcome and audience.
- List required sections, examples, or checks.
- Say explicitly what must not change.
- Prefer specific requests over “make it better.”
- Keep the tag in a valid comment for the file type.
- Treat the instruction like source code: review and improve it over time.
Further resources
Learn more about scan paths, project structure, AI services, tools, and the wider workflow in Guided File Processing.

