# Contributing to Hermes

Welcome! This guide will help you get started with the Hermes agent quickly.

## Prerequisites

- Node.js 18+ and pnpm
- Git
- Paperclip API access (localhost:8087)

## Setup

### 1. Clone the repository

```bash
git clone <repository-url>
cd agents/hermes
```

### 2. Install dependencies

```bash
pnpm install
```

### 3. Configure your environment

Copy the `.env.example` file (if exists) and set required variables:

- `PAPERCLIP_API_URL=http://localhost:8087`
- `PAPERCLIP_AGENT_ID=<your-agent-id>`
- `PAPERCLIP_COMPANY_ID=<company-id>`

### 4. Verify setup

```bash
pnpm paperclipai agent local-cli 14268c99-2acb-4683-928b-94d1bc8224e4 --company-id e4a42be5-3bd4-46ad-8b3b-f2da60d203d4
```

## Getting Started

### Understanding the Agent System

Hermes is a Paperclip-powered agent that:
- Receives tasks via the Paperclip API
- Executes work within defined heartbeats
- Reports progress through issue comments and status updates
- Maintains local memory in the `memory/` directory

### Heartbeat Workflow

Each heartbeat follows this pattern:

1. **Check identity** - Confirm your agent ID and permissions
2. **Review assignments** - Get all assigned issues (todo, in_progress, blocked)
3. **Checkout tasks** - Claim tasks you're ready to work on
4. **Execute work** - Complete the assigned tasks using your tools
5. **Update status** - Mark tasks as done or blocked with comments

### Running a Heartbeat

```bash
pnpm paperclipai heartbeat run --agent-id 14268c99-2acb-4683-928b-94d1bc8224e4
```

## Project Structure

```
hermes/
├── AGENTS.md          # Agent instructions and capabilities
├── HEARTBEAT.md       # Execution checklist
├── SOUL.md            # Persona definition
├── TOOLS.md           # Available tools
├── docs/              # Component documentation (creates on setup)
│   ├── CONTRIBUTING.md
│   └── COMPONENT_PATTERNS.md
├── life/              # Personal PARA folder
│   └── projects/      # Project summaries
└── memory/            # Daily notes and planning
    └── YYYY-MM-DD.md  # Date-based notes
```

## Documentation Guidelines

### Component Documentation (FRE-25)

All public components must have:
- JSDoc comments on exported components
- Clear prop descriptions with types
- Usage examples in the docblock

Example:

```typescript
/**
 * Button component for user interactions.
 * 
 * @param {string} variant - Visual style ('primary', 'secondary', 'danger')
 * @param {boolean} loading - Whether button is in loading state
 * @param {React.ReactNode} children - Button content
 * @returns {JSX.Element} Rendered button element
 */
export function Button({ variant = 'primary', loading, children }: ButtonProps) {
  // implementation
}
```

## Testing

All agents must have tests for:
- API interactions
- Heartbeat workflow
- Task status transitions

Run tests:

```bash
pnpm test
```

## Code Style

- Follow existing patterns in the codebase
- Use TypeScript for type safety
- Write clear, self-documenting code
- Add comments for non-obvious logic

## Reporting Issues

When you encounter blockers:

1. Update issue status to `blocked`
2. Add a comment explaining:
   - What is blocked
   - Why it's blocked
   - Who needs to unblock it
3. Escalate via chainOfCommand if needed

## Commit Guidelines

- Use conventional commits
- Reference issue IDs in commit messages
- Write clear, descriptive commit messages

Example:

```
feat(hermes): add heartbeat workflow
fix(hermes): resolve 409 conflict on checkout
docs(hermes): update CONTRIBUTING.md
```

## Resources

- [Paperclip API Reference](https://opencode.ai)
- [HEARTBEAT.md](./HEARTBEAT.md) - Execution checklist
- [SOUL.md](./SOUL.md) - Agent persona and guidelines