flowchart TB
    subgraph rules ["docs/rules/"]
        direction TB
        CODE["code/"]
        GIT["git/"]
        INFRA["infra/"]
        DOCS["docs/"]
        STYLE["style/"]
    end

    subgraph skills ["Specialized Skills"]
        S1["ogt-docs-rules-code"]
        S2["ogt-docs-rules-git"]
        S3["ogt-docs-rules-code-front"]
        S4["ogt-docs-rules-code-back"]
        S5["ogt-docs-rules-code-infra"]
    end

    CODE --> S1
    CODE --> S3
    CODE --> S4
    CODE --> S5
    GIT --> S2
    INFRA --> S5

docs/rules/
├── code/                           # Coding standards
│   ├── general/                    # Cross-cutting code rules
│   │   ├── rule.md                 # Primary rule definition
│   │   ├── examples.md             # Good/bad examples
│   │   ├── .version                # Schema version
│   │   └── .enforced_by            # How it's enforced (eslint, tsc, etc.)
│   │
│   ├── typescript/                 # TypeScript-specific rules
│   │   ├── rule.md
│   │   ├── examples.md
│   │   └── .enforced_by
│   │
│   ├── naming/                     # Naming conventions
│   │   ├── rule.md
│   │   ├── examples.md
│   │   └── .enforced_by
│   │
│   ├── front/                      # Frontend-specific rules
│   │   ├── components/
│   │   ├── state/
│   │   ├── styling/
│   │   └── routing/
│   │
│   ├── back/                       # Backend-specific rules
│   │   ├── api/
│   │   ├── database/
│   │   └── services/
│   │
│   └── infra/                      # Infrastructure rules
│       ├── docker/
│       ├── ci/
│       └── deployment/
│
├── git/                            # Git workflow rules
│   ├── commits/                    # Commit message format
│   │   ├── rule.md
│   │   ├── examples.md
│   │   └── .enforced_by
│   │
│   ├── branches/                   # Branch naming
│   │   ├── rule.md
│   │   └── examples.md
│   │
│   ├── pull_requests/              # PR requirements
│   │   ├── rule.md
│   │   └── template.md
│   │
│   └── reviews/                    # Code review standards
│       ├── rule.md
│       └── checklist.md
│
├── docs/                           # Documentation rules
│   ├── structure/                  # Folder organization
│   ├── formatting/                 # Markdown standards
│   └── comments/                   # Code comments
│
└── style/                          # Style guides
    ├── ui/                         # UI/UX consistency
    ├── api/                        # API style
    └── naming/                     # Naming conventions

undefined

---

docs/rules/code/typescript/
├── rule.md
├── examples.md
├── .version
└── .enforced_by

undefined

// Explicit types
function calculateTotal(items: CartItem[]): number {
  return items.reduce((sum, item) => sum + item.price, 0);
}

// Unknown instead of any
function parseJSON(text: string): unknown {
  return JSON.parse(text);
}

// Type guards for unknown
function isUser(value: unknown): value is User {
  return typeof value === "object" && value !== null && "id" in value;
}

undefined

// Implicit any - TS7006
function process(data) {
  // ERROR: Parameter 'data' implicitly has 'any' type
  return data.value;
}

// Using any
function handleResponse(response: any) {
  // AVOID: Use unknown or specific type
  return response.data;
}

// ts-ignore without comment
// @ts-ignore  // BAD: No explanation
const result = brokenLibrary.call();

// Exception: Legacy API returns untyped response (see #123)
const data = legacyApi.fetch() as any;

undefined

undefined

// Function return types - ALWAYS explicit
function fetchUser(id: string): Promise<User> {
  return api.get(`/users/${id}`);
}

// Exported constants - ALWAYS explicit
export const DEFAULT_TIMEOUT: number = 5000;

// Complex objects - ALWAYS explicit
const config: AppConfig = {
  apiUrl: process.env.API_URL,
  timeout: 5000,
};

// Local variables with obvious types
const count = 0; // Inferred as number
const name = "test"; // Inferred as string
const items = [1, 2, 3]; // Inferred as number[]

