158 lines
3.7 KiB
Markdown
158 lines
3.7 KiB
Markdown
# 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
|