Soulforge: Agent Architecture and Ontology Design for Real-World Projects

Soulforge, initiated by SungYongMOON, addresses the issues of repeated wheel reinvention and lack of cross-project reuse mechanisms in current AI Agent development. It builds a cross-project reusable management system for skills, tools, and knowledge packages through seven fixed standardized root directories and project-local materialization strategies. It is not a specific Agent implementation but a clearly defined "design repository" aimed at providing unified organizational principles for Agent development.

Background: Architectural Dilemmas of Agent Systems

Current AI Agent development faces structural issues: each project repeats configuration of tools, skills, and workflows, lacking unified organizational principles and cross-project reuse mechanisms. Developers need to rebuild similar Agent capabilities when switching projects.

Soulforge is positioned as a "design repository" that provides an installable and reusable management system for skills, tools, knowledge packages, and workflows through seven standardized root directories and project-local materialization strategies.

Core Concept: Seven Standardized Root Directories

Soulforge architecture revolves around seven root directories with clear responsibilities:

• .registry: External specification storage, managing species definitions, role configurations, skill/tool/knowledge package entries, and ownership rules
• .unit: Owner of active Agent units, holding runtime identity and state
• .workflow: Independent orchestration specification, storing workflow definitions that can be migrated across scenarios
• .party: Reusable orchestration template, defining general collaboration patterns and team structures
• .mission: Holds task plans, including files like mission.yaml and readiness.yaml
• guild_hall: Cross-project operation hub, managing coordination components like gateway and town_crier
• _workspaces: Project-local materialization site, storing actual project files

Privacy and Metadata Separation: _workmeta

_workmeta is a private metadata repository nested under the Soulforge root, separated from _workspaces which stores actual files. Its benefits include:

• Separation of sensitive information (API keys) from code
• Runtime state does not pollute version control
• Support for multi-environment configuration for the same project

Agent Execution Contract

AGENT_EXECUTION_CONTRACT_V0.md defines Agent interaction rules:

• Assumption Exposure: Explicitly declare operation prerequisites
• Minimal Changes: Reduce unnecessary modifications
• Scope Editing: Operations are limited to clearly defined scopes
• Verification Standards: Standardize correctness verification of operations

Architecture Documentation System

Soulforge implements "design as code" through detailed documentation:

• PROJECT_MAP_V0.md: Single-page owner/folder/game loop map
• DEVELOPMENT_ROADMAP_V0.md: Development direction and priorities
• VISION_AND_GOALS.md: Vision, goals, and success criteria
• TARGET_TREE.md: Standardized target tree
• DOCUMENT_OWNERSHIP.md: Document ownership principles
• AGENT_EXECUTION_CONTRACT_V0.md: Agent interaction contract
• ONTOLOGY_MODEL_V0.md: Object/relationship model and storage rules
• ONTOLOGY_REVIEW_MANUAL_V0.md: Ontology review process

Ontology Model and Review

ONTOLOGY_MODEL_V0.md defines the object/relationship model, and ONTOLOGY_REVIEW_MANUAL_V0.md standardizes rules for review triggering, carry-over, and guild_master reminders, elevating architecture management to the conceptual level.

Implementation Path for Cross-Project Reusability

Soulforge achieves cross-project reusability through a layered strategy:

1. Specification Layer (.registry): Defines reusable species, roles, skills, etc.
2. Template Layer (.party/.workflow): Defines general orchestration patterns and processes
3. Instance Layer (_workspaces): Materializes specifications and templates in projects
4. State Layer (_workmeta): Manages project-specific private runtime state
5. Coordination Layer (guild_hall): Cross-project operation and state synchronization

This layered approach enables "write once, run anywhere": skills defined in .registry can be materialized in any project, and guild_hall ensures cross-project coordination.

Design Philosophy and Insights

Soulforge's design philosophy is "convention over configuration, specification-driven development", creating order through strict conventions. Insights for Agent platform teams:

• Clear boundaries support multi-team collaboration
• Standardized documentation ensures knowledge inheritance
• Ontological thinking elevates the abstraction level of architecture
• Privacy separation meets security requirements of production environments

Soulforge demonstrates the engineering direction of Agent architecture: achieving maintainable, reusable, and auditable systems through rigorous practices.