epic: make skilllint repository architecture agent-legible

[Jamie-BitFlight]

Outcome

Make the skilllint repository substantially easier for coding agents to navigate, reason about, modify, and verify without changing the product's established validation semantics.

The repository already has useful domain seams — rules/, adapters/, boundary/, schemas/, scan_runtime.py, reporting, and provenance — but those seams are obscured by:

• a very large packages/skilllint/plugin_validator.py compatibility/implementation surface;
• host-specific orchestration policy living in the universal AGENTS.md;
• a large checked-in agent/workflow/runtime surface that competes with product source during retrieval;
• duplicated volatile CLI/rule facts across README, usage docs, and the bundled skill;
• a slow default test loop that makes repeated agent verification expensive.

This epic coordinates changes that improve change-location inference, context efficiency, documentation authority, and verification latency for agents while preserving the public skilllint behavior.

Design principles

1. Make the correct change seam obvious before an agent reads implementation detail.
2. Keep host-neutral repository rules separate from host-specific orchestration behavior.
3. Treat non-product agent/runtime/planning trees as intentionally classified context, not implicit product architecture.
4. Query volatile product facts from the runtime/registry rather than duplicating them in prose.
5. Decompose the legacy central module incrementally behind compatibility exports.
6. Keep the fast deterministic linter role fast; richer analysis remains opt-in.

Work breakdown

• refactor(agent-context): separate universal repository rules from Claude orchestration #281 — separate universal repository rules from Claude orchestration and add the change-routing map.
• docs(agent-context): classify product, tooling, runtime, vendor, and historical repository surfaces #282 — classify product/tooling/runtime/vendor/history/fixture repository surfaces.
• refactor(core): decompose plugin_validator.py behind stable compatibility exports #283 — decompose plugin_validator.py behind stable compatibility exports.
• docs(agent-skill): make agentskills-skilllint procedural and runtime-driven #284 — make the bundled agent skill procedural and runtime-driven; reduce volatile documentation duplication.
• test(agent-ux): define a fast inner verification loop and retain the full completion gate #285 — define a fast inner verification loop while retaining the full completion gate.
• perf(tests): suite spends ~two thirds of its wall clock on subprocess startup #148 — complete the existing test-performance investigation that informs test(agent-ux): define a fast inner verification loop and retain the full completion gate #285.
• Add opt-in instruction-context static analysis backed by shared host semantics #279 — land opt-in instruction-context analysis through the resulting explicit boundaries.

Current-main reconciliation — 2026-09-29

• refactor(agent-context): separate universal repository rules from Claude orchestration #281 is complete via PR refactor(agent-context): separate universal rules from Claude orchestration #286.
• docs(agent-context): classify product, tooling, runtime, vendor, and historical repository surfaces #282 is complete via PR docs(agent-context): classify repository surfaces for agents #287.
• docs(agent-skill): make agentskills-skilllint procedural and runtime-driven #284 is complete on current main; the bundled skill is procedural/runtime-driven and the volatile catalog ownership has been reduced.
• test(agent-ux): define a fast inner verification loop and retain the full completion gate #285's fast-profile portion is complete via PR test(agent-ux): add fast iterative verification profile #290: scripts/run_fast_tests.py exists, AGENTS distinguishes inner-loop from completion proof, and CI runs the named fast profile. Remaining performance/economic work stays coupled to perf(tests): suite spends ~two thirds of its wall clock on subprocess startup #148, so test(agent-ux): define a fast inner verification loop and retain the full completion gate #285 remains open.
• refactor(core): decompose plugin_validator.py behind stable compatibility exports #283 has already extracted shared validation contracts into models.py; policy/config is the next coherent ownership slice.
• Add opt-in instruction-context static analysis backed by shared host semantics #279 remains last and must enter through its own opt-in analysis subsystem.

Recommended implementation order

Phase 1 — make the repository legible before moving code

1. refactor(agent-context): separate universal repository rules from Claude orchestration #281 — instruction ownership + change routing.
2. docs(agent-context): classify product, tooling, runtime, vendor, and historical repository surfaces #282 — repository-surface classification.

These are low-behavior-risk changes and establish the context rules later agents should follow.

Phase 2 — remove architectural gravity and duplicated knowledge

3. refactor(core): decompose plugin_validator.py behind stable compatibility exports #283 Slice A/B — inventory plugin_validator.py consumers and extract shared models/contracts first.
4. docs(agent-skill): make agentskills-skilllint procedural and runtime-driven #284 — simplify the agent skill/docs once the authoritative runtime seams are explicit.
5. Continue refactor(core): decompose plugin_validator.py behind stable compatibility exports #283 through policy, fixing, validation orchestration, and CLI extraction in small reviewable slices.

#284 can overlap with later #283 slices, but should not invent target module names before the corresponding seam exists.

Phase 3 — improve iteration cost

6. Complete the measurement work in perf(tests): suite spends ~two thirds of its wall clock on subprocess startup #148.
7. Implement test(agent-ux): define a fast inner verification loop and retain the full completion gate #285 using those measurements.

Performance work should preserve the distinction between a fast affected-boundary check and repository-wide completion proof.

Phase 4 — add richer analysis on the clean boundary

8. Re-evaluate Add opt-in instruction-context static analysis backed by shared host semantics #279 against the architecture produced by refactor(agent-context): separate universal repository rules from Claude orchestration #281–test(agent-ux): define a fast inner verification loop and retain the full completion gate #285.
9. Add instruction-context analysis as an explicit opt-in subsystem rather than another responsibility of the legacy validator module.

Existing related work

• perf(tests): suite spends ~two thirds of its wall clock on subprocess startup #148 — test-suite subprocess/import startup cost and slow-marker mismatch.
• Add opt-in instruction-context static analysis backed by shared host semantics #279 — opt-in instruction-context static analysis.

Non-goals

• Moving packages/skilllint to src/skilllint purely for aesthetics.
• Rewriting the rule/adapters/schema architecture that already provides useful extension seams.
• Removing development tooling merely because it is large.
• A big-bang compatibility-breaking rewrite of plugin_validator.py.
• Enabling instruction-context analysis by default.

The repository currently contains one Python package beneath packages/; document the root pyproject.toml ownership clearly, but do not churn paths merely to make the layout look like a conventional single-package src/ project.

Completion criteria

• An unfamiliar coding agent can identify the intended edit location for common change types from the root instructions without repository-wide searching.
• Host-specific agent behavior is not imposed as a universal repository contract.
• Repository tooling/runtime/planning/vendor trees are explicitly distinguishable from product architecture.
• plugin_validator.py is no longer the default owner for unrelated concerns, with compatibility preserved during migration.
• Agent-facing guidance does not duplicate rule catalogs, fixability, command inventories, thresholds, or release/version facts that can be queried from skilllint itself.
• A documented fast verification path exists for iterative work, with the full repository gate remaining authoritative before completion.
• Add opt-in instruction-context static analysis backed by shared host semantics #279 integrates through an explicit analysis subsystem rather than growing the legacy central module.