# teixeirazeus/fablize-for-hermes architecture

> Architecture diagram of the GitHub repository teixeirazeus/fablize-for-hermes, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-17). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/teixeirazeus/fablize-for-hermes
- Repository: https://github.com/teixeirazeus/fablize-for-hermes

## Overview

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.

Main entry points: [`scripts/goals.py`](https://github.com/teixeirazeus/fablize-for-hermes/blob/main/scripts/goals.py) (Goal CLI), [`skills/fablize/SKILL.md`](https://github.com/teixeirazeus/fablize-for-hermes/blob/main/skills/fablize/SKILL.md) (Fablize skill), [`README.md`](https://github.com/teixeirazeus/fablize-for-hermes/blob/main/README.md) (README), [`setup/setup.sh`](https://github.com/teixeirazeus/fablize-for-hermes/blob/main/setup/setup.sh) (Setup script)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_external["External runtime"]
  node_hermes_agent(("Hermes Agent<br/>external host"))
  node_home_state[("Hermes state<br/>persistent runtime data")]
end

subgraph group_entrypoints["Entry surfaces"]
  node_setup_sh["Setup script<br/>install automation<br/>[setup.sh]"]
  node_uninstall_sh["Uninstall script<br/>removal automation<br/>[uninstall.sh]"]
  node_star_sh["Star script<br/>helper script<br/>[star.sh]"]
  node_block_md["Agent block<br/>config fragment<br/>[fablize-block.md]"]
end

subgraph group_discipline["Behavior layer"]
  node_skill["Fablize skill<br/>agent policy<br/>[SKILL.md]"]
  node_workflow_ref["Quickstart<br/>workflow reference"]
  node_verification_pack["Verification pack<br/>discipline note"]
  node_investigation_pack["Investigation pack<br/>discipline note"]
end

subgraph group_tooling["Goal tooling"]
  node_goal_cli["Goal CLI<br/>python state machine<br/>[goals.py]"]
end

subgraph group_quality["Validation"]
  node_goal_tests["Goal tests<br/>unit tests<br/>[test_goals.py]"]
  node_ci["CI workflow<br/>automation<br/>[ci.yml]"]
  node_makefile["Makefile<br/>build entrypoint"]
end

subgraph group_docs["Documentation"]
  node_readme["README<br/>user guide<br/>[README.md]"]
  node_readme_pt["README PT<br/>localized guide<br/>[README.pt.md]"]
  node_readme_zh["README ZH<br/>localized guide<br/>[README.zh.md]"]
end

node_hermes_agent -->|"loads"| node_skill
node_skill -->|"invokes"| node_goal_cli
node_goal_cli -->|"persists"| node_home_state
node_home_state -->|"restores"| node_goal_cli
node_skill -->|"references"| node_verification_pack
node_skill -->|"references"| node_investigation_pack
node_skill -->|"guides"| node_workflow_ref
node_setup_sh -->|"installs"| node_skill
node_setup_sh -->|"can inject"| node_block_md
node_setup_sh -->|"integrates with"| node_hermes_agent
node_uninstall_sh -->|"removes"| node_block_md
node_uninstall_sh -->|"uninstalls"| node_skill
node_goal_cli -->|"validated by"| node_goal_tests
node_goal_cli -->|"checks"| node_ci
node_makefile -->|"drives"| node_goal_cli
node_ci -->|"runs"| node_goal_tests
node_readme -->|"documents"| node_skill
node_readme -->|"documents"| node_goal_cli
node_readme -->|"documents"| node_setup_sh
node_readme_pt -->|"localizes"| node_readme
node_readme_zh -->|"localizes"| node_readme
node_verification_pack -->|"supports"| node_goal_cli
node_investigation_pack -->|"supports"| node_goal_cli

click node_skill "https://github.com/teixeirazeus/fablize-for-hermes/blob/main/skills/fablize/SKILL.md"
click node_workflow_ref "https://github.com/teixeirazeus/fablize-for-hermes/blob/main/skills/fablize/references/workflow-quickstart.md"
click node_goal_cli "https://github.com/teixeirazeus/fablize-for-hermes/blob/main/scripts/goals.py"
click node_goal_tests "https://github.com/teixeirazeus/fablize-for-hermes/blob/main/tests/test_goals.py"
click node_ci "https://github.com/teixeirazeus/fablize-for-hermes/blob/main/.github/workflows/ci.yml"
click node_setup_sh "https://github.com/teixeirazeus/fablize-for-hermes/blob/main/setup/setup.sh"
click node_uninstall_sh "https://github.com/teixeirazeus/fablize-for-hermes/blob/main/setup/uninstall.sh"
click node_star_sh "https://github.com/teixeirazeus/fablize-for-hermes/blob/main/setup/star.sh"
click node_block_md "https://github.com/teixeirazeus/fablize-for-hermes/blob/main/setup/fablize-block.md"
click node_verification_pack "https://github.com/teixeirazeus/fablize-for-hermes/blob/main/packs/verification-grounding-pack.txt"
click node_investigation_pack "https://github.com/teixeirazeus/fablize-for-hermes/blob/main/packs/investigation-protocol.txt"
click node_readme "https://github.com/teixeirazeus/fablize-for-hermes/blob/main/README.md"
click node_readme_pt "https://github.com/teixeirazeus/fablize-for-hermes/blob/main/README.pt.md"
click node_readme_zh "https://github.com/teixeirazeus/fablize-for-hermes/blob/main/README.zh.md"
click node_makefile "https://github.com/teixeirazeus/fablize-for-hermes/tree/main/Makefile"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_hermes_agent,node_home_state toneBlue
class node_setup_sh,node_uninstall_sh,node_star_sh,node_block_md toneAmber
class node_skill,node_workflow_ref,node_verification_pack,node_investigation_pack toneMint
class node_goal_cli toneRose
class node_goal_tests,node_ci,node_makefile toneIndigo
class node_readme,node_readme_pt,node_readme_zh toneTeal
```

## Components

### External runtime

Hermes Agent and the persisted home-directory state outside the repo.

- **Hermes Agent**: external host · The consuming agent platform that loads the skill and invokes the helper script.
- **Hermes state**: persistent runtime data · Goal state persisted outside the repo under the Hermes home directory.

### Entry surfaces

User-facing documentation and the setup boundary.

- [Setup script](https://github.com/teixeirazeus/fablize-for-hermes/blob/main/setup/setup.sh): install automation · Installs the skill and can inject an operating block into agent config files. · `setup/setup.sh`
- [Uninstall script](https://github.com/teixeirazeus/fablize-for-hermes/blob/main/setup/uninstall.sh): removal automation · Reverses the setup-time environment integration changes. · `setup/uninstall.sh`
- [Star script](https://github.com/teixeirazeus/fablize-for-hermes/blob/main/setup/star.sh): helper script · Additional setup-related shell entrypoint shipped with the installer boundary. · `setup/star.sh`
- [Agent block](https://github.com/teixeirazeus/fablize-for-hermes/blob/main/setup/fablize-block.md): config fragment · Installable operating block used to integrate with local or global agent configuration. · `setup/fablize-block.md`

### Behavior layer

Repo content that defines operating rules and contextual guidance.

- [Fablize skill](https://github.com/teixeirazeus/fablize-for-hermes/blob/main/skills/fablize/SKILL.md): agent policy · Primary control plane: always-on discipline, multi-story flow, verification rules, and escalation limits. · `skills/fablize/SKILL.md`
- [Quickstart](https://github.com/teixeirazeus/fablize-for-hermes/blob/main/skills/fablize/references/workflow-quickstart.md): workflow reference · Short reference for the skill's operating workflow. · `skills/fablize/references/workflow-quickstart.md`
- [Verification pack](https://github.com/teixeirazeus/fablize-for-hermes/blob/main/packs/verification-grounding-pack.txt): discipline note · Run/observe/fix/re-run grounding for executable or renderable artifacts. · `packs/verification-grounding-pack.txt`
- [Investigation pack](https://github.com/teixeirazeus/fablize-for-hermes/blob/main/packs/investigation-protocol.txt): discipline note · Debugging workflow for reproduction, competing hypotheses, and causal verification. · `packs/investigation-protocol.txt`

### Goal tooling

Executable helper and its tests.

- [Goal CLI](https://github.com/teixeirazeus/fablize-for-hermes/blob/main/scripts/goals.py): python state machine · Standard-library CLI for creating goals, advancing stories, checkpointing, and reporting status. · `scripts/goals.py`

### Validation

CI and local validation surface.

- [Goal tests](https://github.com/teixeirazeus/fablize-for-hermes/blob/main/tests/test_goals.py): unit tests · Test boundary for the goal engine behavior. · `tests/test_goals.py`
- [CI workflow](https://github.com/teixeirazeus/fablize-for-hermes/blob/main/.github/workflows/ci.yml): automation · Repository CI boundary for validating the script and packaged discipline files. · `.github/workflows/ci.yml`
- [Makefile](https://github.com/teixeirazeus/fablize-for-hermes/tree/main/Makefile): build entrypoint · Convenience entrypoint for repository checks and scripted workflows. · `Makefile`

### Documentation

Primary and localized README surfaces.

- [README](https://github.com/teixeirazeus/fablize-for-hermes/blob/main/README.md): user guide · Primary documentation for using the skill, goal engine, and setup flow. · `README.md`
- [README PT](https://github.com/teixeirazeus/fablize-for-hermes/blob/main/README.pt.md): localized guide · Portuguese documentation variant. · `README.pt.md`
- [README ZH](https://github.com/teixeirazeus/fablize-for-hermes/blob/main/README.zh.md): localized guide · Chinese documentation variant. · `README.zh.md`

## Connections

- Hermes Agent → Fablize skill: loads · Hermes loads the skill as the primary operating policy.
- Fablize skill → Goal CLI: invokes · The skill directs the agent to use the CLI for multi-story work and checkpoints.
- Goal CLI → Hermes state: persists · Goal/session state is written under the Hermes home directory.
- Hermes state → Goal CLI: restores · The CLI reads persisted state so work survives restarts.
- Fablize skill → Verification pack: references · The skill can consult grounding rules for run/observe/fix/re-run loops.
- Fablize skill → Investigation pack: references · The skill can consult the debugging protocol for issue reproduction and verification.
- Fablize skill → Quickstart: guides · The workflow reference supports the skill's operating procedure.
- Setup script → Fablize skill: installs · Setup installs the skill into the Hermes environment.
- Setup script → Agent block: can inject · Setup may add the agent operating block to local or global config.
- Setup script → Hermes Agent: integrates with · Setup targets Hermes environment integration rather than an in-repo runtime.
- Uninstall script → Agent block: removes · Uninstall reverses the injected configuration boundary.
- Uninstall script → Fablize skill: uninstalls · Uninstall removes the installed skill from the Hermes environment.
- Goal CLI → Goal tests: validated by · The CLI behavior is covered by unit tests.
- Goal CLI → CI workflow: checks · CI is expected to exercise the executable helper surface.
- Makefile → Goal CLI: drives · Makefile provides a convenient local entrypoint for the helper workflow.
- CI workflow → Goal tests: runs · CI validates the test boundary for the goal engine.
- README → Fablize skill: documents · README explains the skill-centric operating model.
- README → Goal CLI: documents · README explains how to invoke the goal engine.
- README → Setup script: documents · README explains installation and environment integration.
- README PT → README: localizes · Portuguese variant of the main guide.
- README ZH → README: localizes · Chinese variant of the main guide.
- Verification pack → Goal CLI: supports · The verification loop supports deciding when a story can be closed.
- Investigation pack → Goal CLI: supports · The debugging protocol supports diagnosing failures before progression.