Paths: File paths (
shared/
,
references/
,
../ln-*
) are relative to skills repo root. If not found at CWD, locate this SKILL.md directory and go up one level for repo root. If
shared/
is missing, fetch files via WebFetch from
https://raw.githubusercontent.com/levnikolaevich/claude-code-skills/master/skills/{path}
.

Test Structure Auditor (L3 Worker)

Type: L3 Worker

Specialized worker auditing test file organization and directory structure for maintainability as the test suite grows.

Purpose & Scope

Audit Test Structure (Category 8: Medium Priority)
Detect layout pattern (flat / mirrored / co-located / hybrid)
Flag flat directories exceeding growth thresholds with domain grouping recommendations
Verify test-to-source mapping consistency and orphaned tests
Calculate compliance score (X/10)

Inputs (from Coordinator)

MANDATORY READ: Load

shared/references/audit_worker_core_contract.md

Receives

contextStore

with:

tech_stack

testFilesMetadata

(ALL types -- both automated and manual),

codebase_root

output_dir

domain_mode

all_domains

Note: Unlike other workers that receive type-filtered metadata, this worker receives ALL test files because directory structure analysis requires the full picture of where both automated and manual tests are placed.

Workflow

MANDATORY READ: Load

shared/references/two_layer_detection.md

for detection methodology.

Parse Context: Extract test file list, output_dir, codebase_root, domain info from contextStore
Map Source Structure: Glob source directories (
```
src/
```
,
```
app/
```
,
```
lib/
```
) to build source domain/module tree
Map Test Structure: Group test files by parent directory, count files per directory, classify locations
Scan Checks (Layer 1): Run 5 audit checks (see Audit Rules) using Glob/Grep patterns
Context Analysis (Layer 2 -- MANDATORY): For each candidate finding, apply Layer 2 filters (see each check)
Collect Findings: Record violations with severity, location, effort, recommendation
Calculate Score: Count violations by severity, calculate compliance score (X/10)
Write Report: Build full markdown report in memory per
```
shared/templates/audit_worker_report_template.md
```
, write to
```
{output_dir}/637-test-structure.md
```
in single Write call
Return Summary: Return minimal summary to coordinator (see Output Format)

Audit Rules

1. Layout Pattern Detection

What: Detect which test organization pattern the project uses and check for unintentional mixing

Detection:

Classify each test file location:
- Co-located: test file in same directory as source file (e.g.,
```
src/users/users.test.ts
```
  )
- Mirrored: test file in parallel hierarchy (e.g.,
```
tests/users/users.test.ts
```
  mirrors
```
src/users/
```
  )
- Centralized-flat: all tests in single directory (e.g.,
```
tests/
```
  or
```
__tests__/
```
  )
- Manual: files in
```
tests/manual/
```
  (informational, not flagged)
Calculate distribution percentages across patterns
If >70% files follow one pattern -> that is the dominant pattern
If no pattern reaches 70% -> hybrid

Layer 2:

Hybrid is acceptable if different test TYPES use different patterns (e.g., unit tests co-located + integration tests in
```
tests/automated/integration/
```
). Check if deviation correlates with test type
Projects with <5 test files -> skip (too small to establish pattern)

Severity: MEDIUM if hybrid without clear type-based rule (>30% of same-type tests deviate from dominant pattern)

Recommendation: Standardize test placement -- choose one pattern per test type and document in testing guidelines

Effort: L

2. Test-to-Source Mapping

What: Detect orphaned test files (source file deleted but test remains) and mismatched paths

Detection:

For each test file, extract the implied source module:

```
users.test.ts
```
->
```
users.ts
```
or
```
users/index.ts
```
```
test_payments.py
```
->
```
payments.py
```

Check if the implied source file exists in the expected location
If source file not found -> orphaned test candidate

Layer 2:

Skip integration/e2e tests (test multiple modules, no 1:1 source mapping)
Skip tests in centralized-flat layout (no path-based mapping expected)
Skip test files that import from multiple source modules (integration tests by nature)
Skip utility/helper test files (
```
test_utils.ts
```
,
```
test_helpers.py
```
)

Severity: MEDIUM for orphaned tests (dead code), LOW for path mismatches

Recommendation: Delete orphaned tests or update to match current source structure

Effort: S

3. Flat Directory Growth

What: Detect test directories with excessive file count that would benefit from subdirectory grouping

Detection:

Count test files per directory (excluding
```
node_modules
```
,
```
dist
```
,
```
build
```
)
Thresholds:
- 15-20 files in one flat directory -> LOW (approaching limit)
- >20 files in one flat directory -> MEDIUM (restructure recommended)
For MEDIUM findings, suggest domain-based grouping by analyzing file name prefixes:
- Group by common prefix (e.g.,
```
test_auth_*.py
```
  ->
```
auth/
```
  subdirectory)
- Cross-reference with source domain structure if available

Layer 2:

Skip if directory already has subdirectories (partially organized)
Skip if files use clear naming prefixes that provide sufficient organization without subdirectories
Skip
```
tests/manual/
```
(manual test structure has separate conventions)

