# Contributing to omnibase_infra

This document provides guidelines for contributing to the ONEX Infrastructure repository.

## Coding Standards

**[CLAUDE.md](CLAUDE.md) is the authoritative source for all coding standards and conventions.**

Before writing code, read CLAUDE.md for:
- Type system rules (no `Any` types)
- File and class naming conventions
- Error handling patterns
- Node architecture requirements
- Container dependency injection patterns

The `docs/` directory provides explanations and examples, but **CLAUDE.md rules take precedence** when there is any conflict.

---

## Commit Message Guidelines

### Standard Format

Commit messages follow the Conventional Commits specification with agent attribution:

```
<type>(<scope>): <description> [agent: <agent-name>]
```

### Components

| Component | Description | Required |
|-----------|-------------|----------|
| `type` | Category of change | Yes |
| `scope` | Area of codebase affected | Optional |
| `description` | Brief summary of changes | Yes |
| `agent` | Agent that generated the code | Yes, for agent-generated code |

### Commit Types

| Type | Usage |
|------|-------|
| `feat` | New feature |
| `fix` | Bug fix |
| `refactor` | Code restructuring without behavior change |
| `docs` | Documentation changes |
| `test` | Test additions or modifications |
| `chore` | Build, tooling, or maintenance tasks |
| `perf` | Performance improvements |
| `style` | Formatting, whitespace (no logic change) |

### Agent Attribution

**When to include agent attribution**: Always include `[agent: agent-name]` when code was generated or significantly modified by an AI agent.

**When to omit**: Only for purely human-authored changes.

### Common Agent Names

#### Orchestration Agents

| Agent | Purpose |
|-------|---------|
| `agent-onex-coordinator` | Primary routing and workflow orchestration |
| `agent-workflow-coordinator` | Multi-step execution, sub-agent fleet coordination |
| `agent-ticket-manager` | Ticket lifecycle, dependency analysis |

#### Development Agents

| Agent | Purpose |
|-------|---------|
| `agent-contract-validator` | Contract validation |
| `agent-contract-driven-generator` | Contract-driven code generation |
| `agent-ast-generator` | AST-based code generation |
| `agent-commit` | Commit message generation and staging |

#### DevOps Agents

| Agent | Purpose |
|-------|---------|
| `agent-devops-infrastructure` | Infrastructure configuration |
| `agent-security-audit` | Security review and fixes |
| `agent-performance` | Performance optimization |
| `agent-production-monitor` | Production monitoring setup |

#### Quality Agents

| Agent | Purpose |
|-------|---------|
| `agent-pr-review` | Pull request review |
| `agent-pr-create` | Pull request creation |
| `agent-address-pr-comments` | PR comment resolution |
| `agent-testing` | Test generation and execution |

#### Intelligence Agents

| Agent | Purpose |
|-------|---------|
| `agent-research` | Research and documentation |
| `agent-debug-intelligence` | Debug analysis |
| `agent-rag-query` | RAG query execution |
| `agent-rag-update` | RAG knowledge update |

### Examples

#### Single Agent Contribution

```
feat(event-bus): add circuit breaker to Kafka producer [agent: agent-contract-driven-generator]
```

#### DevOps Change

```
chore(docker): update compose configuration for SSL [agent: agent-devops-infrastructure]
```

#### Documentation

```
docs(patterns): add error recovery pattern guide [agent: agent-research]
```

#### Bug Fix

```
fix(adapters): resolve connection leak in Vault adapter [agent: agent-debug-intelligence]
```

#### Test Addition

```
test(event-bus): add integration tests for message routing [agent: agent-testing]
```

#### Refactoring

```
refactor(models): consolidate Pydantic model definitions [agent: agent-contract-validator]
```

#### Human-Only Change

```
fix(typo): correct spelling in README
```

### Multi-Line Commit Messages

For complex changes, include a body with additional context:

```
feat(runtime): implement policy registry for orchestrators [agent: agent-contract-driven-generator]

- Add RegistryPolicy class with thread-safe registration
- Implement orchestrator and reducer policy types
- Add container wiring for policy resolution
- Include comprehensive unit tests

Resolves: OMN-812
```

### Co-Authored Commits

When multiple agents or humans contribute:

```
feat(nodes): add postgres adapter effect node [agent: agent-contract-driven-generator]

Implementation generated by agent-contract-driven-generator.
Tests generated by agent-testing.
Review and refinements by human developer.

Co-authored-by: agent-testing
```

## Code Review Attribution

When agents participate in code review, note this in PR descriptions:

```markdown
## Review Notes

- Initial review: agent-pr-review
- Security audit: agent-security-audit
- Final approval: human reviewer
```

## Pre-commit Hooks

This repository uses pre-commit hooks that run automatically. Install them after cloning:

```bash
pre-commit install
```

## See Also

- [CLAUDE.md](CLAUDE.md) - Agent architecture and development rules
- [docs/patterns/README.md](docs/patterns/README.md) - Implementation patterns
- [README.md](README.md) - Project overview and setup
