nelson: Instructions file for Claude Code

Nelson

Nelson is a Claude Code skill for coordinating agent work using Royal Navy terminology. It provides an eight-step operational framework: Sailing Orders, The Estimate, Battle Plan, Form the Squadron, Get Permission to Sail, Quarterdeck Rhythm, Action Stations, and Stand Down.

Key references

• docs/project_structure.md — full repository layout
• README.md — user-facing overview and quick start

Maintainability sensors

This repo has automated sensors that you (the agent) should run and read carefully before considering a task done. They're how the codebase gives you fast feedback about whether your changes are maintainable.

Active sensors

• Linter — ruff check. Config in pyproject.toml. AI-targeted thresholds (max-args=5, max-branches=10, max-statements=50, max-complexity=10, line-length=120). Each violation message is feedback — read it, don't just look at the line. Many rules accept a suppress-with-reason or threshold-bump instead of forcing a fix.

• Formatter — ruff format --check. Apply with ruff format before committing.

• Tests — run separately per directory because each has its own conftest.py:

  pytest skills/nelson/scripts/ -v
  pytest hooks/ -v
  pytest scripts/ -v
  

• Pre-commit — pre-commit run --all-files. Includes secret scanning (Gitleaks), Ruff, and standard hygiene. Install once with pre-commit install. If a hook fails, fix the underlying issue rather than passing --no-verify.

• CI — the same checks re-run on clean infra after push (see .github/workflows/ci.yml). Green locally + red in CI usually means environment drift (Python version, env vars, OS-specific paths).

Suppressing or bumping a sensor

You may suppress a rule or bump a threshold when the rule is clearly wrong for the situation. The reason is mandatory.

result = subprocess.run(  # noqa: S603 -- args are repo-internal paths, sys.executable is trusted
    [sys.executable, str(_SCRIPT), ...],
    ...,
)