BuildModule

BuildModule

Guide for creating robust forge modules. Focuses on the three-layer concern architecture and ensures modules are portable across AI coding tools.

Module Structure

Every forge module follows this standard layout:

module-name/
    module.yaml         Metadata and event registration
    defaults.yaml       Default configuration (committed)
    config.yaml         User overrides (gitignored)
    agents/             Agent markdown files
    skills/             SKILL.md files for AI capabilities
    hooks/              Bash scripts triggered by events
    bin/                Entry points or build scripts
    src/                Source code (typically Rust)
    .claude-plugin/     Claude Code plugin manifest
    Makefile            Multi-provider install/verify/test
    CLAUDE.md           Project instructions for Claude Code (generated)
    AGENTS.md           Project overview for Codex/OpenCode (generated)
    GEMINI.md           Project context for Gemini CLI (generated)
    README.md           Human-facing documentation
    INSTALL.md          Installation guide
    VERIFY.md           Post-installation checklist

Not all directories are required. A skills-only module (no hooks, no Rust) only needs: skills/, module.yaml, defaults.yaml, .claude-plugin/plugin.json, Makefile.

Core Mandates

1. Config Convention: Ship defaults.yaml (committed) with reasonable defaults + config.yaml (gitignored override). Users create config.yaml only when they need overrides. Loader falls back: config.yaml > defaults.yaml > compiled Default impl. Never commit user-specific paths.

2. Separation of Concerns: Keep parsing logic "pure" (no I/O) in library modules. Let binaries handle the environment and file reads.

3. Lazy Compilation: Use bin/_build.sh to compile binaries on first hook invocation, ensuring low overhead.

4. Validation Driven: Always provide a VERIFY.md that allows an AI agent to confirm the module is functional without manual intervention.

Three-Layer Architecture

Every module addresses one or more of these concerns:

Layer	Question	Examples
Identity	Does it store user-specific knowledge?	forge-avatar (goals, preferences, beliefs)
Behaviour	Does it change how the AI responds?	forge-steering (rules), forge-tlp (access control)
Knowledge	Does it provide new tools or skills?	forge-council (specialists), forge-core (build skills)

Don't mix layers. Rules go in behaviour modules. Skills go in knowledge modules. User data goes in identity modules.

module.yaml

name: forge-example
version: 0.1.0
description: One-line description of what this module does.
events: []
platforms: []

events: [] means no hooks. For hook-using modules, list the events:

events: [SessionStart, PreToolUse, Stop]

platforms: [] means all platforms (default). For platform-restricted modules:

platforms: [macos]  # skip Windows/Linux checks in INSTALL.md validation

defaults.yaml

# Module-specific configuration.
# Override: create config.yaml (gitignored) with only the fields you want to change.

skills:
    claude:
        SkillName:
    gemini:
        SkillName:
    codex:
        SkillName:
    opencode:
        SkillName:

agents:
    AgentName:
        model: fast
        tools: Read, Grep, Glob

providers:
    claude:
        fast: claude-sonnet-4-6
        strong: claude-opus-4-6
    gemini:
        fast: gemini-2.0-flash
        strong: gemini-2.5-pro
    codex:
        fast: o4-mini
        strong: o4-mini
    opencode:
        fast: claude-sonnet-4-6
        strong: claude-opus-4-6

The skills: section uses provider-keyed allowlists. forge install reads this to decide which skills deploy to which provider. Skills omitted from a provider's list are skipped. This allows Claude-only skills (e.g., those using agent teams) to be excluded from Gemini/Codex without per-skill configuration.

Critical: The providers: section drives agent deployment. forge install reads provider keys from this section to determine target directories. A provider missing from providers: means agents will NOT deploy there, even if the agents: section is correct.

plugin.json

{
    "name": "forge-example",
    "version": "0.1.0",
    "description": "Module description.",
    "author": {"name": "Author Name"},
    "skills": ["./skills"]
}

Add "hooks": "./hooks/hooks.json" only if the module has hooks.

Makefile Pattern

Modules use the forge CLI for install, verify, and validate targets:

AGENTS   = AgentName
SKILLS   = SkillOne SkillTwo SkillThree
AGENT_SRC = agents
SKILL_SRC = skills

.PHONY: help install clean verify test lint check

install:
	forge install

clean:
	forge clean

verify:
	forge verify

test:
	forge validate $(CURDIR)

lint: lint-schema lint-shell

SKILLS variable: Lists skills for verification and cleanup only. forge install reads defaults.yaml directly to decide what deploys where. Provider-specific skills (e.g., Claude-only) should be excluded from the global SKILLS list since verify checks all providers. The skill will still install correctly via defaults.yaml.

For skills-only modules (no agents), omit AGENTS, AGENT_SRC, and the agent mk includes.

Provider Documentation

Every module ships platform-specific instruction files at its root:

File	Platform	Generate	Reference
CLAUDE.md	Claude Code	claude (manual or /init)	--
AGENTS.md	Codex, OpenCode	codex init / opencode init	@CodexProvider.md, @OpenCodeProvider.md
GEMINI.md	Gemini CLI	gemini init	@GeminiProvider.md

Generate these files by running each platform's CLI init command inside the module directory. The CLI analyzes the codebase and produces platform-appropriate instructions. To update an existing file, rename it to .bak, re-run init, and diff.

These files are the primary way AI agents understand the module when working inside it. Generate them after the module structure is complete and before first commit.

Validation Flow

1. Unit Tests: cargo test (or equivalent) for Rust modules
2. Module Conventions: forge validate . checks structure
3. Skill Verification: make verify confirms deployment
4. Binary Availability: Check binaries respond to --help or --version

Validate

@ModuleStructure.md

Constraints

• ALL CAPS filenames = system-provided (SYSTEM.md, CONVENTIONS.md). Title Case = user-authored.
• config.yaml is always gitignored at every level
• The forge CLI provides install, validate, and assembly operations
• Modules must work standalone -- no dependency on a parent monorepo