Add Hermes Gitea Ecosystem Manual to knowledge-base (read-only policy on Ty_Tech respected). Synthesized from current repo structures, workflows, and verified ops patterns.

2026-06-21 19:38:52 +00:00
parent 8a75bd6ead
commit 9b8191dfce
1 changed files with 107 additions and 0 deletions
@@ -0,0 +1,107 @@
 # 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**