Forge-core BuildModule

Design, build, and validate forge modules. USE WHEN create module, new module, scaffold module, validate module, check module, audit module, module structure, module conventions, module architecture.

install

source · Clone the upstream repo

git clone https://github.com/N4M3Z/forge-core

Claude Code · Install into ~/.claude/skills/

T=$(mktemp -d) && git clone --depth=1 https://github.com/N4M3Z/forge-core "$T" && mkdir -p ~/.claude/skills && cp -r "$T/skills/BuildModule" ~/.claude/skills/n4m3z-forge-core-buildmodule && rm -rf "$T"

manifest: skills/BuildModule/SKILL.md

source content

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

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.
Separation of Concerns: Keep parsing logic "pure" (no I/O) in library modules. Let binaries handle the environment and file reads.
Lazy Compilation: Use
```
bin/_build.sh
```
to compile binaries on first hook invocation, ensuring low overhead.
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

Unit Tests:
```
cargo test
```
(or equivalent) for Rust modules
Module Conventions:
```
forge validate .
```
checks structure
Skill Verification:
```
make verify
```
confirms deployment
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