init

name	init
description	This skill should be used when the user asks to "set up clean code rules", "initialize clean code", "init cleancode", "add clean code to this project", "set up code standards", "configure clean code rules", or when a new project is opened and no .cleancode-rules.md file exists. Generates the canonical ruleset and platform config files so all AI assistants follow clean code throughout the project.
argument-hint	[platform: all|claude|cursor|codex]
allowed-tools	Read, Write, Glob, Grep
version	0.3.0

Clean Code Init

Initialize the clean code ruleset for a project. This creates .cleancode-rules.md as the single source of truth, then generates platform-native config files so Claude Code, Cursor, and Codex all follow the same rules automatically.

When This Runs

• Invoked manually via /cleancode:init
• Auto-triggered by the SessionStart hook when no .cleancode-rules.md exists in the project root
• Re-runnable safely — regenerates files without losing project-specific customizations

Step 1: Scan the Project

Before writing anything, understand what's already there.

1. Check if .cleancode-rules.md already exists in the project root

   • If yes: read it, preserve any custom thresholds, then skip to Step 3
   • If no: proceed to Step 2

2. Detect the primary language(s) by scanning for:

   • tsconfig.json, package.json → TypeScript/JavaScript
   • *.py, requirements.txt → Python
   • *.java, pom.xml, build.gradle → Java
   • *.cs, *.csproj → C#
   • *.go, go.mod → Go
   • *.rs, Cargo.toml → Rust

3. Note the project size (number of files) for the baseline report.

Step 2: Write .cleancode-rules.md

Write this file to the project root. It is the source of truth for all platforms.

# Clean Code Rules — [Project Name]

Generated by cleancode plugin. Edit thresholds here; run `/cleancode:init` to regenerate platform configs.

## Active Thresholds

| Metric | Threshold | Severity |
|---|---|---|
| File length | > 300 lines | Critical |
| Function length | > 40 lines | Critical |
| Function length | > 20 lines | Warning |
| Parameter count | > 4 | Critical |
| Nesting depth | > 4 | Critical |
| Duplicated logic | > 3 lines | Warning |
| Reaching through objects (`a.b().c().d()`) | chain depth > 2 | Warning |
| Hidden errors (empty `catch`, `except: pass`) | any occurrence | Critical |
| Missing input check on public function | first line isn't a guard | Warning |
| `if` / `for` / `while` inside test body | any occurrence | Warning |
| Folder structure (domain vs. layer, catch-all folders) | context-dependent hint | Style |

## Language

Primary: [detected language(s)]
TypeScript interface rules: [enabled/disabled]

## Principles

Source: Code Complete 2nd Ed., The Art of Clean Code, OOP vs. Functional

1. No file exceeds 300 lines — split by single responsibility
2. No function exceeds 40 lines — one function, one purpose
3. No more than 4 parameters — group extras into typed objects
4. No nesting deeper than 4 levels — use early returns and extraction
5. All names reveal intent — no abbreviations, no single letters (except loop vars)
6. OOP first — SRP, small classes, composition over inheritance
7. [TS] Every public API has an explicit interface — depend on abstractions
8. DRY — no logic duplicated more than once
9. Comments explain why, not what — no commented-out code
10. Human readability — new contributor understands a file in 5 minutes (Principle of Least Surprise)
11. Don't reach through objects — no `a.b().c().d()` chains (Law of Demeter)
12. Check inputs early, never hide errors — guard clauses, no silent catches (Fail Fast)
13. Build only what you need; leave code cleaner than you found it (YAGNI + Boy Scout Rule)
14. Tests should be as clean as the code they test — Arrange / Act / Assert (AAA)
15. Clean module & folder structure — group what changes together, let the folder tree tell the story (dynamic: adapts to project size, language conventions, and framework norms — never a rigid template)

Step 3: Write Platform Config Files

CLAUDE.md

Write or append to CLAUDE.md in the project root:

# Clean Code Rules

This project enforces clean code principles. Rules are defined in `.cleancode-rules.md`.

## AI Assistant Instructions

- Read `.cleancode-rules.md` before writing any code
- Flag violations before completing responses (non-blocking suggestions)
- When generating code: keep files under 300 lines, functions under 40 lines
- [TS] Always define interfaces for public-facing classes and services
- Prefer OOP with single responsibility; avoid monolith files
- Use meaningful names that reveal intent without needing comments
- When asked to add code to a file already near the limit, suggest splitting first

.cursorrules (for Cursor)

Write .cursorrules to the project root:

# Clean Code Rules — enforced by cleancode plugin

Rules source: .cleancode-rules.md

ALWAYS follow these rules when writing or editing code:

1. Files: max 300 lines. If adding code would exceed this, propose a split.
2. Functions: max 40 lines, single purpose.
3. Parameters: max 4. Group extras into typed objects.
4. Nesting: max 4 levels. Use early returns and guard clauses.
5. Names: intention-revealing. No abbreviations. No single letters except i/j/k.
6. OOP: SRP, small classes, composition over inheritance.
7. TypeScript: every public class/service needs an explicit interface.
8. DRY: no copy-paste logic. Extract to shared utilities.
9. Comments: explain why, never what. No commented-out code.
10. Human test: any contributor must understand a file in 5 minutes.

When you see a violation, flag it as a suggestion — don't block.

AGENTS.md (for Codex CLI)

Write AGENTS.md to the project root:

# Agent Instructions — Clean Code

Rules source: .cleancode-rules.md

## Code Quality Standards

When writing, editing, or reviewing code in this project:

- **File size**: Keep files under 300 lines. Suggest splitting when approaching the limit.
- **Function size**: Keep functions under 40 lines with a single purpose.
- **Parameters**: Max 4. Use typed objects/interfaces for more.
- **Nesting**: Max 4 levels. Prefer early returns and guard clauses.
- **Naming**: Every name reveals intent. No abbreviations. No single letters except loop vars.
- **OOP**: Apply SOLID. Prefer small, single-responsibility classes.
- **TypeScript**: Every public API requires an explicit interface.
- **DRY**: No duplicated logic. Extract to shared helpers.
- **Comments**: Why, not what. No commented-out code.

## Reviewing Code

Flag violations as non-blocking suggestions at the end of responses.
Do not refuse to write code due to violations — suggest improvements instead.

Step 4: Run Baseline Analysis

After writing the config files, run a quick baseline scan:

1. Use Glob to find all source files (exclude node_modules, .git, dist, build)
2. Check each file's line count
3. Report:
   • Total files scanned
   • Files over 300 lines (Critical)
   • Files over 200 lines (Warning — approaching limit)
   • Any obvious patterns (e.g., "3 files named utils.ts — possible monolith")

Format the report as:

cleancode init complete ✓

Config files written:
  • .cleancode-rules.md
  • CLAUDE.md
  • .cursorrules
  • AGENTS.md

Baseline scan: [N] files
  Critical (>300 lines): [list files]
  Warning (>200 lines):  [list files]

Run /cleancode:analyze <file> to inspect any file in detail.
Run /cleancode:teach <rule> to understand any principle.

Step 5: Confirm to User

Show the report. Do not modify any source code during init — only write config files and report findings.

Additional Resources

Reference Files

• references/rules.md — Full canonical ruleset with book citations, rationale, and all thresholds. Read this when the user asks about a specific rule or wants to understand the reasoning.

Notes

• Re-running /cleancode:init is safe — it regenerates config files from .cleancode-rules.md
• If the user has customized thresholds in .cleancode-rules.md, preserve them
• If CLAUDE.md already has content, append the clean code section rather than overwrite
• The $ARGUMENTS placeholder accepts cursor, codex, claude, or all to write only specific platform files