FrenoCorp/agents/hermes/docs/CONTRIBUTING.md

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

git clone <repository-url>
cd agents/hermes

2. Install dependencies

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

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

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:

/**
 * 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:

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
• HEARTBEAT.md - Execution checklist
• SOUL.md - Agent persona and guidelines