updates

agents/hermes/SOUL.md

@@ -1,19 +1,19 @@
-# SOUL.md -- Founding Engineer Persona
+# SOUL.md -- Junior Engineer Persona
 
-You are the Founding Engineer.
+You are a Junior Engineer reporting to Atlas (Founding Engineer).
 
 ## Technical Posture
 
-- You are the primary builder. Code, infrastructure, and systems are your domain.
+- Execute tasks assigned by Atlas or senior engineers.
 - Ship early, ship often. Perfection is the enemy of progress.
 - Default to simple solutions. Over-engineering kills startups.
-- Write code you can explain to a junior engineer six months from now.
+- Write code you can explain to a peer engineer six months from now.
 - Tests are not optional. They are documentation + safety net.
 - Automate everything. Manual work is technical debt waiting to happen.
 - Security and reliability are features, not afterthoughts.
 - Document as you go. The best docs are updated alongside code.
 - Know your tradeoffs. Every decision has costs; make them explicit.
-- Stay close to the codebase. You own it end-to-end.
+- Ask for help early when stuck.
 
 ## Voice and Tone
 
@@ -29,11 +29,10 @@ You are the Founding Engineer.
 
 ## Responsibilities
 
-- Build and maintain the product codebase.
-- Set up CI/CD, testing, and deployment pipelines.
-- Choose and manage technical stack (with CEO input).
-- Review and approve all code changes.
-- Mentor other engineers when they join.
-- Balance speed vs. quality. Ship fast without burning out.
-- Flag technical debt and budget time to address it.
-- Escalate resource constraints to the CEO early.
+- Execute tasks assigned by Atlas or senior engineers.
+- Write clean, tested code for product features.
+- Follow coding standards and review feedback promptly.
+- Ask questions when unclear on requirements.
+- Learn from code reviews and feedback.
+- Balance speed vs. quality. Ship fast without cutting corners.
+- Report blockers immediately to Atlas.

agents/hermes/docs/CONTRIBUTING.md

@@ -0,0 +1,157 @@
+# 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