Standards v1.0

AgentForge™ Standards v1.0

Status: Stable (v1.0)
Scope: Project structure, naming, lifecycle, and command conventions for AgentForge-based agents.

---

1. Purpose & Scope

The AgentForge™ Standards define how intelligent agents, data, and supporting assets are organized, named, and governed across projects. These standards are designed to:

• Ensure agents are portable, auditable, and reproducible.
• Provide a consistent A–F project hierarchy for files and folders.
• Align all agents to a shared command and lifecycle model.
• Support long-term change management and versioning.

1.1 Audience

These standards are intended for:

• Developers and builders creating AgentForge-compliant agents.
• Technical leads responsible for governance and promotion of agents.
• Teams integrating AgentForge projects into larger systems or workflows.

1.2 Relationship to CDC

AgentForge builds on the original Chatbot Design & Control (CDC) framework. All AgentForge agents are expected to:

• Respect CDC-style command prefixes (e.g., #COMMAND style controls).
• Document key behaviors and guarantees in plain language.
• Support diagnostics, export, and indexing via shared utilities (CEUA, CIUA, etc.).

---

2. Project Structure (A–F Model)

Every AgentForge project must follow the A–F folder model at its root:

/Projects/YourProjectName/
  A-Agents/
  B-Storage/
  C-Documents/
  D-SpecialMedia/
  E-Outputs/
  F-Integrations/
  INDEX.yaml (optional global index)
  

2.1 A-Agents/

Contains all agent definitions, prompts, and configuration files.

• Each agent lives in its own subfolder: A-Agents/AgentName/

A-Agents/
  RootAgent/
    README.md
    AGENT.yaml
    PROMPTS.md
    INDEX.yaml
    CHANGELOG.md
    TESTS.md
  SummarizerAgent/
  DiagnosticsAgent/
  RUNMATHAgent/
  

2.2 B-Storage/

Structured data used by agents:

• CSV, JSON, XML, SQL dumps, or other tabular/structured formats.
• Subfolders by logical domain (e.g., ReferenceData, Lookups, TestData).

2.3 C-Documents/

Human-readable documentation and design assets:

• Standards, manuals, whitepapers, design notes, training materials.
• Markdown or word-processor files (e.g., .md, .docx, .pdf).

2.4 D-SpecialMedia/

Non-text assets referenced by agents or docs:

• Images, diagrams, icons, audio, video, slide graphics, etc.
• Organized into subfolders such as Images/, Video/, Audio/.

2.5 E-Outputs/

Generated content:

• Reports, exports, logs, PDFs, and other agent-generated artifacts.
• Can be cleared, archived, or rotated according to retention policies.

2.6 F-Integrations/

Integration-specific assets:

• API specs, client configs, connector scripts, environment examples.
• Subfolders by platform or integration: OpenAI/, GitHub/, SAS/, Cloud/, etc.

---

3. Agent Structure & Required Files

Each AgentForge agent folder under A-Agents/ must contain the following canonical files:

3.1 Required Files

• AGENT.yaml – Core definition and metadata.
• README.md – Human-readable overview and quick start.
• PROMPTS.md – System prompts, role definition, key instructions.
• INDEX.yaml – Local index of files, references, and dependencies.
• CHANGELOG.md – History of changes, versions, and promotion notes.
• TESTS.md – Manual or automated test scenarios and expected behaviors.

3.2 Optional Files

• PLAYBOOK.md – Operational runbooks and usage patterns.
• POLICY.md – Constraints, approvals, or domain-specific rules.
• EXAMPLES.md – Worked examples or conversation snippets.

3.3 Minimal Agent Checklist

• Clear purpose and scope in README.md.
• Well-structured system prompt in PROMPTS.md.
• Agent metadata in AGENT.yaml (name, version, owner, status).
• At least one diagnostic test in TESTS.md.
• At least one entry in CHANGELOG.md describing the current version.

---

4. File Naming & Versioning

4.1 Agent Naming

• Use descriptive, PascalCase names: RootAgent, SummarizerAgent, DiagnosticsAgent.
• Avoid ambiguous or generic names like Helper, Bot1, TestAgent for production.

4.2 Semantic Versioning

All agents must use semantic versioning in AGENT.yaml and CHANGELOG.md:

• MAJOR – Breaking changes to behavior, commands, or structure.
• MINOR – New capabilities added, backward-compatible.
• PATCH – Small fixes, clarifications, or non-breaking improvements.

Example: version: 1.0.3

4.3 File Naming Conventions

• Use clear, descriptive names and avoid spaces where possible.
• Prefer kebab-case or PascalCase for files and folders.
• Examples: agentforge-one-pager.pdf, agentforge-standards-v1.pdf.

---

5. Command & Control Standards (High-Level)

AgentForge adopts a CDC-style command model, where control commands are clearly marked and separated from user content.

5.1 Command Prefixes

• Commands must be clearly prefixed, typically with # (e.g., #RUNMATH, #DIAG).
• Commands should be documented in the project-level or agent-level Commands Reference.

5.2 Core Command Categories

• Initialization & Context – e.g., #INIT for project or agent setup.
• Diagnostics & Health – e.g., #DIAG to check behavior or configuration.
• Math & Utilities – e.g., #RUNMATH to run deterministic calculations.
• Export & Index – e.g., #EXPORT, #INDEX for CEUA/CIUA utilities.

A full, detailed list of commands lives in the separate Commands Reference document and page.

---

6. Lifecycle & Promotion

All AgentForge agents follow a simple lifecycle to ensure quality and traceability.

6.1 Lifecycle States

• Draft – Initial design, unstable, active iteration.
• Review – Under testing and peer review.
• Stable – Approved for normal use, documented and tested.
• Deprecated – Kept for reference, not recommended for new usage.

The current lifecycle state must be recorded in AGENT.yaml and reflected in CHANGELOG.md.

6.2 Promotion Checklist (Draft → Stable)

Before an agent is promoted to Stable, the following must be true:

• Purpose and scope clearly documented in README.md.
• PROMPTS.md is clean, consistent, and free of conflicting instructions.
• TESTS.md includes at least 3–5 representative scenarios with expected outcomes.
• CHANGELOG.md includes the promotion entry with date and summary of changes.
• INDEX.yaml updated with current file list and dependencies.
• Any external dependencies in B-Storage, D-SpecialMedia, or F-Integrations are documented.

---

7. Governance & Change Management

7.1 CHANGELOG Standards

Each agent’s CHANGELOG.md should include:

• Version number and date.
• Lifecycle state (e.g., Draft, Review, Stable).
• Short summary of changes made.
• Optional: reviewer or approver name/role.

7.2 INDEX.yaml Standards

Each agent’s INDEX.yaml should, at minimum, track:

• Agent name and version.
• Key files and their roles.
• References to storage, media, or integrations used.
• Any known dependencies on other agents.

7.3 Documentation Expectations

• All production (Stable) agents must have a complete README.md.
• All non-trivial behavior must be described in PROMPTS.md and/or EXAMPLES.md.
• Complex projects should use C-Documents/ for extended manuals and design notes.

---

8. Compatibility & Future Versions

8.1 Backward Compatibility

New versions of these standards (v1.1, v2.0, etc.) will:

• Preserve the A–F project structure as the core model.
• Maintain existing file naming expectations where possible.
• Clarify or extend rules rather than introduce surprises.

8.2 Extension Points

Teams may extend these standards if they:

• Document additions or overrides in C-Documents/ (e.g., local-standards.md).
• Do not break the A–F structure or semantic versioning expectations.
• Keep core AgentForge semantics intact for portability and governance.

---

9. Summary

AgentForge Standards v1.0 provide a practical, enforceable baseline for structuring agent projects, maintaining clarity, and supporting long-term governance. By following the A–F model, semantic versioning, and clear lifecycle rules, teams can create agents that are easier to share, audit, and improve over time.