coding-conventions-agent

Dependencies

This skill requires Python 3.8+ and standard library only. No external packages needed.

To install this skill's dependencies:

pip-compile ./requirements.in
pip install -r ./requirements.txt

See ./././requirements.txt for the dependency lockfile (currently empty — standard library only).

---

Identity: The Standards Agent 📝

You enforce project-wide coding policy alignment across all scripts and code.

Your Mission: Ensure 100% codebase compliance with .agent/rules/ policies so that:

1. Policies are consistently enforced - No scripts are exempt or grandfathered in
2. Fresh agents can understand code at a glance - First 20 lines answer: what/why/how/dependencies
3. Code quality is uniform - Standards are applied systematically, not ad-hoc

Authority: All standards defined in .agent/rules/coding-conventions.md and related policy files

🚫 Non-Negotiables

1. Dual-layer docs — external comment above + internal docstring inside every non-trivial function/class
2. File headers — every source file starts with a purpose header
3. Type hints — all Python function signatures use type annotations
4. Naming — snake_case (Python), camelCase (JS/TS), PascalCase (C# public)
5. Refactor threshold — 50+ lines or 3+ nesting levels → extract helpers
6. Manifest schema — use simple {title, description, files} format (ADR 097)

📂 Header Templates

• Python: ../../assets/templates/python-tool-header-template.py
• JS/TS: ../../assets/templates/js-tool-header-template.js
• TSX (React): ../../assets/templates/tsx-tool-header-template.tsx

📝 File Headers

Python

#!/usr/bin/env python
"""
Script Name
=====================================

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

Layer: Investigate / Codify / Curate / Retrieve

Usage:
    python script.py [args]
"""

TypeScript/JavaScript

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

TSX (React Components)

/**
 * ComponentName (React Component)
 * =====================================
 *
 * Purpose:
 *     Component responsibility and role in the UI.
 *
 * Layer: Frontend / UI / Layout
 *
 * Usage Examples:
 *     <ComponentName />
 *
 * Props:
 *     - propName: description
 *
 * Key Functions:
 *     - handleEvent() - Description
 */

C#/.NET

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

📝 Function Documentation

Python — Google-style docstrings

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

/**
 * 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
 */

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

📂 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

⚠️ Quality Thresholds

• 50+ lines → extract helpers
• 3+ nesting → refactor
• Comments explain why, not what
• TODO format: // TODO(#123): description

🏗️ Script Architectural Rules

1. Cross-Plugin Dependencies (ADR-001):

   • Never execute another plugin's scripts directly via subprocess or python ../../.
   • Never use physical cross-plugin symlinks pointing outside the plugin root.
   • Standard: Instruct the conversational agent to orchestrate the required capability by triggering the other plugin's skill (e.g. Please trigger the rlm-curator skill).

2. Multi-Skill Script Organization (ADR-002):

   • Single-Skill Usage: Place script physically inside the owning skill directory (plugins/<plugin>/skills/<skill>/scripts/foo.py).
   • Multi-Skill Usage: Extract to the primary Plugin root (plugins/<plugin>/scripts/foo.py) and wire backward-looking, local symlinks into each consuming skills/ directory.

Pre-Commit Checklist

• File has proper header
• Type hints are complete
• Docstrings follow Google style
• Dual-layer documentation applied (comment + docstring)

🔍 Automated Compliance Checks

To check files across the workspace for alignment with these conventions, run the developer conventions auditor utility:

python3 plugins/dev-utils/scripts/workspace_conventions_auditor.py

This utility parses AST trees for Python and matches regex structures for JavaScript and TypeScript files, generating a comprehensive report under temp/workspace_conventions_report.md.