feat(structure): enforce 1000-line module cap and split oversized files

.github/workflows/ci.yml

@@ -37,6 +37,9 @@ jobs:
       - name: Doc Tests
         run: cargo test --doc && cargo test --doc --features pkce-auth
 
+      - name: Check module size limits
+        run: ./cli-engine/scripts/check-module-size.sh
+
       # cli-engine depends on the new cli-engine-macros crate (path + version
       # dependency), which isn't on crates.io until its first real release
       # (see release.yml) — until then, the dry run can't resolve it, which

AGENTS.md

@@ -11,6 +11,12 @@ These instructions apply to the Rust `cli_engine` crate in this workspace.
   integration tests in `tests/`.
 - Do not add implementation code, docs, fixtures, or tests from unrelated implementations to this repository.
 
+## Code File Structure
+
+- No hand-written `.rs` file exceeds 1000 lines. CI enforces this with `cli-engine/scripts/check-module-size.sh`. When a file grows past the limit, split it into a directory module (`foo.rs` becomes `foo/mod.rs` plus sibling files) grouped by cohesive purpose — not by mechanically chopping it into equal chunks. `cli-engine/src/cli/` (`builtins.rs`, `completion.rs`, `help.rs`, `tree_render.rs`) is an example of this pattern.
+- Prefer functions that fit on one "screen" (~35 lines) as a rule of thumb. When a function's purpose can't be seen without scrolling, extract named helper steps.
+- Keep comments succinct and useful to a reader with no memory of this coding session or its PR review thread: explain a non-obvious local decision (a hidden constraint, a workaround, a subtle invariant), not what the code does or why *this change* did it.
+
 ## Design Direction
 
 - Preserve the cli-engine concepts: domain modules, noun-based groups, leaf commands, colon-separated command paths, middleware, authentication, authorization, output envelopes, schemas, guides, search, and transport helpers.
@@ -29,7 +35,6 @@ These instructions apply to the Rust `cli_engine` crate in this workspace.
 - Keep public names idiomatic Rust: snake_case functions and fields, PascalCase types, clear module names.
 - Avoid clever abstractions unless they clearly reduce repeated command-author work.
 - Public APIs should have useful rustdoc comments. Explain behavior, errors, and invariants where they matter.
-- Source comments should explain non-obvious local decisions.
 
 ## Creating A Consumer CLI
 
@@ -278,6 +283,7 @@ cargo clippy --all-targets -- -D warnings
 RUSTDOCFLAGS='-D warnings' cargo doc --no-deps
 cargo test --all-targets
 cargo test --doc
+./cli-engine/scripts/check-module-size.sh
 ```
 
 Some human-output tests assume width 80 (non-TTY). On a wide interactive terminal they

cli-engine/scripts/check-module-size.sh

@@ -0,0 +1,30 @@
+#!/usr/bin/env bash
+# Fails if any hand-written .rs file exceeds the line-count limit — see
+# AGENTS.md's "Code File Structure" section for the file-layout convention
+# this enforces.
+#
+# Scope: cli-engine/src and cli-engine-macros/src — every workspace member's
+# hand-written source. Deliberately excludes target/ (build output; nothing
+# under it is committed source).
+set -euo pipefail
+
+repo_root="$(cd "$(dirname "$0")/../.." && pwd)"
+limit=1000
+violations=0
+
+while IFS= read -r -d '' file; do
+  lines=$(wc -l < "$file")
+  if [ "$lines" -gt "$limit" ]; then
+    echo "  $file: $lines lines (limit $limit)"
+    violations=$((violations + 1))
+  fi
+done < <(find "$repo_root/cli-engine/src" "$repo_root/cli-engine-macros/src" \
+  -name '*.rs' -print0 2>/dev/null)
+
+if [ "$violations" -gt 0 ]; then
+  echo "ERROR: $violations file(s) over the ${limit}-line limit (shown above)."
+  echo "Split by concern into a directory module — see AGENTS.md."
+  exit 1
+fi
+
+echo "==> All .rs files are within the ${limit}-line limit"