Imported from rakaarwaky/lint-arwaky (.agents/skills/lint-arwaky-python/SKILL.md). Install upstream with npx skills add rakaarwaky/lint-arwaky --skill lint-arwaky-python. Copyright stays with the author.

lint-arwaky-python — Complete Command & Argument Reference

Run lint-arwaky-cli scanner and MCP server for Python projects. Validates AES (Architecture Error Standards) compliance, checks layer violations, and helps fix architecture issues.

Shell Aliases

Shortcut aliases are available for fast terminal access (automatically added to ~/.bashrc / ~/.zshrc):

1. Global CLI Options

These options apply globally across all lint-arwaky-cli subcommands:

2. Complete Commands & Subcommands Reference

scan / check

Scans target Python workspace, discovers modules, and runs all linters.

# Basic scan (defaults to text format)
lint-arwaky-cli scan workspaces-bad/modules

# Scan with specific output format (text | json | sarif | junit)
lint-arwaky-cli scan workspaces-bad/modules --format json

# Filter scan results by rule code (e.g. AES201, AES401)
lint-arwaky-cli scan workspaces-bad/modules --filter AES201

# Save reports to custom directory
lint-arwaky-cli scan workspaces-bad/modules --format json --output-dir ~/.local/share/lint-arwaky/reports

Arguments & Flags:

• [PATH]: Target path to scan (defaults to current directory .).
• --format <FORMAT>: Output format (text, json, sarif, junit).
• --member <NAME>: Target single workspace member by module name.
• --filter <CODE>: Filter violations by AES rule ID.
• -o, --output-dir <DIR>: Output directory path to save report files.

fix

Applies safe automatic fixes to compliance violations across the codebase.

# Apply automatic fixes
lint-arwaky-cli fix modules/

# Preview changes without modifying files (Dry Run)
lint-arwaky-cli fix modules/ --dry-run

# Preview fixes for specific rule code
lint-arwaky-cli fix modules/ --dry-run --filter AES101

Arguments & Flags:

• [PATH]: Target path to fix (defaults to .).
• --dry-run: Perform a dry run showing diffs without modifying files.
• --filter <CODE>: Apply fixes only for a specific AES rule ID.

ci

Continuous Integration quality gate mode. Evaluates compliance score against a threshold.

# CI mode with default threshold
lint-arwaky-cli ci modules/

# CI mode with custom score threshold (exits with status 1 if score < 80)
lint-arwaky-cli ci modules/ --threshold 80 --format junit

Arguments & Flags:

• [PATH]: Target path (defaults to .).
• --threshold <SCORE>: Minimum acceptable quality score (0–100, default: 80).
• --format <FORMAT>: Output format (text, json, sarif, junit).

quality, import, naming, role, orphan, external

Run a single linter independently for targeted analysis.

# Run only naming rules
lint-arwaky-cli naming modules/

# Run only orphan detection with JSON output
lint-arwaky-cli orphan modules/ --format json

# Run orphan on a specific member
lint-arwaky-cli orphan modules/ --member animator

# Run only import rules
lint-arwaky-cli import modules/

# Run only role rules
lint-arwaky-cli role modules/

# Run only external linters (ruff)
lint-arwaky-cli external modules/

# Run only quality analysis
lint-arwaky-cli quality modules/

Arguments & Flags:

• [PATH]: Target path to scan (defaults to .).
• --format <FORMAT>: Output format (text, json, sarif, junit).
• --member <NAME>: (orphan only) Target specific workspace member.

security & dependencies

Scans for security vulnerabilities and library dependency CVEs.

# Scan code for security issues (Bandit, Cargo Audit, ESLint Security)
lint-arwaky-cli security modules/

# Scan Python library dependencies for vulnerabilities
lint-arwaky-cli dependencies modules/

watch

Monitors file system changes and re-runs linting automatically upon file save.

# Watch directory and re-lint on changes
lint-arwaky-cli watch modules/

install-hook & uninstall-hook

Manages Git pre-commit hook integration.

# Install git pre-commit hook
lint-arwaky-cli install-hook

# Uninstall git pre-commit hook
lint-arwaky-cli uninstall-hook

init & install

Initializes workspace configuration and installs linter adapter dependencies.

# Create default lint_arwaky.config.yaml in workspace
lint-arwaky-cli init

# Install required external linter tools (ruff, mypy, bandit, etc.)
lint-arwaky-cli install

config-show, adapters, & mcp-config

Displays workspace configuration and active integrations.

# Show active configuration tokens and rules
lint-arwaky-cli config-show

# List all active linter adapters (Ruff, Mypy, Radon, Bandit, etc.)
lint-arwaky-cli adapters

# Print MCP server configuration JSON for AI client integration
lint-arwaky-cli mcp-config

doctor & version

Environment diagnostic tools.

# Health check for Python tooling and environment
lint-arwaky-cli doctor

# Display binary version information
lint-arwaky-cli version

MCP Server Tools Reference (lint-arwaky-mcp)

