architecture-template

A documentation skill for creating consistent architecture documentation for AI agent projects.

Overview

This skill provides a standardized template and tooling for documenting the architecture of AI agent systems. It ensures consistency, completeness, and maintainability across projects.

Why?

• Consistency: All projects follow the same structure
• Completeness: Template ensures nothing is forgotten
• Maintainability: Easy to update and track changes
• Onboarding: New team members understand the system faster

Quick Start

For Humans

# Clone the skill
git clone https://forgejo.tail593e12.ts.net/noopsec/architecture-template.git

# Copy template to your project
cp architecture-template/TEMPLATE.md my-project/ARCHITECTURE.md

# Edit and fill placeholders
# Use bot/validator.py to validate
python3 architecture-template/bot/validator.py my-project/ARCHITECTURE.md

For Bots/Agents

# Load and use template
from architecture_template import TemplateParser, Validator

parser = TemplateParser("TEMPLATE.md")
placeholders = parser.get_placeholders()

# Fill with project data
filled = parser.fill({
    "PROJECT_NAME": "MyAgent",
    "VERSION": "1.0.0",
    # ... more fields
})

# Validate
validator = Validator()
result = validator.validate(filled)
assert result.valid

Structure

architecture-template/
├── SKILL.md                          # Skill definition
├── TEMPLATE.md                       # The architecture template
├── README.md                         # This file
│
├── bot/
│   ├── USAGE.md                     # Detailed usage guide for bots
│   ├── parser.py                    # Template parser (reference)
│   └── validator.py                 # Validation tool
│
├── schemas/
│   └── module-schema.json           # JSON schema for modules
│
├── examples/
│   ├── minimal/                     # Minimal working example
│   └── full/                        # Comprehensive example
│
└── tests/
    └── test_architecture_template.py # Unit tests

Features

Template Features

• Standardized Structure: 8 main sections covering all aspects
• ASCII Diagrams: Visual architecture representations
• Placeholder System: Easy to fill with {{PLACEHOLDER}} syntax
• Status Tracking: Built-in status indicators (🟢🟡🔴)

Bot Features

• Parser: Extract and categorize placeholders
• Validator: Check for completeness and security issues
• Window Management: Strategy for large templates
• Section-based Editing: Work on parts independently

Security Features

• Credential Detection: Warns about possible leaked secrets
• Validation Rules: Ensures no real data in examples
• Fail-Closed Design: Rejects if uncertain

Usage Examples

Generate from Scratch

from pathlib import Path
from bot.parser import TemplateParser
from bot.validator import TemplateValidator

# Load template
parser = TemplateParser("TEMPLATE.md")

# See what needs to be filled
print("Required fields:")
for placeholder in parser.get_placeholders():
    print(f"  - {placeholder}")

# Fill template
data = {
    "PROJECT_NAME": "MyAwesomeAgent",
    "VERSION": "1.0.0",
    "DATE": "2026-02-20",
    "BRIEF_DESCRIPTION": "An agent that automates tasks",
    # ... fill all required fields
}

filled = parser.fill(data)

# Validate
validator = TemplateValidator()
result = validator.validate(filled)

if result.valid:
    Path("ARCHITECTURE.md").write_text(filled)
    print("✅ Generated successfully!")
else:
    print("❌ Validation errors:", result.errors)

Validate Existing Document

# Command line
python3 bot/validator.py ARCHITECTURE.md

# With strict mode (warnings = errors)
python3 bot/validator.py ARCHITECTURE.md --strict

# JSON output for automation
python3 bot/validator.py ARCHITECTURE.md --json

Parse for Analysis

from bot.parser import TemplateParser

parser = TemplateParser("ARCHITECTURE.md")

# Get placeholders by section
sections = parser.get_placeholders_by_section()
for section, placeholders in sections.items():
    print(f"{section}: {len(placeholders)} placeholders")

# Get statistics
stats = parser.get_template_stats()
print(f"Total lines: {stats['total_lines']}")
print(f"Sections: {stats['section_count']}")

Development Standards

This skill follows Hermes' dev-standards:

• File Size: Max 200 lines per tool file
• Error Handling: Propagate errors, don't swallow them
• Logging: Use logging module, not print
• Testing: unittest in tests/ directory
• Documentation: Docstrings for all public functions

Security Considerations

Template Safety

• Templates contain only placeholders, no real data
• Examples use neutral data (example.com, MyProject)
• Validator checks for credential patterns

Validation Checks

• Unfilled placeholders detection
• Possible credential leak detection
• Structure completeness check
• Security section presence check

Testing

# Run all tests
python3 -m unittest tests/test_architecture_template.py -v

# Test specific component
python3 -m unittest tests.test_architecture_template.TestTemplateParser -v

# Run parser directly
python3 bot/parser.py TEMPLATE.md

Contributing

1. Fork the repository
2. Create feature branch
3. Make changes following dev-standards
4. Add tests
5. Validate with validator
6. Submit pull request

Integration

As Cobot Skill

# In your Cobot setup
plugins:
  external:
    - architecture-template

# Then in chat
/arch-template generate
/arch-template validate docs/ARCHITECTURE.md

As Standalone Tool

# Add to PATH
export PATH=$PATH:/path/to/architecture-template/bot

# Use anywhere
validator.py my-project/ARCHITECTURE.md

Examples

See examples/ directory:

• minimal/: Small agent system (~50 lines filled)
• full/: Complex multi-service system (~200 lines filled)

Roadmap

• Visual diagram generation (Mermaid)
• Interactive web editor
• Version diff tool
• More specialized templates (microservices, embedded, etc.)

License

MIT License - See LICENSE file

Contact

• Repository: https://forgejo.tail593e12.ts.net/noopsec/architecture-template
• Issues: Create issue in Forgejo

---

This skill is part of the Cobot ecosystem but can be used standalone.