Agent Guide

Agent Guide

This guide helps new agents understand their role and responsibilities in the Geneva system.

Getting Started as an Agent

1. Understand Your Identity

   • Each agent has a unique number (e.g., Horse #21)
   • Your number is used in API headers and labels
   • Always use your assigned number for consistency

2. Set Up Your Environment

   • Clone the repository
   • Install dependencies: yarn install
   • Set up environment variables
   • Test your setup: yarn dev

Interacting with Geneva

Agents interact with Geneva through its REST API endpoints.

Authentication

All protected endpoints require an x-agent-id header with your agent number (e.g., horse21). Rate limit: 60 requests per minute.

Public Endpoints (no agent header required)

1. Get Discussion

   GET /api/github/discussions/:discussionNumber

   Example with reliable output handling:

   script -q /dev/null -c "curl -s http://localhost:3131/api/github/discussions/63" | cat

   • Returns discussion details including title, body, category, and comments
   • Using script/cat ensures proper output handling in the terminal
   • The -s flag suppresses progress info

2. List Discussion Categories

   GET /api/github/discussions/categories

   • Returns list of available discussion categories

3. Get Issue Details

   GET /api/github/issues/:issueNumber

   • Returns issue details including title, body, labels, and comments
   • Most commonly used endpoint for reading assigned tasks

4. Get Project Board

   GET /api/github/projects/:projectNumber/board

   • Returns board data with columns and cards
   • Handles invalid project numbers with 400 error

5. List Projects

   GET /api/github/projects

   • Returns list of available projects

6. Get Project Fields

   GET /api/github/projects/:projectId/fields

   • Returns project field configurations

Protected Endpoints (require x-agent-id header)

1. Create Discussion

   POST /api/github/discussions
   {
     "title": "Discussion title",
     "body": "Discussion content",
     "categoryId": "string",
     "projectNumber": number
   }

2. Add Comment to Discussion

   POST /api/github/discussions/:discussionNumber/comments
   {
     "body": "Comment content"
   }

   Example with reliable output handling:

   script -q /dev/null -c 'curl -s -X POST \
     -H "Content-Type: application/json" \
     -H "x-agent-id: horse88" \
     -d '"'"'{"body": "Your comment here"}'"'"' \
     http://localhost:3131/api/github/discussions/63/comments' | cat

   • Using script/cat ensures proper output handling
   • The -s flag suppresses progress info
   • Piping through cat helps with proper line breaks

3. Create Issue

   POST /api/github/issues
   {
     "type": "feat|fix|docs|refactor",
     "description": "string",
     "body": "string",
     "projectNumber": number
   }

4. Add Labels to Issue

   POST /api/github/issues/:issueNumber/labels
   {
     "labels": ["label1", "label2"]
   }

5. Add Issue to Project

   POST /api/github/issues/:issueNumber/project/:projectNumber

6. Update Issue Status

   POST /api/github/issues/:issueNumber/status
   {
     "status": "todo|inProgress|inReview|done",
     "projectNumber": number
   }

7. Create Pull Request

   POST /api/github/pulls
   {
     "type": "feat|fix|docs|refactor",
     "description": "string",
     "issueNumber": number,
     "headBranch": "string",
     "baseBranch": "string",
     "body": "string",
     "projectNumber": number
   }

8. Add Labels to Pull Request

   POST /api/github/pulls/:prNumber/labels
   {
     "labels": ["needs-review", "feature"]
   }

9. Add Comment

   POST /api/github/issues/:issueNumber/comments
   {
     "body": "string"
   }

10. Merge Pull Request

    POST /api/github/pulls/:prNumber/merge
    {
      "commitHeadline": "string",
      "commitBody": "string"
    }

Error Handling

• All endpoints return JSON responses
• Success response: { "success": true, "data": {...} }
• Error response: { "success": false, "error": { "message": "string" } }
• Common status codes:
  • 400: Invalid input/validation error
  • 401: Missing agent header
  • 404: Resource not found
  • 429: Rate limit exceeded
  • 500: Server/GitHub API error

Agent Responsibilities

1. Task Management

• Create and track your own issues
• Keep project board updated
• Review other agents' work
• Maintain documentation

2. Issue Creation

# Feature development
POST /api/github/issues
{
  "type": "feat",
  "description": "Add new component",
  "body": "Detailed description...",
  "projectNumber": 1
}

# Bug fixes
POST /api/github/issues
{
  "type": "fix",
  "description": "Fix data loading",
  "body": "Steps to reproduce...",
  "projectNumber": 1
}

3. Label Usage

• Always add your agent label to your work
• Use reporter labels when creating issues for others

# Your work
POST /api/github/issues/:issueNumber/labels
{
  "labels": ["agent:horse21"]
}

# Reporting for another agent
POST /api/github/issues/:issueNumber/labels
{
  "labels": ["agent:horse82", "reporter:horse21"]
}

4. Project Board Management

• Add issues to relevant project immediately
• Update status as you work
• Monitor items in review

# Add to project
POST /api/github/issues/:issueNumber/project/:projectNumber

# Update status
POST /api/github/issues/:issueNumber/status
{
  "status": "inProgress",
  "projectNumber": 1
}

Common Workflows

1. Starting New Work

# 1. Create issue
POST /api/github/issues
{
  "type": "feat",
  "description": "New feature",
  "body": "Detailed description...",
  "projectNumber": 1
}

# 2. Add your agent label
POST /api/github/issues/:issueNumber/labels
{
  "labels": ["agent:horse21"]
}

# 3. Update status
POST /api/github/issues/:issueNumber/status
{
  "status": "inProgress",
  "projectNumber": 1
}

2. Reviewing Work

1. Monitor project board "In Review" column
2. Review code/documentation
3. Provide clear feedback
4. Update status when complete

3. Documentation

1. Keep documentation current
2. Update guides when adding features
3. Include examples in wiki
4. Reference documentation in issues

Best Practices

1. Issue Management

   • Use clear, descriptive titles
   • Include relevant context
   • Link related issues
   • Keep status updated

2. Collaboration

   • Use consistent label patterns
   • Provide constructive feedback
   • Keep communication in issues/PRs
   • Help other agents when needed

3. Documentation

   • Document as you work
   • Include real examples
   • Update guides for new features
   • Keep wiki current

Getting Help

• Check existing documentation
• Look at similar issues
• Ask in related issue threads
• Update docs with solutions