teixeirazeus/fablize-for-hermes

1. This repository is not an application runtime; it is an agent-discipline package for Hermes Agent. Its architecture is centered on three delivery surfaces: a Hermes skill, a standalone goal-tracking script, and setup/uninstall automation.

2. The core behavioral layer lives in skills/fablize/SKILL.md. That skill is the primary “control plane” for the repository: it encodes always-on operating rules, multi-story completion discipline, debugging procedure, verification grounding, and escalation limits. Hermes loads this skill and applies its instructions during agent sessions.

3. The second major subsystem is scripts/goals.py, a self-contained Python CLI built only on the standard library. It provides the procedural state machine for multi-story work: create goals, advance through the next story, checkpoint completion, and report status. It persists session state under ~/.hermes/fablize/, which makes the goal workflow survive agent/session restarts.

4. The repository’s data flow is intentionally simple: the skill tells the agent how to behave; the agent uses goals.py when a task contains multiple stories or requires verification gates; goals.py writes and reads persistent goal state; the agent then uses that state as evidence for progression and completion. The script does not manage orchestration by itself—it is a stateful helper invoked by the agent.

5. The packs/ directory contains contextual discipline files that the skill can reference. verification-grounding-pack.txt defines the run/observe/fix/re-run loop for artifacts that can be executed or rendered, while investigation-protocol.txt defines the debugging workflow for reproducing issues, forming competing hypotheses, and verifying causal chains. These are supporting knowledge modules, not executable components.

6. The setup/ directory provides installation and removal boundaries for the whole system. setup.sh installs the Hermes skill and can optionally inject an operating block into local or global agent config files; uninstall.sh reverses those changes. The setup layer is the only part that touches environment-level integration, but it does not contain application logic.

7. There is an explicit separation between portable repo assets and persisted runtime state. Repository files define behavior and tooling; runtime goal state lives outside the repo in the Hermes home directory. That boundary matters for architecture diagrams because it shows which parts are version-controlled content versus session-independent operational data.

8. The project includes a small test boundary in tests/test_goals.py, which likely validates the CLI goal engine’s behavior. Combined with Makefile, this suggests the repo treats goals.py as the only executable component worth unit testing, while the skill and packs are mostly static content.

9. .github/workflows/ci.yml provides the continuous-integration boundary. In this repo, CI is mainly about validating the script/test surface and ensuring the packaged discipline files remain consistent, rather than deploying a service or building an artifact.

10. The README and its localized variants are part of the product surface: they explain how the skill is used, how the goal engine is invoked, and how installation changes the surrounding Hermes environment. For an architecture diagram, these docs sit at the user-facing entrypoint, not in the execution path.

11. The system’s main external integration point is Hermes Agent itself. Unlike the original Claude Code version, this port relies on Hermes skill loading and optional agent-config injection rather than hooks or a plugin runtime. That makes the architecture “instruction + helper script + environment setup,” not “plugin + hook callbacks.”

12. Overall, the repo is a thin but layered control package: static behavioral policy in the skill, procedural state management in Python, contextual guidance in packs, and environment wiring in shell scripts. The key flow is agent session → load skill → optionally call goal engine → persist/checkpoint state → verify completion before finalizing work.