my-coding

name: my-coding description: Coding style for all languages — PHP, Dart, TypeScript, Go. No strict_types, 120-char lines, multi-line collections, full types + docblocks, TDD, English only, zero lint violations, Laravel-inspired OOP. when-to-use: Any request to write, modify, review, or generate code in any language. Triggers on implementation, refactoring, code review, and TDD tasks.

Kodizm Coding Style

Code is artisanship. Every class, method, and docblock is intentional. If it doesn't look clean enough to frame on a wall, it's not done.

North Star: Laravel's Elegance

Laravel's API design — expressive method names, fluent interfaces, clean separation of concerns — is the gold standard for ALL code, not just PHP. Apply these principles universally:

• Naming tells a story — findOrCreate, syncBarcodes, bootSkillsIfNeeded
• Structure mirrors intent — Service orchestrates. Repository queries. Controller delegates.
• OOP done right — Interfaces for contracts. Abstract classes for shared behavior. Enums for magic values. Value objects for immutability.

CRITICAL: Adapt to Project's Language Version

BEFORE writing any code, detect the project's language version from config files (composer.json → require.php, pubspec.yaml → environment.sdk, tsconfig.json → target, etc.). Use ONLY features available in that version.

PHP version feature gates:

Dart version feature gates:

The style principles (clean imports, docblocks, multi-line formatting, TDD) apply regardless of version. Only syntax features adapt.

Non-Negotiable Rules

1. No declare(strict_types=1)

NEVER add declare(strict_types=1) to PHP files. It violates project conventions, causes runtime TypeError in production with external data, and breaks Laravel's type coercion. Omit the declaration entirely. Type safety is enforced via PHPStan + explicit type declarations, not runtime strict mode.

2. English Only

ALL identifiers, comments, docblocks, commit messages, error messages, DB columns, task sections, knowledge base documents, plan content — English. No exceptions, regardless of project audience.

3. Type Everything

Every parameter, return type, and property has an explicit type declaration. No untyped code ships.

4. Document Everything

If a method needs a paragraph of comments, extract it into a named method.

5. 120-Character Line Width

No line exceeds 120 characters. Break method signatures, chains, conditionals — everything.

6. Multi-Line Collections — ALWAYS

Arrays, objects, parameter lists, maps — ALWAYS multi-line. Even with 2 elements. Trailing commas mandatory.

// CORRECT
$config = [
    'key' => 'value',
    'timeout' => 30,
];

// WRONG — never inline
$config = ['key' => 'value', 'timeout' => 30];

// CORRECT
final colors = [
  Colors.red,
  Colors.blue,
  Colors.green,
];

// WRONG
final colors = [Colors.red, Colors.blue, Colors.green];

7. Clean Imports

Import at the top of the file. NEVER reference classes by full namespace inline.

// CORRECT
use RuntimeException;
throw new RuntimeException('Failed.');

// WRONG — inline namespace
throw new \RuntimeException('Failed.');

8. TDD — Red, Green, Refactor

Write the failing test FIRST. Then implement. Then refactor. Applies to features, bugfixes, and refactors.

• New feature → test describes the contract before implementation
• Bug fix → test reproduces the bug first
• Refactor → existing tests are the safety net

There is no "we'll add tests later." The test comes before the code.

9. Linter is Law

Code MUST pass the linter with zero warnings, zero errors. No suppressions (@ts-ignore, @phpstan-ignore, // ignore:). Fix the actual issue.

10. Numbered Step Comments

Methods with 3+ logical phases get numbered steps:

public function findOrCreate(Team $team, User $user, array $data): GlobalProduct
{
    // 1. Check if already exists — avoid duplicate translations.
    if ($existing = $this->findProductByLocale(...)) {
        return $existing;
    }

    // 2. Find base product in any language as translation source.
    $base = $this->findBaseProduct(...);

    // 3. Translate via AI service.
    $translated = $this->translateViaAI($base, $data['locale']);

    // 4. Create product and sync related data in a transaction.
    return DB::transaction(function () use ($translated, $team) {
        $product = GlobalProduct::create([...$translated, 'team_id' => $team->id]);
        $this->syncBarcodes($product, collect($translated['barcodes']));
        return $product;
    });
}

11. Enum Everything

Status values, types, categories — ALWAYS backed enums. Never string constants or magic values.

12. Thin Controllers + Form Requests

Controllers validate via Form Request, delegate to Service, return Resource. No business logic. No inline validation.

public function store(StoreRequest $request): JsonResponse
{
    $pool = $this->poolService->create($request->validated());

    return response()->json(PoolResource::make($pool), 201);
}

13. Constructor Dependency Injection

Inject dependencies via constructor. Never use facades or service location in class methods.

public function __construct(
    protected PoolService $poolService,
) {}

14. Guard Clauses Over Nesting

Use early returns. Never nest conditionals beyond 2 levels.

if ($pool->isActive()) {
    return;
}

if (! $pool->hasMinimumStake()) {
    throw new InsufficientStakeException($pool);
}

$pool->update(['status' => PoolStatus::Active]);

Architecture Principles

Language-Specific References

Load these when working in the respective language:

• PHP / Laravel: See references/php-laravel.md for controller, model, service, resource, route, and package patterns.
• Dart / Flutter: See references/dart-flutter.md for widget, parser, state management, and SDK/package patterns.
• Anti-Patterns: See references/anti-patterns.md for the comprehensive "never do" list across all languages.