Module Architect

Expert guide for creating robust Forge Framework modules. Focuses on the "Three-Layer Concern" architecture and ensures modules are portable across AI coding tools.

Module Structure

Every Forge module must follow this standard layout:

• •module.yaml — Metadata and event registration.
• •defaults.yaml — Default configuration with shared path support.
• •bin/ — Entry points or build scripts (e.g., _build.sh).
• •hooks/ — Bash scripts triggered by Forge events.
• •skills/ — AI instructions and steering content.
• •src/ — Source code (typically Rust) for module logic.
• •VERIFY.md — Post-installation checklist for AI agents.
• •ALL CAPS filenames = system-provided (SYSTEM.md, CONVENTIONS.md). Title Case = user-authored content.

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. •Path Resolution: Use forge-core utilities to resolve user paths relative to the vault root or CWD.
4. •Lazy Compilation: Use bin/_build.sh to compile binaries on first hook invocation, ensuring low overhead.
5. •Validation Driven: Always provide a VERIFY.md that allows an AI agent to confirm the module is functional without manual intervention.

Architectural Patterns

• •Identity Layer: Does this module store user-specific knowledge?
• •Behaviour Layer: Does it change how the AI responds or gates session flow?
• •Knowledge Layer: Does it provide new tools or skills?

Validation Flow

1. •Unit Tests: Run cargo test (or equivalent).
2. •Binary Availability: Check if binaries respond to --help or --version.
3. •Hook Dry-run: Simulate hook inputs (JSON via stdin or CLI args) and check the output JSON for correct decisions.