Coding Conventions

Dual-Layer Documentation

Every non-trivial code element needs two layers:

• External comment/header — scannable description above the definition

• Internal docstring — detailed docs inside the definition

File Headers

Every source file starts with a header describing its purpose.

Python Files

#!/usr/bin/env python3 """ Script Name

Purpose: What the script does and its role in the system.

Layer: Investigate / Codify / Curate / Retrieve

Usage: python script.py [args]

Related: - related_script.py """

For CLI tools in plugins/ , use the extended format with Usage Examples, CLI Arguments, Key Functions, and Script Dependencies sections. See references/header_templates.md

for the full gold-standard template.

TypeScript/JavaScript Files

/**

• path/to/file.js
• ================
• Purpose:
• Component responsibility and role in the system.
• Key Functions/Classes:
• • functionName() - Brief description */

C#/.NET Files

// path/to/File.cs // Purpose: Class responsibility. // Layer: Service / Data access / API controller. // Used by: Consuming services.

Function Documentation

Python — Google-style docstrings with type hints

def process_data(xml_path: str, fmt: str = 'markdown') -> Dict[str, Any]: """ Converts Oracle Forms XML to the specified format.

Args:
    xml_path: Absolute path to the XML file.
    fmt: Target format ('markdown', 'json').

Returns:
    Dictionary with converted data and metadata.

Raises:
    FileNotFoundError: If xml_path does not exist.
"""

TypeScript — JSDoc with @param , @returns , @throws

/**

• Fetches RCC data and updates component state.
• @param rccId - Unique identifier for the RCC record
• @returns Promise resolving to RCC data object
• @throws {ApiError} If the API request fails */ async function fetchRCCData(rccId: string): Promise<RCCData> {}

C# — XML doc comments

/// <summary> /// Retrieves RCC details by ID. /// </summary> /// <param name="rccId">Unique identifier.</param> /// <returns>RCC entity with related data.</returns> public async Task<RCC> GetRCCDetailsAsync(int rccId) {}

Naming Conventions

Language Functions/Vars Classes Constants

Python snake_case

PascalCase

UPPER_SNAKE_CASE

TS/JS camelCase

PascalCase

UPPER_SNAKE_CASE

C# PascalCase (public) PascalCase

PascalCase

C# private fields use _camelCase prefix.

Code Quality Thresholds

• 50+ lines in a function → extract helpers

• 3+ nesting levels → refactor

• Comments explain why, not what

• TODO format: // TODO(#123): description

Module Organization (Python)

module/ ├── init.py # Exports ├── models.py # Data models / DTOs ├── services.py # Business logic ├── repositories.py # Data access ├── utils.py # Helpers └── constants.py # Constants and enums

Tool Inventory Integration

All Python scripts in plugins/ must be registered in plugins/tool_inventory.json .

After creating or modifying a tool:

python plugins/tool-inventory/scripts/manage_tool_inventory.py add --path "plugins/path/to/script.py" python plugins/tool-inventory/scripts/manage_tool_inventory.py audit

The extended Python header's Purpose: section is auto-extracted for the RLM cache and tool inventory.

Pre-Commit Checklist

• File has proper header

• Script registered in plugins/tool_inventory.json

• manage_tool_inventory.py audit shows 0 untracked scripts

Manifest Schema (ADR 097)

For .agent/learning/ manifests, use the simple schema:

{ "title": "Bundle Name", "description": "Purpose of the bundle.", "files": [ {"path": "path/to/file.md", "note": "Brief description"} ] }