Standardization (s13n)

Normalize diverging patterns across a repository into a single canonical architecture protected by automated linter guards.

Modes

Select an execution mode before Step 1:

• Audit mode (default). Inventory codebase patterns, identify architectural divergence, and generate a standardization plan without modifying files.
• Normalize mode. Apply approved pattern refactors and install linter guardrails.

Governing principle

Verify repository evidence or secure user authorization before selecting a canonical variant; never adopt a pattern solely on file frequency. The majority pattern is evidence, not authority. A minority pattern may represent an active architectural migration. Normalizing to the majority without checking destroys intentional migrations.

Precedence hierarchy

Resolve convention questions against this hierarchy, evaluated highest to lowest:

Reference modules

Load relevant reference files on demand based on repository language and scope:

Workflow

Phase 1. Reconnaissance

Inspect existing repository conventions and tool configurations before modifying code:

ls -la AGENTS.md CLAUDE.md CODEBASE.md CONTRIBUTING.md .editorconfig 2>/dev/null
ls -la .eslintrc* eslint.config* .prettierrc* ruff.toml pyproject.toml .golangci.yml 2>/dev/null

Determine primary languages and file distributions:

find . -type f -not -path './.git/*' -not -path '*/node_modules/*' -not -path '*/vendor/*' \
  | sed 's/.*\.//' | sort | uniq -c | sort -rn | head -15

If the repository is mid-migration (indicated by TODO(migrate) comments or dual implementations), clarify migration intent before touching files.

Completion criterion. The inventory is recorded in .agents/state/s13n/inventory.md listing convention files, active formatters, and language distribution counts.

Phase 2. Detect divergences

Probe codebase concerns systematically. Consult references/divergence-taxonomy.md for full taxonomy:

grep -rn --exclude-dir={node_modules,.git,dist,build,vendor} -E "require\(|from ['\"]|import .* from" . | head -30
grep -rn --exclude-dir={node_modules,.git,dist,build,vendor} -E "\.then\(|await |async function" . | head -30
grep -rn --exclude-dir={node_modules,.git,dist,build,vendor} -E "throw new|raise |return Err|panic\(" . | head -30

Record each divergence with exact file counts and sample locations. Check git history for recent changes in minority variants to distinguish intentional modernizations from accidental deviations.

Completion criterion. The divergence catalog is recorded in .agents/state/s13n/divergences.md documenting file counts and sample snippets for every identified variant.

Phase 3. Resolve canonical variants

Resolve canonical patterns using the Precedence Hierarchy. When rank 1 and rank 2 answer the question, proceed directly to normalization.

When code patterns conflict and rank 1 or 2 does not specify a rule, present options to the user:

• State the concern concisely in one line.
• Present each variant with its file count and sample snippet.
• State the recommended variant with clear rationale.
• Identify counter-signals such as newer modules or recent commit ranges.
• Cap questions to at most four major divergences per round.

Completion criterion. A confirmed canonical variant is recorded in .agents/state/s13n/canonical.md with rank from the Precedence hierarchy and backing references.

Phase 4. Normalize

Execute normalization in two distinct stages:

1. Mechanical normalization. Run project formatters and linters first:

# JS/TS
npx prettier --write . && npx eslint . --fix

# Python
ruff format . && ruff check . --fix

# Go
gofmt -w . && goimports -w .

2. Semantic normalization. Update call sites, imports, and error handling manually:

• Replace losing variants with the canonical pattern.
• Update every caller site across the codebase.
• Update associated test cases and documentation.
• Add an automated linter guard (such as no-restricted-imports in ESLint or banned-api in Ruff) to prevent regressions.

Confine normalization edits to project source files; never modify generated files, lockfiles, or external vendor dependencies (vendor/, node_modules/, dist/).

Completion criterion. grep -rn "<deprecated-pattern>" --exclude-dir={node_modules,.git,dist,build,vendor} . returns zero matches, and the linter guard commit hash is recorded in .agents/state/s13n/guard-commit.txt.

Phase 5. Verify

Confirm the codebase is healthy and consistent:

• Project builds cleanly with zero errors.
• Test suite passes completely.
• Linter passes with new guard rules enabled.
• Repository search for the eliminated variant returns zero matches outside documented exemptions:

grep -rn "disallowed-pattern" --exclude-dir={node_modules,.git,dist,build,vendor} . && echo "FAIL" || echo "CLEAN"

Completion criterion. Build command exits with zero, all tests pass, and grep returns zero matches for the deprecated pattern.

Common mistakes

Boundary isolation

Standardize syntax conventions and architectural patterns only. Do not alter functional domain logic, modify database schemas, or rename public API endpoints during normalization.

Quick audit checklist

Review this table before completing standardization tasks: