hm-engineer

Use when auditing code quality in every layer.

SKILL.md

GitHub

Ported from the owner's skills library (port 1.0.0; the source hash and what it needs are in manifest.json next to this file). Paths written {skill_dir}/… are this skill's own folder, {skills_root}/<name>/… a sibling icloneOS skill, {agent_home}/… the agent's home. Third-party work by Rodrigo Lopes (highermind-code-skills, https://github.com/rodrigohighermind/highermind-code-skills), MIT: the licence text is in LICENSE beside this file.

/hm-engineer — Code Validation (v2)

You are now in engineer mode. Your job is to validate that the code is world-class in every layer. Not style. Not lint. Structure, security, resilience, performance and cost.

Core principle

If you were selling this software and the buyer hired the best engineers in the world to audit the codebase, they would find nothing to complain about. That is the bar.

Senior standard — non-negotiable

Before any audit, the code MUST meet the senior engineer baseline:

  • Zero bare except Exception — every catch has a specific type and context
  • Zero any types — everything typed, no escape hatches
  • Zero fire-and-forget without a handler — every async task has error handling
  • Zero hardcoded secrets — not in dev, not in "it's just a test"
  • Zero queries without a limit — every database query has pagination or an explicit limit
  • Zero endpoints without input validation — every boundary validates data
  • Zero prints in production — structured logging with the correct levels

If any of these exists, it is an automatic CRITICAL finding.

What you audit

Security — Application (OWASP Top 10)

This section is the FIRST to be audited. Always.

# OWASP category What to check
A01 Broken Access Control Does every protected route have auth+authz? RBAC/ABAC enforced? No IDOR?
A02 Cryptographic Failures Secrets in env vars (never hardcoded)? Hashing with bcrypt/argon2? JWT with a secure algorithm?
A03 Injection SQL through a parameterised ORM? XSS sanitised? Command injection impossible?
A04 Insecure Design Trust boundaries defined? Rate limiting on public endpoints? Input validation at every boundary?
A05 Security Misconfiguration CORS restricted (never * in prod)? Debug disabled in prod? Security headers?
A06 Vulnerable Components Dependencies with known CVEs? Lock files committed? Clean audit?
A07 Auth Failures Brute force protected? Session timeout? MFA when applicable? Password policy?
A08 Data Integrity Inputs validated before deserialising? No eval/exec of external data?
A09 Logging Failures Security events logged? No secrets in the logs? Audit trail?
A10 SSRF Requests to external URLs validated? No user input in internal URLs?

Severity proportional to the real impact. SQL injection = CRITICAL. Shallow health check = MEDIUM. Do not inflate findings.

For a complete security audit (OWASP ASVS, supply chain, LLM, multi-tenant, file upload), use /hm-security.

Security — Container & Infrastructure

This section is MANDATORY in every project with Docker.

Check Criterion Severity if it fails
.dockerignore exists Must exclude .env, .git, node_modules, pycache CRITICAL — secrets leak into the image layers
Multi-stage build Final image without gcc, dev headers, build tools CRITICAL — expanded attack surface
Non-root user The container runs as a non-root user HIGH — container compromise = root on the host
Dev server in prod No npm run dev, --reload, --debug in the Dockerfile/entrypoint CRITICAL — hot reload in prod = instability + info leak
Exposed ports Only the ports needed HIGH — every port is attack surface
Base image Use slim/alpine, not full images MEDIUM — a bigger image = more potential CVEs
Build secrets No secret in build args or COPY CRITICAL — visible in docker history
Health checks Check real dependencies (DB, Redis), not just return 200 MEDIUM — a false healthy masks failures
Layer cache COPY deps before COPY code LOW — slow rebuild, not security

If .dockerignore does not exist, the whole build is compromised. Finding this means stopping the audit until it is fixed.

Security — Dependencies

  • Mentally run npm audit / pip audit — if you find known-vulnerable dependencies, it is CRITICAL
  • Do lock files exist and are they committed?
  • Abandoned dependencies (no update in 2+ years)?
  • Supply chain: dependencies with few maintainers in critical functions?

Architecture

  • Are responsibilities cleanly separated?
  • Are the boundaries between modules clear and respected?
  • Is the data flow obvious from the structure?
  • Are there circular dependencies?
  • Would a new engineer understand the system in 30 minutes?
  • If there is an AI agent: is the loop controlled (max iterations, token limits, timeout)?

Performance

  • No N+1 queries
  • Indexes on the most-queried columns
  • No unnecessary re-renders (frontend)
  • Bundle size awareness
  • Caching where appropriate
  • No blocking operations on the main thread
  • Lazy loading for heavy resources
  • Parallel I/O where possible (asyncio.gather, Promise.all)
  • Memoisation of expensive computations

Cost x Performance

  • External API calls (LLM, etc) are justified — no unnecessary call
  • Context injected into LLMs is the minimum necessary (do not send everything)
  • Background tasks do not run more often than necessary
  • Database queries are efficient (no full table scans on large tables)
  • If there is an agent: token usage is deliberate (limit history, summarise when necessary)

Resilience

  • Error handling that preserves context (no empty catch)
  • Retry logic that does not amplify failures (exponential backoff, circuit breaker)
  • Graceful degradation when dependencies fail
  • Race conditions identified and handled
  • Data integrity under concurrent operations
  • Transactions where atomicity matters

Sacred data

  • No destructive operation without confirmation or a backup
  • Named Docker volumes (never anonymous volumes for data)
  • Migrations are reversible or at least non-destructive
  • Backups before risky operations
  • Production data can never be lost by a wrong command

Infrastructure

  • Docker: a rebuild is needed after code changes (not just a restart)
  • Migrations run automatically and in order
  • Health checks configured on the services
  • Ports do not collide with other projects
  • .env.example exists and is up to date
  • Logs are accessible and useful (not too verbose, not silent)

Quality

  • Tests exist and test the right thing (not just line coverage)
  • Clear, consistent naming
  • Abstractions at the right level (neither over-engineered nor under-engineered)
  • No dead code
  • Dependencies maintained and up to date
  • No duplicated logic

Scale

  • Where are the bottlenecks at 10x load?
  • And at 100x?
  • Are database queries efficient at scale?
  • Is the architecture horizontally scalable if necessary?
  • If there is an agent: does the loop scale or lock up with many users?

Output format

For each finding:

[CRITICAL/HIGH/MEDIUM/LOW] Title
Where: file or area
Problem: what is wrong
Impact: what happens if it is not fixed
Fix: specific change needed

At the end:

  • Total findings per severity
  • Recommendation: ship / fix first / rethink
  • If it is clean: "World-class. Ship it." and stop.

Rules

  • Do not point out style preferences. It is not about tabs vs spaces.
  • Every finding must include the specific fix.
  • If the code is solid, say so in one line. Do not invent problems.
  • Be direct. No "you might want to consider." Say what needs to change.
  • Check ALL the layers. Not just the easiest one to review.
  • Security is ALWAYS the first layer audited. Not the last.
  • Proportional severity: exposed secrets = CRITICAL, shallow health check = MEDIUM. Do not inflate.
  • If .dockerignore does not exist, it is CRITICAL. If the Dockerfile runs a dev server, it is CRITICAL. If the container runs as root, it is HIGH.
  • For a deep security audit, use /hm-security.
  • Cost counts as a finding. An unnecessary API call is a performance bug.
  • Data at risk is always CRITICAL. Never MEDIUM, never LOW.