hermesd: Skill for Codex

This skill complements AGENTS.md, .codex/rules/python-patterns.md, and .codex/rules/python-idioms.md. It must stay aligned with all three and applies as an execution discipline layer on top of the project's Python standards.

This skill adds execution rigor:

• ATDD/TDD workflow
• SRP, DRY, and OCP decision rules
• explicit dependency injection discipline with a pragmatic carve-out for CLI composition roots
• strict type discipline
• comment quality standards
• structured implementation and review checks
• hermesd-specific invariants (cache-preservation, read-only access, panels as OCP seam)

If AGENTS.md is stricter on any point, follow AGENTS.md.

<when_to_use> Use this skill when:

• implementing a new feature or behavior increment
• refactoring Python code for clearer ownership or testability
• reviewing module boundaries or dependency flow
• replacing hidden collaborator construction with explicit injection
• tightening tests around user-visible or integration behavior
• removing Any types or tightening weak types in touched code
• cleaning up hardcoded values or global mutable state </when_to_use>

1. Inspect the project first. Read pyproject.toml, project layout, local AGENTS.md, CONTRIBUTING.md, CHANGELOG.md, tool configs ([tool.ruff], [tool.mypy], [tool.pytest.ini_options]), and existing tests.

2. Define acceptance behavior first. Express the user-visible outcome before writing implementation details.

3. Add or update an acceptance-level test when the project has that layer. For hermesd, the acceptance seam is Collector → DashboardState → panel renderer. Use rich.console.Console(record=True) to capture output for end-to-end render assertions.

4. Add the next smallest failing test. Prefer a focused unit or module test for the next behavior increment.

5. Implement the minimum change that makes the test pass. Keep the diff tight. Do not rewrite unrelated code.

6. Refactor while green. Improve naming, cohesion, dependency flow, and readability without changing behavior.

7. Keep standards and user-facing docs in sync. If the task materially changes project conventions, architecture, or workflow expectations, update AGENTS.md or the relevant rule/skill in the same change. Update CHANGELOG.md for user-visible changes and README.md when install/usage instructions change.

8. Verify locally before opening a PR. Run uv run ruff check ., uv run ruff format --check ., uv run mypy hermesd, uv run pytest tests/ -v -W error::ResourceWarning, uv run pip-audit, uv lock --check, uv build, wheel smoke installs, and uvx twine check dist/*. CI runs the same gate commands across Python 3.11/3.12/3.13.

<design_rules> Apply these rules during implementation:

• Keep project structure clean and predictable
• SRP: each module, class, and function should have one clear reason to change
• DRY: remove repeated validation, mapping, branching, and policy logic when the abstraction improves clarity
• OCP: extend behavior through composition, Protocols, configuration, and strategy injection instead of invasive branching or copy-paste forks
• Prefer domain-oriented module boundaries over technical dumping grounds
• Keep domain logic separate from transport, persistence, configuration, and presentation concerns
• Prefer the smallest coherent abstraction that solves the real duplication or extension point
• Do not introduce Protocol-first abstractions without real consumer pressure
• Prefer composition over inheritance; keep inheritance hierarchies shallow

OCP example in hermesd. hermesd/panels/__init__.py is the canonical OCP seam: add a new panel by writing hermesd/panels/your_panel.py, adding a _render_your_panel(ctx: PanelRenderContext) wrapper, then registering that wrapper in _RENDERERS and the label in PANEL_NAMES. This pattern is documented in CONTRIBUTING.md#Adding a New Panel. </design_rules>