lint-arwaky-mcp exposes 5 JSON-RPC 2.0 tools over STDIO for AI clients (Claude Code, Cursor, Windsurf, Hermes):

Example MCP JSON-RPC Payload

// execute_command: run Python scan
{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"execute_command","arguments":{"action":"scan","args":{"path":"workspaces-bad/modules"}}}}

// health_check: check Python adapters (ruff, mypy, bandit)
{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"health_check","arguments":{}}}

// get_config: retrieve Python architecture configuration
{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"get_config","arguments":{"language":"python"}}}

3. Report Redirection & XDG Storage

Output can be saved directly to the XDG reports directory (~/.local/share/lint-arwaky/reports/):

# Save JSON report
lint-arwaky-cli scan modules/ --format json > ~/.local/share/lint-arwaky/reports/scan_python.json

# Save SARIF report for GitHub Code Scanning
lint-arwaky-cli scan modules/ --format sarif > ~/.local/share/lint-arwaky/reports/scan_python.sarif

4. AES Rules for Python

Layer Import Rules (AES201)

ALLOWED:    taxonomy_*, contract_*
FORBIDDEN:  capabilities_*, agent_* (peer layers)

Protocol Requirements (AES403)

• Every capability class MUST inherit from protocol ABC
• Every agent class MUST inherit from aggregate ABC

Layer Boundaries (AES404)

5. Verification Checklist

• All layer imports follow AES201 rules
• All classes inherit appropriate protocol ABCs (AES403)
• No mixed responsibilities in layers (AES404)
• No magic constants in layers (AES405)
• Surface files follow role-based imports (AES406)

6. Scan → Diagnose → Fix → Verify Workflow

End-to-end workflow for an AI agent when asked to fix architecture violations in a Python codebase.

6.1 Pre-flight

# Verify Python environment works
python3 -c "import sys; print(sys.version)"

# Check that key dependencies are importable
python3 -c "import ruff; print('ruff ok')" 2>/dev/null || echo "ruff not installed"

6.2 Scan (detect all violations)

# Full scan — get total count and breakdown by rule
lint-arwaky-cli scan <target-path> --format json > /tmp/arwaky-scan.json

# Count total violations
cat /tmp/arwaky-scan.json | python3 -c "import sys,json; d=json.load(sys.stdin); print(f\"Total: {d.get('total_violations', len(d.get('violations', [])))}\")"

# Filter by severity — focus on CRITICAL first (AES201, AES205, AES304)
lint-arwaky-cli scan <target-path> --filter AES201
lint-arwaky-cli scan <target-path> --filter AES304

Priority order for fixes:

1. 🔴 CRITICAL: AES201 (forbidden import), AES205 (circular import), AES304 (bypass comment)
2. 🟡 HIGH: AES101–102 (naming), AES202 (mandatory import), AES301–303 (quality), AES401–403, AES406, AES505–506
3. 🟢 MEDIUM/LOW: AES203–204, AES305, AES404–405, AES501–504

6.3 Diagnose (understand each violation)

For each violation, read the affected file and determine:

6.4 Fix (apply changes)

Auto-fixable violations (use the CLI):

# Preview first
lint-arwaky-cli fix <target-path> --dry-run

# Fix all auto-fixable violations
lint-arwaky-cli fix <target-path>

# Fix specific rule
lint-arwaky-cli fix <target-path> --filter AES101
lint-arwaky-cli fix <target-path> --filter AES304

Manual fixes (by violation type):

6.5 Verify (confirm all clean)

# 1. Re-scan — should show 0 violations
lint-arwaky-cli scan <target-path>

# 2. Syntax check
python3 -m py_compile src/<module>.py

# 3. Import check
python3 -c "import <module>"

# 4. Run ruff (if available)
ruff check src/

# 5. Run mypy (if available)
mypy src/

6.6 Commit

git add -A
git commit -m "fix: resolve <N> AES violations (<list of rules>)"

7. Quick Fix Recipes

Rename file (AES101/102)

# Before: capabilities_scanner.py (wrong — missing concern + suffix mismatch)
# After:  capabilities_file_scanner.py
git mv src/capabilities_scanner.py src/capabilities_file_scanner.py
# Update __init__.py imports

Remove unused import (AES203)

lint-arwaky-cli fix src/file.py --filter AES203
# Or manually: remove the unused import line

Fix bypass comments (AES304)

# Find all bypass patterns
grep -rn 'noqa\|type: ignore\|pragma: no cover\|FIXME\|TODO' src/

# Fix each one:
# noqa → fix the underlying lint issue
# type: ignore → add proper type annotation
# pragma: no cover → ensure code is testable

Remove dead code (AES501–506)

# Find orphan files
lint-arwaky-cli orphan modules/ --format json

# If orphan is truly dead → delete it
# If orphan should be wired → add to container or import chain

Fix layer role violation (AES401–406)

# Identify which role rule is violated
lint-arwaky-cli role modules/ --filter AES403

# Common fixes:
# - Move I/O code from capabilities to utility
# - Move business logic from surface to capabilities
# - Move orchestration from capabilities to agent

6. Common Issues & Fix Strategies