Document-Driven Development & Integrated Scoped Wiki

Concept & Purpose

Writing agent logic without clear specifications leads to AI "hallucinations" and inconsistent system structures. YAIFA enforces a "Documents First" paradigm:

Requirements, architecture layouts, and expected input data are written in standard Markdown files inside the project's integrated scoped wiki. The attached AI IDE (e.g. Cursor or VS Code equipped with YAIFA rules) reads these documents as direct semantic context. Instead of inventing structures, the AI acts as a system filler, populating predefined templates and code stubs based strictly on the wiki specification.

The YAIFA Method (Document-Supported MAS Construction)

The YAIFA method is the methodical core of the framework: a Multi-Agent System is built document-supported and with LLM assistance. A persisted model, versioning, and release gates support safe operation.

Principle	Meaning
Documents first	Specifications, Scoped Wiki (Project/Agent/Element) and planned data examples are machine-readable context for humans and LLM — not just a manual.
Structure before implementation	Agent dummies (skeletons, templates, draft agent.json) define rough structure, ports, relations, and data flows before business logic is complete.
LLM as filler	The LLM generates and supplements configuration and code within the YAIFA schema: classes, BDI rows, processing modules, business logic — Config first, Generator second.
Iterative Draft and Learn phases	Design (Draft) and Learn can be run through multiple times: refine structure → train → re-adjust — without re-inventing the entire agent.
Simulation as quality gate	The simulation phase verifies logic and MAS behavior and prepares production operation; on updates it is repeated (regression).
BDI as exchangeable layer	Beliefs, Desires, and Plans are versionable components — individual parts (e.g. only the plan) can be exchanged; old and new plan can coexist in a lineage until simulation and release secure the transition.
Classification at BDI hooks	Element Classes check structurally and at runtime whether adoption and plan selection are permissible — BDI becomes typed, not just textual.
Logging as learning loop	BDI Runtime Logs and business logs are feedback: evaluation leads to new Beliefs, Desires, Plans, and configuration changes — again via the same BDI and classification logic.
Executable BDI artifacts	BDI objects are not dumb text messages: Beliefs, Plans, and Port-Processing can be newly trained neural networks, Python programs, rules, and structured payloads — hybrid in the same template.

Guiding principle: Describe and scaffold (Documents + Dummies) → LLM fills classes and logic → Learn and Draft iterate → Simulation releases → Logs improve the model.

The Three-Layer Wiki Structure

The knowledge base of a YAIFA project is structured into three clear levels, providing hierarchical context for the AI developer loop:

Wiki Level	On-Disk Location	Role for the AI Assistant
1. Product Specification	documentation/wiki/	Global rules, validation parameters, and system boundary parameters.
2. Project Wiki	/Documentation/wiki/	General MAS architecture, active agent roles, and data flow topologies.
3. Agent / Element Wiki	<agent_dir>/Documentation/wiki/	Detailed descriptions of specific inputs, BDI slots, and expected processing steps.

Technology Focus — Manufacturer Independence

YAIFA focuses on Python, JSON, and YAML as normative artifacts. This keeps the system manufacturer-independent. LLMs can optimally support the development process because schema, generator, and common patterns are machine-readable. The user describes data and functionality in their preferred language. The LLM creates Python code from this, allowing arbitrary business logic and complex problem solving without limits of a visual sandbox.

Technical Realization

During the Design (Draft) phase, developers follow a standard workflow to create and deploy agents:

1. Write Specification: Draft the agent's responsibilities, input schemas, and plans inside the scoped Agent Wiki.
2. Create Skeleton: Create a basic agent.json config mapping only names and port outlines (manually or via a template).
3. Invoke AI Filler: Let the AI assistant read the Wiki and fill in the detailed agent.json parameters, BDI rules, and processing logic drivers.
4. Run Code Generation: Trigger the studio generator, compiling the verified agent.json config into executable Python driver templates.

The absolute source of truth remains the declarative config (agent.json) and the specification document, rather than chat logs or temporary prompt memories.