// Arrow functions in callbacks
users.filter((user) => user.active); // Parameter type inferred from array

// CORRECT: Use discriminated unions
type Result<T> = { success: true; data: T } | { success: false; error: Error };

function handleResult<T>(result: Result<T>) {
  if (result.success) {
    console.log(result.data); // TypeScript knows data exists
  } else {
    console.error(result.error); // TypeScript knows error exists
  }
}

// INCORRECT: Loose union without discriminant
type Response = {
  data?: User;
  error?: Error;
};

// Problem: Both could be undefined, or both could be set

// CORRECT: Constrain generics appropriately
function getProperty<T, K extends keyof T>(obj: T, key: K): T[K] {
  return obj[key];
}

// INCORRECT: Unconstrained generic
function getValue<T>(obj: T, key: string): any {
  // Returns any!
  return (obj as any)[key];
}

undefined

{ "schema": "1.0", "created": "2026-01-15T10:00:00Z", "updated": "2026-02-01T14:00:00Z" }

tsc --noEmit
eslint --ext .ts,.tsx
pre-commit hook
CI pipeline

docs/rules/git/commits/
├── rule.md
├── examples.md
├── .version
└── .enforced_by

undefined

<type>(<scope>): <description>

[optional body]

[optional footer(s)]

feat(auth): add Steam OAuth provider

Implement Steam OpenID authentication flow.
Follows existing Google/Discord pattern.

Closes #456

fix(api): handle null response from legacy endpoint

The /v0/users endpoint can return null for deleted users.
Add null check and return 404 instead of 500.

Fixes #789

refactor(components): extract CardBase from entity cards

DRY refactor - all entity cards now extend CardBase.
No functional changes.

feat(api)!: change authentication header format

BREAKING CHANGE: Authorization header now requires "Bearer " prefix.
Migration guide: docs/guides/auth_migration.md

Fixed bug // No type, no scope, vague

FEAT: Add new feature // Wrong case

feat(auth): Added Steam OAuth // Past tense

feat: implement the new user authentication system with Steam support and update all related components // Too long

undefined

undefined

feat(creatures): add CR filtering to creature list

Allow filtering creatures by Challenge Rating range.
Uses dual-handle slider component.

Related: #234

feat(search): implement fuzzy search with MiniSearch

Replace substring matching with indexed fuzzy search.
Results ranked by relevance score.

Performance: <16ms for 10k entries

Closes #567

fix(cards): prevent image flash on card hover

Card images were reloading on every hover due to
missing key prop in map. Add stable key based on
entity slug.

Fixes #890

fix(auth): handle expired refresh tokens gracefully

When refresh token expires, redirect to login instead
of showing error page. Clear local storage on redirect.

Fixes #891
Fixes #892

refactor(services): extract API client from services

Move HTTP logic to dedicated ApiClient class.
Services now use dependency injection.

No functional changes. Improves testability.

docs(readme): add Docker setup instructions

Document docker-compose workflow for new developers.
Include troubleshooting section for common issues.

feat(api)!: rename /monsters to /creatures

BREAKING CHANGE: All /api/monsters/_ endpoints now at /api/creatures/_

Migration:

- Update all fetch calls
- /monsters/:slug -> /creatures/:slug
- Search params unchanged

Deprecation notice sent 2026-01-01.
Old endpoints removed 2026-02-01.

undefined

commitlint
husky pre-commit
GitHub Actions CI

flowchart TD
    A[Identify Need for Rule] --> B{Rule Type?}

    B -->|Code| C[docs/rules/code/]
    B -->|Git| D[docs/rules/git/]
    B -->|Docs| E[docs/rules/docs/]
    B -->|Style| F[docs/rules/style/]

    C --> G[Create Rule Folder]
    D --> G
    E --> G
    F --> G

    G --> H[Write rule.md]
    H --> I[Add examples.md]
    I --> J[Set .version]
    J --> K[Document .enforced_by]
    K --> L{Automated Enforcement?}

    L -->|Yes| M[Configure Tooling]
    L -->|No| N[Add to Review Checklist]

    M --> O[Add to CI]
    N --> O

    O --> P[Announce to Team]