Severity: MEDIUM (>20 files), LOW (15-20 files)

Recommendation: Group tests into subdirectories by domain/feature. Suggest specific grouping based on file name analysis:

# Before (flat):
tests/test_auth_login.py, tests/test_auth_tokens.py, tests/test_users_crud.py, ...

# After (grouped):
tests/auth/test_login.py, tests/auth/test_tokens.py, tests/users/test_crud.py, ...

Effort: M

4. Domain Grouping Alignment

What: Check whether test directory grouping mirrors source domain structure

Detection:

Compare source domain directories (from
```
all_domains
```
or scanned
```
src/
```
) with test directory names
For each source domain, check if a corresponding test group exists:
- Mirrored layout:
```
tests/{domain}/
```
  directory exists
- Co-located: test files exist in
```
src/{domain}/
```
Flag source domains with zero corresponding test groups

Layer 2:

Skip if project has no clear domain structure (
```
domain_mode="global"
```
or <2 source domains)
Skip shared/common/utils domains (cross-cutting, may not need dedicated test group)
Skip if project uses centralized-flat layout (no grouping expected)

Severity: MEDIUM for domains with >5 source files but no test group, LOW otherwise

Recommendation: Create test directory/group for domain to maintain structural alignment

Effort: M

5. Co-location Consistency

What: Detect which co-location pattern the project uses and flag inconsistencies

Detection:

Count test files placed next to source files vs. in dedicated test directories
Calculate ratio: co-located / (co-located + centralized)
If ratio 0.0-0.2 -> centralized pattern
If ratio 0.8-1.0 -> co-located pattern
If ratio 0.2-0.8 -> mixed (potential inconsistency)
For mixed: identify which modules deviate from the dominant pattern

Layer 2:

Mixed is acceptable if different test types use different placement:
- Unit tests co-located + integration/e2e tests centralized -> valid hybrid
- Check test file naming/location correlation with type
Projects with <5 test files -> skip

Severity: MEDIUM if >20% of same-type tests deviate from dominant placement pattern

Recommendation: Consolidate test placement -- move deviating tests to follow the project's dominant pattern

Effort: M-L

Scoring Algorithm

MANDATORY READ: Load

shared/references/audit_worker_core_contract.md

and

shared/references/audit_scoring.md

Severity mapping:

Orphaned tests, Excessive flat directory (>20), Inconsistent layout, Inconsistent co-location -> MEDIUM
Approaching flat directory limit (15-20), Missing domain test group (small domain), Path mismatch -> LOW

Output Format

MANDATORY READ: Load

shared/references/audit_worker_core_contract.md

and

shared/templates/audit_worker_report_template.md

If summaryArtifactPath is present, write JSON summary per shared/references/audit_summary_contract.md. Compact text output is fallback only.

Write report to

{output_dir}/637-test-structure.md

with

category: "Test Structure"

and checks: layout_pattern, test_source_mapping, flat_dir_growth, domain_grouping, colocation_consistency.

Return summary per

shared/references/audit_summary_contract.md

Legacy compact text output is allowed only when

summaryArtifactPath

is absent:

Report written: .hex-skills/runtime-artifacts/runs/{run_id}/audit-report/637-test-structure.md
Score: X.X/10 | Issues: N (C:N H:N M:N L:N)

Critical Rules

MANDATORY READ: Load

shared/references/audit_worker_core_contract.md

Do not auto-fix: Report only, suggest restructuring
Effort realism: S = <1h, M = 1-4h, L = >4h
Skip when trivial: If <5 test files total, return score 10/10 with zero findings
No naming check: Test naming consistency (
```
.test.
```
vs
```
.spec.
```
) is out of scope -- do not duplicate
Both types: Analyze both automated and manual test file locations for complete layout picture
Concrete suggestions: For flat directory growth findings, always suggest specific subdirectory grouping based on file name prefix analysis

Definition of Done

MANDATORY READ: Load

shared/references/audit_worker_core_contract.md

contextStore parsed successfully (including output_dir, domain info)
Source structure mapped (domain/module tree)
Test structure mapped (files grouped by directory, counts calculated)
All 5 checks completed
Layer 2 context analysis applied (type-based hybrid, small project exclusions)
Layout pattern detected and documented in report
Flat directory growth signals identified with specific grouping suggestions
Findings collected with severity, location, effort, recommendation
Score calculated using penalty algorithm
Report written to
```
{output_dir}/637-test-structure.md
```
(atomic single Write call)
Summary written per contract

Version: 1.0.0 Last Updated: 2026-03-15

ln-637-test-structure-auditor

NPX Install

Tags

SKILL.md Content

Test Structure Auditor (L3 Worker)

Purpose & Scope

Inputs (from Coordinator)

Workflow

Audit Rules

1. Layout Pattern Detection

2. Test-to-Source Mapping

3. Flat Directory Growth

4. Domain Grouping Alignment

5. Co-location Consistency

Scoring Algorithm

Output Format

Critical Rules

Definition of Done