# Hermes Gitea & Agent Development Ecosystem Manual

**Version 1.0 | June 21, 2026**

This manual documents the full Hermes AI Agent Development setup on Gitea. It covers repositories, the role-based multi-agent system, workflows, the critical verified operations protocol, and how to work within it. Maintained as part of your personal-agent-os knowledge base.

## 1. Introduction & Philosophy

The Hermes ecosystem uses layered repositories for clear separation of concerns:

- **core-planning (Ty_Tech)**: Strategic HQ. High-level planning, task decomposition, ADRs, research synthesis, team guidelines, KANBAN workflows. *Read-only for you now.*
- **template-app (Ty_Tech)**: Reusable starter template with agent role files (`agents/HA_*.md`), issue/PR templates. Fork for new feature projects. *Read-only.*
- **hermes-agent-development (Ty_Tech)**: Active implementation hub (new repo). Core Hermes code, orchestration, persistent agent OS, skills hub, integrations. *Read-only.*
- **personal-agent-os (Tony_tech)**: Your private git-backed external brain. Knowledge base, project tracking, automation patterns, agent configs. *Writable.*
- **research (Ty_Tech)**: Informal research capture. *Read-only.*

**Philosophy**: Planning-first. Durable Kanban coordination. Role specialization with clear handoffs. Verified SHA-based operations for all mutations (no hallucinations). Traceability from plans to code. Small atomic commits.

## 2. Accessing Gitea

- **Web**: https://gitea.vps1.afterthedemo.com/ (Ty_Tech org and your Tony_tech repos)
- **Git**: Clone via HTTPS or SSH. Use existing PuTTY SSH tunnels for secure access from local/VPS.
- **MCP Tools**: TonyTechMCP connector provides `tonytechmcp___*` tools for programmatic access.

**Important**: You specified read-only on Ty_Tech org repos. All writes go through Tony_tech/personal-agent-os or other personal scopes.

## 3. The Role-Based Multi-Agent System

Agents have specialized roles for efficient, traceable collaboration (defined in template-app/agents/):

| Role | Agent Name | Primary Responsibility | Key Outputs |
|------|------------|------------------------|-------------|
| Planner | HA_Planner | Task decomposition, planning, prioritization | Issues, plans, roadmaps, status reports |
| Architect | HA_Architect | System design, technical decisions | ADRs, architecture docs |
| Coder | HA_Coder | Feature/fix implementation | Code, branches, PRs |
| Reviewer | HA_Reviewer | Quality, security, best practices | PR feedback |
| Tester | HA_Tester | Test creation & validation | Test results, bugs |
| Orchestrator | HA_Orchestrator | Workflow coordination, routing, unblocking | Task handoffs, Kanban management |
| DevOps | HA_DevOps | CI/CD, infrastructure, deployments | Pipelines, environments |

## 4. Core Workflows

### Planning-First
All major work starts with planning/decomposition in core-planning (read the docs there for details).

### Starting New Projects
Use template-app as base. For core Hermes work, extend hermes-agent-development (read-only for now; plan changes via issues).

### Kanban Coordination
Use Hermes Kanban for multi-agent or human-overseen work (durable audit trail).

**Recommended statuses** (from core-planning docs):
- triage → todo → ready → running → blocked/done/archived

**Task updates**: Use SCRUM format (What I did / Doing next / Blockers). Escalate to human only for external dependencies, strategic conflicts, major decisions, or prolonged blockers.

### Branching & PRs
- `main` protected.
- Feature branches + PRs.
- Reference planning issues.
- PRs reviewed by HA_Reviewer.

### Human Role
Strategic overseer: set direction, review aggregated reports, handle qualified escalations.

## 5. Verified Gitea Operations Protocol (Mandatory for Writes)

**Never** mutate without this. Enforced by gitea-mcp-verified-ops skill.

1. **Pre-verify**: Read current state/SHA (e.g., `tonytechmcp___get_file_contents`, list_branches, get_tree).
2. **Mutate**: Use exact SHA for updates/deletes in create_or_update_file (or other write tools). For new files, omit SHA after confirming absence.
3. **Post-verify**: Immediately re-read and confirm new SHA/content matches intent.
4. Abort/report on mismatches.

This applies to Tony_tech writes. Always use fresh reads before asserting state.

**Key tools** (TonyTechMCP):
- Read: get_file_contents, get_repository_tree, list_org_repos (Ty_Tech read OK), list_my_repos
- Write: create_or_update_file (with SHA), create_repo (in Tony_tech OK), fork_repo, etc.

## 6. Personal-Agent-OS Structure (Your Writable Layer)

- `knowledge-base/` — Research, patterns, manuals (this manual lives here)
- `projects/hermes-persistent-os/` — Specific Hermes OS work
- `agent-config/`, `agent-comms/`, `templates/`, `_meta/decision-log.md`

**How to include docs**: Add/edit Markdown files here (e.g., this manual). Regenerate PDFs as needed via scripts.

## 7. Best Practices

- Plan in core-planning (read).
- Use Kanban for coordination.
- Verified protocol for all writes (in Tony_tech).
- Small commits, explicit handoffs, traceability.
- Treat docs as living (update this manual as processes evolve).

## Quick Reference

- Gitea URL: https://gitea.vps1.afterthedemo.com/Tony_tech/personal-agent-os (and Ty_Tech read-only)
- New manual PDF: See artifacts or regenerate via Python script in personal-agent-os.
- For questions: Use agent-comms/grok-inbox/ or decision-log.

*This manual was synthesized from your Gitea state. Update it here in personal-agent-os as needed. No writes performed to Ty_Tech.*

---

**End of Manual**