# {{PROJECT_NAME}} — Coding Conventions

Project-specific coding standards for SpecForge Agent Teams workers. Workers follow these conventions when implementing tickets.

## Language & Framework

- **Language:** {{LANGUAGE}}
- **Framework:** {{FRAMEWORK}}
- **Runtime:** {{RUNTIME}}

## Naming Conventions

### Files
- Components: `PascalCase.tsx` (e.g., `UserProfile.tsx`)
- Utilities/helpers: `kebab-case.ts` (e.g., `date-utils.ts`)
- Tests: `{filename}.test.ts` or `{filename}.spec.ts`
- Styles: `{ComponentName}.module.css` or co-located

### Code
- Functions: `camelCase` (e.g., `getUserById`)
- Interfaces/Types: `PascalCase` (e.g., `UserProfile`, `CreateUserInput`)
- Constants: `UPPER_SNAKE_CASE` (e.g., `MAX_RETRIES`)
- Enums: `PascalCase` with `PascalCase` members
- Boolean variables: prefix with `is`, `has`, `should`, `can` (e.g., `isLoading`)

## Import Style

```
// 1. External packages
import React from 'react';
import { useState } from 'react';

// 2. Internal aliases (@/ paths)
import { Button } from '@/components/ui/Button';
import { useAuth } from '@/lib/hooks/useAuth';

// 3. Relative imports
import { helper } from './utils';
import type { Props } from './types';

// 4. Type-only imports (separate)
import type { User } from '@/lib/types';
```

## Error Handling

```
// Use try/catch for async operations
try {
  const result = await apiCall();
  return result;
} catch (error) {
  // Log with context
  console.error('Failed to fetch user:', error);
  // Re-throw or return error state — don't swallow errors silently
  throw error;
}
```

- Use typed error handling where possible
- Return error states from hooks/functions rather than throwing in UI code
- Log errors with context (what operation failed, relevant IDs)

## Test Patterns

- **Test framework:** {{TEST_FRAMEWORK}}
- **Location:** Co-located `__tests__/` directories or `*.test.ts` files
- **Pattern:** Arrange-Act-Assert

```
describe('functionName', () => {
  it('should handle the expected case', () => {
    // Arrange
    const input = createTestInput();

    // Act
    const result = functionName(input);

    // Assert
    expect(result).toEqual(expectedOutput);
  });
});
```

## State Management

- {{STATE_PATTERN}}
- Keep state as close to where it's used as possible
- Avoid prop drilling beyond 2 levels — use context or state management

## API Patterns

- {{API_PATTERN}}
- Use consistent response shapes
- Handle loading, error, and success states

## Monorepo Rules

_(Remove this section for single-app projects)_

- **Workspace tool:** {{WORKSPACE_TOOL}}
- Workers must stay within their assigned workspace
- Shared packages go in `packages/` directory
- Cross-workspace imports use package names, not relative paths
- Run commands scoped to the workspace: `cd {workspace} && {command}`

## Project-Specific Notes

_(Add any project-specific conventions here)_