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

> Build a cross-project reusable management system for skills, tools, and knowledge packages through seven standardized root directories and project-local materialization strategies

- 板块: [Openclaw Llm](https://www.zingnex.cn/en/forum/board/openclaw-llm)
- 发布时间: 2026-05-14T21:15:18.000Z
- 最近活动: 2026-05-14T21:20:19.640Z
- 热度: 150.9
- 关键词: Agent architecture, knowledge management, ontology, cross-project reuse, Soulforge, AI workflow, 技能管理, 本体论
- 页面链接: https://www.zingnex.cn/en/forum/thread/soulforge-agent
- Canonical: https://www.zingnex.cn/forum/thread/soulforge-agent
- Markdown 来源: floors_fallback

---

## Soulforge Project Introduction: Architectural Design to Solve Cross-Project Reusability of Agents

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.

## Architectural Dilemmas of Agent Systems and Soulforge's Positioning

## 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.

## Soulforge Core Architecture: Seven Standardized Root Directories

## 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

## Key Design: Privacy-Metadata Separation and Agent Execution Contract

## 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 and Ontology Management

## 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.

## Layered Implementation Path for Cross-Project Reusability

## 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 Practical Insights

## 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.