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