project-structure-clarity

name	project-structure-clarity
description	Refactor this Ataraxia Rust workspace's crate and module structure aggressively but safely. Use when the user asks to clean up project structure, decompose god files, reduce ad-hoc flat source directories, clarify crate boundaries, reorganize modules, or make the workspace easier to grow without changing behavior.

Project Structure Clarity

Use this skill for architecture cleanup of the Ataraxia Rust workspace. Treat the task as a behavior-preserving structural refactor: improve ownership, locality, crate boundaries, and navigation while avoiding cosmetic churn.

Ground Rules

• Read the relevant project skills before implementation work, especially Rust and Cargo skills that match the touched area.
• Check .spec/ before changing code. If .spec/ and code disagree, stop and repair the spec or the code before continuing.
• Use Context7 MCP for current library documentation, API references, and code examples when a refactor touches third-party APIs or library-specific patterns.
• Inspect every Ataraxia crate before making structural decisions: ataraxia, ataraxia-core, ataraxia-engine, ataraxia-host, ataraxia-privilege, and ataraxia-test-support.
• Preserve behavior unless a change is explicitly justified.
• Prefer moving and reorganizing over rewriting.
• Keep public APIs stable unless there is a strong reason to change them. Explain any public API or crate dependency change.
• Avoid modules, structs, traits, or files named utils, helpers, common, misc, manager, service, adapter, factory, or handler.

Required First Pass

Run the user's culprit-finding commands before planning moves:

tokei ataraxia-engine ataraxia-test-support ataraxia-privilege ataraxia-host ataraxia ataraxia-core ataraxia-test-support/ --files | sort -n -k 3 | tail -n 20

cargo clippy -- -A clippy::all \
  -W clippy::cognitive_complexity \
  -W clippy::type_complexity \
  -W clippy::too_many_lines

Then manually ingest the workspace:

• Inspect crate manifests, lib.rs, main.rs, module declarations, and source trees.
• Read the largest files and any files flagged by clippy complexity lints.
• Trace dependencies between crates and modules before moving code.
• Identify files that are already focused and should remain flat.
• Identify files that mix responsibilities, force heavy scrolling, or act as default dumping grounds.

Planning Checklist

Before editing files, present a short target structure:

• Current responsibility of each crate.
• Which files stay flat and why.
• Which files or modules are too broad, misplaced, or grouped poorly.
• Proposed target structure for each crate that will change.
• Reasoning behind each major move.
• Expected public API, visibility, or dependency impact.
• Verification commands to run after the refactor.

Keep the plan concrete. Name actual files and modules, not vague "clean up" areas.

Refactor Heuristics

Balance flatness and grouping:

• Keep simple, focused files flat when that is clearest.
• Introduce modules or subfolders when several files share a domain, workflow, layer, or responsibility.
• Split god files when they contain independent concepts, multiple workflows, broad error/type definitions, or unrelated tests.
• Avoid nesting that only lengthens imports.
• Avoid large flat src directories when meaningful grouping exists.
• Prefer domain-oriented names such as release, staging, promotion, rollback, backup, migration, proxy, runtime, privilege, registry, and doctor.

Respect crate ownership:

• ataraxia stays a CLI binary: parse commands, call ataraxia-engine, render output.
• ataraxia-core stays pure: domain model, identifiers, config types, path rules, errors, state types, invariants.
• ataraxia-engine owns workflow decisions, orchestration plans, order, and stop conditions. It must not execute host commands directly.
• ataraxia-host owns concrete unprivileged host execution, filesystem access, typed command builders, and local host observations.
• ataraxia-privilege exposes only allowlisted privileged actions and never accepts arbitrary shell strings.
• ataraxia-test-support owns fixtures, fake hosts, golden tools, and failure injection seams for tests only.

Implementation Rules

• Move incrementally so compiler errors stay attributable to one structural change at a time.
• Update mod declarations, imports, visibility, and re-exports immediately after each move.
• Use pub(crate) or narrower visibility when callers do not need a public API.
• Keep lib.rs and entrypoint files small, intentional, and oriented around public module boundaries.
• Remove stale module declarations, obsolete files, and dead re-exports after moves.
• Update tests with the moved code. Prefer preserving existing assertions over rewriting tests.
• Add or adjust tests only when the refactor exposes missing coverage around moved behavior.
• Avoid introducing traits, indirection, or new abstractions solely to make the structure look architectural.

Validation

Run the project gates after the refactor:

just fmt
just check
just clippy
just test

Do not suppress command output with --quiet. Treat warnings as failures. If a gate cannot run because a required tool or environment is missing, report the exact blocker and any narrower validation that did run.

Final Report

Summarize:

• Structural moves by crate.
• Behavior-preservation rationale.
• Public API, visibility, or dependency changes, if any.
• Tests or gates run and their results.
• Any files intentionally left flat because they are already clear.