Guidance-Driven File Processing
Tell me your sorrows.
― Clifford D. Simak, "Crying Jag"
Inroduction
When developers encounter repetitive tasks, they write code to automate them. However, some tasks don't seem easily programmable, so they're usually done manually, with instructions described in natural language on relevant resources. And this can be disheartening.
Now there's an opportunity to try delegating these concerns to what we've come to call artificial intelligence. Let's skip all the controversial points about copyright, potential leaks of important or confidential information, and other issues related to this technology, and focus on how it can help us as software developers.
Undoubtedly, this is a powerful tool, but with all due respect, let's temper our expectations of AI and not expect it to do everything for us. Let's try to be realistic, and perhaps even a bit pessimistic. For now, it's just a fairly good automatic formatter of your thoughts with a powerful function for improving and adding popular internet information. It's exactly the routine work we never have time for when trying to create something new.
I don't know about you, but I see this as just another software translator, like many others. Only in this case, it translates human language. And that's certainly cool, if the result is what we expected.
Using a guided file processing system is like making notes in the margins of pages with instructions about what should be on those pages, and then "magical" elves execute everything written, leaving you only to check if everything was done correctly. It's somewhat similar to the work of a "ghostwriter": they're quite skilled and erudite, but they're not the master—just an assistant.
GenAI services are often used as chatbots, agents, or assistants. This approach is somewhat different, though similar to the concept of agents: we view GenAI as a natural language translator. In this paradigm, your instructions written in plain language become "source code" that GenAI interprets and executes. This enables automation and optimization of file processing tasks, making even complex workflows accessible to everyone, regardless of technical skill level.
Since we use GenAI prompts as code, it's important to treat them with the same care as traditional source code. Prompts should be stored in the project in a structured and maintainable format, ensuring their versioning, testing, and easy access for future updates or collaboration. This approach helps maintain consistency, traceability, and quality in your GenAI-based workflows.
These prompts or annotations with instructions don't directly affect program behavior during execution. If desired, you can skip the AI processing step and use the saved descriptions as guidelines. However, the process becomes significantly more efficient when using specialized tools and focusing on testing their results.
The @guidance Tag
Unlike tools that write code interactively, this is purely about executing specific file processing tasks described in natural language. This can be anything: writing in-code documentation, creating content pages for a project website, or coverage with unit tests, etc.
The system uses @guidance annotations and special instruction files to automate processing.
@guidance tags are placed in comment blocks to eliminate their impact on source code or data, so they can only be used in files that support comments. For example, text files like *.txt cannot contain such tags. The exception is the @guidance.txt file, which is fully processed as an @guidance tag for the folder in which it's located.
Here are examples of tag usage for different file types.
Markdown, HTML and XML Files
Example:
File: README.md
<!-- @guidance:
**Important:** If any section or content already exists, update it with the latest and most accurate information instead of duplicating or skipping it.
1. **Project Title and Overview:**
- Provide the project name and a brief description based on `src\site\markdown\index.md` content summary.
- Add `` before the title.
- Add `[](https://central.sonatype.com/artifact/org.machanism.machai/machai)` after the title as a new paragraph.
2. **Module List:**
- List all modules in the project.
- For each module, include its name, a short description, and a link to its module
...
-->
Java and TypeScript Files
For Java and TypeScript source files, use the @guidance annotation in a multi-line comment block (not in Javadoc or TSDoc comments).
Example:
File: AIFileProcessor.java
/*@guidance:
* Create or update javadoc of AIFileProcessor class.
* Class javadoc description should describe supported functionality and provide examples to use it.
* If the method used as Javadoc documentation is not public or protected, the method name should not be specified.
*/
TypeScript example:
/*
* @guidance:
* - Document all exported classes, interfaces, functions, and constants using TSDoc.
* - Provide clear descriptions, parameter details, and usage examples.
* - Keep documentation up to date with code changes.
* - Do not use `@guidance` within TSDoc comments.
*/
Python Files
For Python files, use a multi-line comment at the top or in the relevant section to include guidance:
'''
@guidance:
- Follow PEP 257 for docstrings.
- Document all public classes, methods, and functions.
- Keep comments up to date and clear.
'''
Folder Level Guidance
@guidance.txt
In the project root directory, ensure the following files are present and properly created:
**LICENSE.txt**
- Include the full text of the project's license.
- If the license file is missing, create it using the license type defined in the pom.xml file.
- Ensure the license terms are accurate and up to date.
- Use `Copyright 2026 Machanism.org`
Java Package Guidance
For Java packages, you can use the @guidance tag at the package level in the package-info.java file.
Example:
File: package-info.java
package org.machanism.machai.bindex;
/*-
* @guidance:
* IMPORTANT: ADD JAVADOC TO ALL CLASSES IN THE PACKAGE AND THIS `package-info.java`!
* - Use Clear and Concise Descriptions:
* - Write meaningful summaries that explain the purpose, behavior, and usage of each element.
* - Avoid vague statements; be specific about functionality and intent.
*/
Which Files Are Processed
For the application to work, you need to specify the project folder and scan path. The project folder should point to the location of the project (or multiple projects) that need processing. The scan path determines which files in the project need to be analyzed for @guidance tags for subsequent actions.
The scan path is specified as a relative or absolute path to a file or folder; you can also use regular expressions (regex) or glob patterns.
The scan folder defines the specific folder from which file scanning and analysis begins. This parameter allows you to focus processing on only a certain part of your project, providing flexibility and control over which files and subdirectories are involved in the process.
The search for files requiring processing is performed by the application without using AI.
Only files containing @guidance tags are processed. A separate processing session with its own context is created for each one, so the context window is formed only for the current file being processed. The responsibility for identifying files for processing lies with the application, and AI is typically not involved in this.
The application also recognizes the project structure and applies file processing taking into account which module they belong to. This allows scanning of branched projects with many modules.
File Processing Sequence
All project files matching the scan path are sorted based on their location depth (path length). Scanning begins with files that have the most nested folders.
The file processing sequence should be considered if files located closer to the project root use information from files located deeper in the structure.
If the project has child modules, they are processed before the main project files: sequentially (in the order of their declaration in the project) or in parallel (if multithreading is enabled).
Additionally, it's possible to run the application under external build systems, such as Maven in per-module mode. In this case, the module processing sequence will be determined by dependencies in the project.
After processing all modules, the application proceeds to process project files.
Using GenAI Services
For guided file processing, GenAI service APIs are used through a unified abstraction, enabling support for various providers and access proxy servers. The model is specified in the format: <ProviderName>:<ModelName>.
Currently supported providers: 1. OpenAI 2. Anthropic 3. CodeMie - offering a wide range of models: gpt, claude, gemini, etc.
There are also several pseudo-providers that don't call external services and are used for special cases. For example, None:log can be used for system debugging, and Tools:yaml for calling functional tools directly without accessing the GenAI service.
Function Tools
So our "ghostwriter" can not just fantasize but actually work with code, it has a set of built-in functional tools. These enable GenAI to interact with the file system, build projects, run tests, and even access the internet.
All these tools can be divided into several key categories:
- Project and file inspection (structure navigation and search)
- File modification (writing, editing, and auto-replacement)
- Command execution and log handling (project compilation, test running, and result analysis)
- Project context and metadata (understanding structure and relationships between modules)
- Script execution and process management (automation scripts)
- Libraries and external resources (working with external data sources)
- Task and application management (orchestration of the current process)
Important security note: Tools that modify files, execute system commands, or make external network requests are used exclusively when directly required by your task. All these actions are strictly controlled by your access settings (Human-in-the-Loop principle).
You also have the ability to create and add any custom tools for effectively solving your own tasks, or limit their use by specifying only those that are allowed.
Execution Environment
Since Machai Ghostwriter is a Java application, it requires an installed JVM to run. Java 8 is sufficient for executing the tool's own code, but Java 17 or newer is strongly recommended for optimal performance.
Machai Ghostwriter is designed for use in CI/CD pipelines, but can also be run as a CLI tool.
There's also the possibility of publishing Ghostwriter's functional tools through Machai MCP Server. If the application is used as an MCP server, you should consider permissions for actions in the file system where it runs (especially if it's a remote server).
The Machai project also includes a Maven plugin for running Ghostwriter, making it extremely convenient for Maven projects.
The distribution JAR file with all necessary libraries can be downloaded at: https://sourceforge.net/projects/machanism/files/machai/ghostwriter/gw.zip or used as a Ghostwriter Maven plugin as a dependency: org.machanism.machai:gw-maven-plugin. You can also clone the Machai project if you plan to contribute to its improvement.
Running
To start file processing, you only need to specify the path to the project and the scan path—no other parameters are required. All directives that need to be executed are already contained in the files.
It looks like this:
> java -jar gw.jar
or
> mvn gw:gw
If you need to narrow down the list of processed files, add a scan path:
> java -Dgw.model=CodeMie:gpt-5.6-terra-2026-07-09 -jar gw.jar "glob:**/*.md"
or
> mvn gw:gw -Dgw.path=glob:**/*.md -Dgw.model=CodeMie:gpt-5.6-terra-2026-07-09
(or configuration is set in the plugin)
The specific AI provider and model are specified through the gw.model parameter, which applies to all files. If you need to use different models for different paths, you should run processing for each one separately.
Usage Examples
@guidance tags perfectly meet the needs for automatic synchronization of related data—whether it's in-code documentation, project documentation, or writing unit tests.
An example of using Machai Ghostwriter is primarily the Machai project from Machanism. Here, @guidance tags are used in many files for automatic generation and updating of code documentation and configurations. Machai is an open-source project where development focuses on implementing code that provides the required functionality.
Writing documentation is a secondary process, but at the same time extremely important, as it's necessary for third-party users to work with the project. But this isn't just about human users. Within this project, specialized library descriptions (bindex) are also created to form context when using AI for automatic code generation. In this case, automatic intelligent generation of in-code documentation becomes a responsible step, where @guidance tags define information that will be used for code generation.