https://github.com/othercodes/minion-forge
MinionForge is a modular instruction system for AI models. It is designed to work with Claude Sonnet 4, GPT-based models, or any language model that supports XML-style prompts inside Markdown files.
https://github.com/othercodes/minion-forge
Last synced: 4 months ago
JSON representation
MinionForge is a modular instruction system for AI models. It is designed to work with Claude Sonnet 4, GPT-based models, or any language model that supports XML-style prompts inside Markdown files.
- Host: GitHub
- URL: https://github.com/othercodes/minion-forge
- Owner: othercodes
- Created: 2025-07-22T23:19:06.000Z (11 months ago)
- Default Branch: master
- Last Pushed: 2025-07-24T08:08:12.000Z (11 months ago)
- Last Synced: 2025-08-05T03:41:43.269Z (11 months ago)
- Size: 32.2 KB
- Stars: 1
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# MinionForge
MinionForge is a modular instruction system for AI models. It is designed to work with Claude Sonnet 4, GPT-based models, or any language model that supports XML-style prompts inside Markdown files.
The goal is to define precise, reusable, and role-based behaviors through structured prompt modules. This helps AI follow clear rules and adapt better to real-world project workflows.
## Motivation
Most prompts are plain text — difficult to maintain, scale, or reuse reliably.
MinionForge solves this by breaking behavior into modular, reusable instructions tied to specific roles and contexts.
## Project Status
MinionForge is currently in active development and considered experimental. The format, tags, and conventions may change as we refine the design based on real-world usage with different models.
## References
- [Anthropic Claude Prompt Engineering Guide](https://docs.anthropic.com/en/docs/build-with-claude/prompt-engineering/overview)
## Components
MinionForge uses custom XML tags embedded in `.md` files. These tags define structure and intent, while keeping the text readable and easy to maintain.
| Tag | Purpose |
|------------------|--------------------------------------------------------------------|
| `` | Declares the identity and purpose of the AI agent. |
| `` | Lists what this role is expected to deliver. |
| `` | Declares global rules shared by all roles and instruction. Only allowed in the base instruction file. |
| `` / `` | Mandatory behaviors and constraints for the role or instruction. |
| `` / `` | Recommended strategies or behavioral suggestions. |
| `` / `` | Declares instructions: either as inline blocks or external references. |
| `` / `` | Optional usage samples for clarity or guidance. |
| `` / `` | Runtime options or behavior flags (e.g. `--seq`). |
| `` | Sets the default language, architecture, or project context. |
| `` | Defines how the AI should interact with users (tone, clarity, intent). |
| `` | Enforces voice, confidence, and level of formality. |
| `` | Controls formatting, spacing, line length, and visual hierarchy. |
| `` | Specifies allowed symbols and their meanings. |
| `` | Declares individual symbols and their interpretation. |
| `` | Defines the required structure of output (summary first, bullets, etc). |
## Format and Structure
All files are plain `.md` files using XML-style tags. Each `` is structured using a consistent set of components described below.
### `` / ``
The `` tag is used to declare atomic instructions.
You can define them in two ways:
1. **External reference** (recommended for modular design):
```xml
- [analyze-project](../instructions/analyze-project.md)
- [generate-development-checklist](../instructions/generate-development-checklist.md)
```
each item links to a separate `.md` file containing a block, like:
```xml
Generate a detailed checklist from the FDD, with verifiable implementation steps grouped by section.
```
You may also define a natural-language condition inline to guide activation:
```xml
Each listed instruction is REQUIRED when the user’s request matches the described condition.
You MUST load and apply the full content of the linked file in that case.
- You MUST use [generate-tests](./instructions/generate-tests.md) whenever the user requests to create, extend, or infer unit or feature tests from code or specification.
```
This is an example of a **semantic activation phrase**. It tells the model when to apply each instruction, using natural language instead of special tags. This approach also makes the instruction list easier to read and maintain.
2. **Inline declaration** (for context-specific or temporary instructions):
```xml
Generate a detailed checklist from the FDD, with verifiable implementation steps grouped by section.
```
You may mix both forms if needed, but external files are preferred for reuse and clarity.
### ``
Defines strict behaviors or constraints the model must follow.
Each `` is atomic and imperative. Use them to enforce logic, compliance, or limitations.
You can add a `for="..."` attribute to scope the rule (e.g., `tooling`, `architecture`, etc.).
```xml
NEVER write business logic inside views or serializers.
ALWAYS validate user input before processing.
ONLY use markdown for documentation tasks.
```
### ``
Provides softer behavioral instructions — best practices, style guides, or process recommendations.
Use `` for suggestions that improve clarity, safety, or quality.
```xml
Use second-level markdown headings (`##`) for main sections.
Organize tasks in the same order as the FDD sections.
Ask questions before adding optional sections like security or performance.
```
### ``
Optional but useful. Provide sample inputs and expected outputs using `` to guide the model.
Use only when the behavior is non-obvious or benefits from demonstration.
```xml
Design an endpoint to deactivate a user.
POST /users/{id}/deactivate → triggers UserDeactivationService
```
### ``
Declare runtime flags that affect reasoning. For example: `--seq` for sequential thinking.
Each `` represents a modifier that the model should activate when the instruction is loaded.
```xml
--seq
--context7
```
### ``
Used to specialize a instruction for specific environments (like Django, Laravel, etc.).
Each `` must include a `` section that defines when it applies.
Variants may override or add ``, ``, or `` inside the instruction.
```xml
Python
Django
Use DRF ViewSets and Celery tasks when applicable.
```
Variants are optional. The base instruction applies globally by default.
### ``
Declares the default working context — such as language, framework, architecture, constraints, or any other environment-specific assumption the AI should consider when reasoning.
Use this block in role or system instruction files to define expectations like:
```xml
Python
Django
modular, testable
design-first
```
### Example Project Structure
```text
.github/
├── copilot-instructions.md
├── instructions/
│ ├── analyze-project.md
│ ├── generate-fdd-outline.md
│ ├── generate-development-checklist.md
│ ├── generate-architecture-diagram.md
│ └── ...
└── chatmodes/
├── feature-designer.chatmode.md
└── software-engineer.chatmode.md
```
- `instructions/` contains atomic instruction modules (reusable).
- `chatmodes/` defines the roles, responsibilities, and instruction loading logic.