personal-agent-os/knowledge-base/hermes-gitea-ecosystem-manual.md

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