107 lines
5.5 KiB
Markdown
107 lines
5.5 KiB
Markdown
# 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** |