# h4ckforge/sentinel architecture

> Architecture diagram of the GitHub repository h4ckforge/sentinel, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-05-23). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/h4ckforge/sentinel
- Repository: https://github.com/h4ckforge/sentinel

## Overview

1. **This repo is not an application server; it is an agent package.**  
   Sentinel is mainly a collection of Markdown prompt assets plus a small Python persistence utility. The runtime that actually hosts the LLM is external (Hermes Agent today, but the repo is intentionally model-agnostic).

2. **Core control plane: the system prompt.**  
   `sentinel_soul_v1.3.md` is the active system prompt and appears to be the primary brain of the agent. The README describes it as a 6-layer prompt covering identity, conduct, decision rules, tone, security behavior, and meta-instructions.

3. **Task execution is organized as skills.**  
   `skills/` contains the operational modules the agent can invoke: `/plan`, `/recon`, `/enum`, `/exploit`, `/post`, `/report`, `/analyze`, `/rt-llm`, `/state`, `/handoff`, and `/checkpoint`. Each skill is a `SKILL.md` document, so the skills are prompt-level behavior specs rather than code libraries.

4. **The engagement lifecycle is encoded as phases.**  
   The skills map directly to a red-team workflow: planning → recon → enumeration → exploitation → post-exploitation → reporting. The architecture should show these as sequential but not strictly linear, since `/analyze`, `/state`, `/handoff`, and `/checkpoint` can be used at any point.

5. **Session state is a shared contract across all skills.**  
   The README defines a common state schema: `session_id`, `mode`, `target`, `last_tool`, `user_level`, `recon_done`, `phase_complete`, `active_skill`, `pending_actions`, `explained_concepts`, and `findings`. `skills/recon/SKILL.md` is noted as the place where this schema is defined, and all other skills read/extend it.

6. **Persistence is externalized into SQLite through a narrow boundary.**  
   The agent itself emits plain-text `CHECKPOINT` blocks; it does not write structured storage directly. The `skills/checkpoint/scripts/` utilities are the bridge to persistence: `init_db.py` initializes the SQLite schema, `checkpoint.py` parses a checkpoint block and writes it, and `recover.py` reconstructs the latest session state back into a checkpoint block.

7. **The database is a separate runtime artifact, not part of the prompt layer.**  
   `sentinel.db` is the persistent session store, with the default path configurable via `SENTINEL_DB`. This creates a clean split between ephemeral model context and durable engagement memory.

8. **Input/output boundary for checkpoints is text-based.**  
   The checkpoint format is a structured plain-text block with explicit fields and an `END_CHECKPOINT` marker. That means the architecture should show the LLM emitting text, the Python script parsing that text, and SQLite storing the resulting state.

9. **Operator guidance and workflow conventions live outside the agent loop.**  
   `operator-guide.md` documents wiki/Obsidian conventions, which suggests a human-facing operational layer for organizing knowledge and engagement notes. This is adjacent to the agent but not part of the core execution pipeline.

10. **Versioned prompt documents show prompt evolution, not separate app versions.**  
   The presence of `sentinel_soul_v1.0.md` through `v1.3.md` implies iterative prompt refinement. Only `v1.3` is active; the others are historical references for prompt evolution.

11. **Dependencies and infrastructure are intentionally minimal.**  
   The repo uses Python 3.10+ and only stdlib modules for the scripts (`sqlite3`, `argparse`, `json`, `re`). There is no application framework, API server, or external service dependency inside the repo; Hermes or another agent runtime is the main external integration point.

12. **The main architecture diagram should therefore show three layers.**  
   First, the external agent runtime loads the system prompt and skills. Second, the skills govern operator interaction and phase-specific reasoning. Third, the checkpoint utilities persist and recover session state in SQLite, creating a feedback loop from runtime output back into long-lived engagement memory.

Main entry points: [`sentinel_soul_v1.3.md`](https://github.com/h4ckforge/sentinel/blob/master/sentinel_soul_v1.3.md) (Soul v1.3), [`skills/state/SKILL.md`](https://github.com/h4ckforge/sentinel/blob/master/skills/state/SKILL.md) (State), [`skills/recon/SKILL.md`](https://github.com/h4ckforge/sentinel/blob/master/skills/recon/SKILL.md) (Recon), [`skills/exploit/SKILL.md`](https://github.com/h4ckforge/sentinel/blob/master/skills/exploit/SKILL.md) (Exploit)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Runtime boundary"]
  node_external_runtime(("Agent runtime<br/>external host"))
end

subgraph group_prompts["Prompt assets"]
  node_system_prompt["Soul v1.3<br/>system prompt"]
  node_prompt_history["Prompt history<br/>prompt versions"]
end

subgraph group_skills["Skills"]
  node_plan_skill["Plan<br/>skill<br/>[SKILL.md]"]
  node_recon_skill["Recon<br/>skill<br/>[SKILL.md]"]
  node_enum_skill["Enum<br/>skill<br/>[SKILL.md]"]
  node_exploit_skill["Exploit<br/>skill<br/>[SKILL.md]"]
  node_post_skill["Post<br/>skill<br/>[SKILL.md]"]
  node_report_skill["Report<br/>skill<br/>[SKILL.md]"]
  node_analyze_skill["Analyze<br/>skill<br/>[SKILL.md]"]
  node_state_skill["State<br/>skill<br/>[SKILL.md]"]
  node_handoff_skill["Handoff<br/>skill<br/>[SKILL.md]"]
  node_rtllm_skill["RT-LLM<br/>skill<br/>[SKILL.md]"]
  node_checkpoint_skill["Checkpoint<br/>skill<br/>[SKILL.md]"]
end

subgraph group_persistence["Persistence"]
  node_checkpoint_block["Checkpoint text<br/>text contract"]
  node_checkpoint_scripts["Checkpoint scripts<br/>python tools"]
  node_init_db_script["Init DB<br/>python script<br/>[init_db.py]"]
  node_checkpoint_script["Write checkpoint<br/>python script<br/>[checkpoint.py]"]
  node_recover_script["Recover state<br/>python script<br/>[recover.py]"]
  node_session_db[("Session DB<br/>sqlite store")]
end

subgraph group_ops["Operator layer"]
  node_operator_guide["Operator guide<br/>operator notes<br/>[operator-guide.md]"]
end

node_external_runtime -->|"loads"| node_system_prompt
node_external_runtime -.->|"references"| node_prompt_history
node_external_runtime -.->|"consults"| node_operator_guide
node_system_prompt -->|"governs"| node_plan_skill
node_system_prompt -->|"governs"| node_recon_skill
node_system_prompt -->|"governs"| node_enum_skill
node_system_prompt -->|"governs"| node_exploit_skill
node_system_prompt -->|"governs"| node_post_skill
node_system_prompt -->|"governs"| node_report_skill
node_system_prompt -->|"governs"| node_analyze_skill
node_system_prompt -->|"governs"| node_state_skill
node_system_prompt -->|"governs"| node_handoff_skill
node_system_prompt -->|"governs"| node_rtllm_skill
node_system_prompt -->|"governs"| node_checkpoint_skill
node_plan_skill -->|"leads to"| node_recon_skill
node_recon_skill -->|"feeds"| node_enum_skill
node_enum_skill -->|"feeds"| node_exploit_skill
node_exploit_skill -->|"feeds"| node_post_skill
node_post_skill -->|"feeds"| node_report_skill
node_analyze_skill -.->|"supports"| node_recon_skill
node_analyze_skill -.->|"supports"| node_exploit_skill
node_state_skill -->|"defines"| node_recon_skill
node_state_skill -.->|"shared by"| node_enum_skill
node_state_skill -.->|"shared by"| node_exploit_skill
node_state_skill -.->|"shared by"| node_post_skill
node_state_skill -.->|"shared by"| node_report_skill
node_state_skill -.->|"shared by"| node_handoff_skill
node_state_skill -.->|"shared by"| node_checkpoint_skill
node_checkpoint_skill -->|"emits"| node_checkpoint_block
node_checkpoint_block -->|"parsed by"| node_checkpoint_script
node_checkpoint_script -->|"belongs to"| node_checkpoint_scripts
node_checkpoint_scripts -->|"contains"| node_init_db_script
node_checkpoint_scripts -->|"contains"| node_recover_script
node_checkpoint_script -->|"writes"| node_session_db
node_init_db_script -->|"initializes"| node_session_db
node_recover_script -->|"reads"| node_session_db
node_session_db -.->|"restores as"| node_checkpoint_block

click node_system_prompt "https://github.com/h4ckforge/sentinel/blob/master/sentinel_soul_v1.3.md"
click node_prompt_history "https://github.com/h4ckforge/sentinel/blob/master/sentinel_soul_v1.0.md"
click node_operator_guide "https://github.com/h4ckforge/sentinel/blob/master/operator-guide.md"
click node_plan_skill "https://github.com/h4ckforge/sentinel/blob/master/skills/plan/SKILL.md"
click node_recon_skill "https://github.com/h4ckforge/sentinel/blob/master/skills/recon/SKILL.md"
click node_enum_skill "https://github.com/h4ckforge/sentinel/blob/master/skills/enum/SKILL.md"
click node_exploit_skill "https://github.com/h4ckforge/sentinel/blob/master/skills/exploit/SKILL.md"
click node_post_skill "https://github.com/h4ckforge/sentinel/blob/master/skills/post/SKILL.md"
click node_report_skill "https://github.com/h4ckforge/sentinel/blob/master/skills/report/SKILL.md"
click node_analyze_skill "https://github.com/h4ckforge/sentinel/blob/master/skills/analyze/SKILL.md"
click node_state_skill "https://github.com/h4ckforge/sentinel/blob/master/skills/state/SKILL.md"
click node_handoff_skill "https://github.com/h4ckforge/sentinel/blob/master/skills/handoff/SKILL.md"
click node_rtllm_skill "https://github.com/h4ckforge/sentinel/blob/master/skills/rt-llm/SKILL.md"
click node_checkpoint_skill "https://github.com/h4ckforge/sentinel/blob/master/skills/checkpoint/SKILL.md"
click node_checkpoint_scripts "https://github.com/h4ckforge/sentinel/tree/master/skills/checkpoint/scripts"
click node_init_db_script "https://github.com/h4ckforge/sentinel/blob/master/skills/checkpoint/scripts/init_db.py"
click node_checkpoint_script "https://github.com/h4ckforge/sentinel/blob/master/skills/checkpoint/scripts/checkpoint.py"
click node_recover_script "https://github.com/h4ckforge/sentinel/blob/master/skills/checkpoint/scripts/recover.py"

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_external_runtime toneBlue
class node_system_prompt,node_prompt_history toneAmber
class node_plan_skill,node_recon_skill,node_enum_skill,node_exploit_skill,node_post_skill,node_report_skill,node_analyze_skill,node_state_skill,node_handoff_skill,node_rtllm_skill,node_checkpoint_skill toneMint
class node_checkpoint_block,node_checkpoint_scripts,node_init_db_script,node_checkpoint_script,node_recover_script,node_session_db toneRose
class node_operator_guide toneIndigo
```

## Components

### Runtime boundary

External LLM host that loads the agent prompt package

- **Agent runtime**: external host · External LLM host such as Hermes that executes the prompt package

### Prompt assets

System prompt and supporting operator guidance

- [Soul v1.3](https://github.com/h4ckforge/sentinel/blob/master/sentinel_soul_v1.3.md): system prompt · Active 6-layer system prompt that acts as the agent's control plane · `sentinel_soul_v1.3.md`
- [Prompt history](https://github.com/h4ckforge/sentinel/blob/master/sentinel_soul_v1.0.md): prompt versions · Earlier sentinel_soul versions that show prompt evolution · `sentinel_soul_v1.0.md`

### Skills

Operational prompt modules for the engagement lifecycle

- [Plan](https://github.com/h4ckforge/sentinel/blob/master/skills/plan/SKILL.md): skill · Initial engagement framing and task decomposition · `skills/plan/SKILL.md`
- [Recon](https://github.com/h4ckforge/sentinel/blob/master/skills/recon/SKILL.md): skill · Target discovery and shared session-state schema source · `skills/recon/SKILL.md`
- [Enum](https://github.com/h4ckforge/sentinel/blob/master/skills/enum/SKILL.md): skill · Enumeration and structure discovery · `skills/enum/SKILL.md`
- [Exploit](https://github.com/h4ckforge/sentinel/blob/master/skills/exploit/SKILL.md): skill · Controlled exploitation workflow · `skills/exploit/SKILL.md`
- [Post](https://github.com/h4ckforge/sentinel/blob/master/skills/post/SKILL.md): skill · Post-exploitation actions and follow-on steps · `skills/post/SKILL.md`
- [Report](https://github.com/h4ckforge/sentinel/blob/master/skills/report/SKILL.md): skill · Findings synthesis and reporting · `skills/report/SKILL.md`
- [Analyze](https://github.com/h4ckforge/sentinel/blob/master/skills/analyze/SKILL.md): skill · Cross-cutting reasoning and interpretation · `skills/analyze/SKILL.md`
- [State](https://github.com/h4ckforge/sentinel/blob/master/skills/state/SKILL.md): skill · Shared session-state contract and coordination surface · `skills/state/SKILL.md`
- [Handoff](https://github.com/h4ckforge/sentinel/blob/master/skills/handoff/SKILL.md): skill · Transfer of context between operators or stages · `skills/handoff/SKILL.md`
- [RT-LLM](https://github.com/h4ckforge/sentinel/blob/master/skills/rt-llm/SKILL.md): skill · Runtime-facing LLM interaction helper · `skills/rt-llm/SKILL.md`
- [Checkpoint](https://github.com/h4ckforge/sentinel/blob/master/skills/checkpoint/SKILL.md): skill · Text checkpoint boundary between the agent and persistence · `skills/checkpoint/SKILL.md`

### Persistence

Checkpoint parsing and SQLite-backed session memory

- **Checkpoint text**: text contract · Structured plain-text block emitted by the agent and parsed by persistence tools
- [Checkpoint scripts](https://github.com/h4ckforge/sentinel/tree/master/skills/checkpoint/scripts): python tools · Utilities that initialize, write, and recover session state · `skills/checkpoint/scripts`
- [Init DB](https://github.com/h4ckforge/sentinel/blob/master/skills/checkpoint/scripts/init_db.py): python script · Initializes the SQLite schema · `skills/checkpoint/scripts/init_db.py`
- [Write checkpoint](https://github.com/h4ckforge/sentinel/blob/master/skills/checkpoint/scripts/checkpoint.py): python script · Parses checkpoint blocks and writes session state · `skills/checkpoint/scripts/checkpoint.py`
- [Recover state](https://github.com/h4ckforge/sentinel/blob/master/skills/checkpoint/scripts/recover.py): python script · Reconstructs the latest session state into a checkpoint block · `skills/checkpoint/scripts/recover.py`
- **Session DB**: sqlite store · Durable session memory backing the checkpoint workflow

### Operator layer

Human-facing workflow conventions and notes

- [Operator guide](https://github.com/h4ckforge/sentinel/blob/master/operator-guide.md): operator notes · Human workflow and wiki/Obsidian conventions · `operator-guide.md`

## Connections

- Agent runtime → Soul v1.3: loads · The external agent runtime loads the active system prompt
- Agent runtime → Prompt history: references · Historical prompt versions document evolution, not runtime behavior
- Agent runtime → Operator guide: consults · Operators use the guide alongside the runtime workflow
- Soul v1.3 → Plan: governs · The system prompt defines how skills are selected and executed
- Soul v1.3 → Recon: governs · The system prompt governs recon behavior and state setup
- Soul v1.3 → Enum: governs · The system prompt governs enumeration behavior
- Soul v1.3 → Exploit: governs · The system prompt governs exploitation behavior
- Soul v1.3 → Post: governs · The system prompt governs post-exploitation behavior
- Soul v1.3 → Report: governs · The system prompt governs reporting behavior
- Soul v1.3 → Analyze: governs · The system prompt governs cross-cutting analysis
- Soul v1.3 → State: governs · The system prompt governs shared session-state handling
- Soul v1.3 → Handoff: governs · The system prompt governs context handoff behavior
- Soul v1.3 → RT-LLM: governs · The system prompt governs runtime-facing LLM interaction
- Soul v1.3 → Checkpoint: governs · The system prompt governs checkpoint emission and recovery
- Plan → Recon: leads to · Planning typically precedes target recon
- Recon → Enum: feeds · Recon findings inform enumeration
- Enum → Exploit: feeds · Enumeration results inform exploitation choices
- Exploit → Post: feeds · Successful exploitation leads into post-exploitation
- Post → Report: feeds · Post-exploitation findings are summarized in reporting
- Analyze → Recon: supports · Analysis can be used at any stage, especially during recon
- Analyze → Exploit: supports · Analysis can inform exploitation decisions
- State → Recon: defines · Recon defines the shared session-state schema
- State → Enum: shared by · Enumeration reads and extends the shared state
- State → Exploit: shared by · Exploitation reads and extends the shared state
- State → Post: shared by · Post-exploitation reads and extends the shared state
- State → Report: shared by · Reporting consumes the shared state and findings
- State → Handoff: shared by · Handoffs preserve the same session contract
- State → Checkpoint: shared by · Checkpointing persists the shared session contract
- Checkpoint → Checkpoint text: emits · The agent emits a structured plain-text checkpoint block
- Checkpoint text → Write checkpoint: parsed by · The checkpoint utility parses the text contract
- Write checkpoint → Checkpoint scripts: belongs to · Checkpoint writer is part of the scripts boundary
- Checkpoint scripts → Init DB: contains · Schema initialization utility
- Checkpoint scripts → Recover state: contains · State recovery utility
- Write checkpoint → Session DB: writes · Parsed state is persisted in SQLite
- Init DB → Session DB: initializes · Creates or prepares the SQLite session store
- Recover state → Session DB: reads · Recovery pulls the latest session state from SQLite
- Session DB → Checkpoint text: restores as · Persisted state can be reconstructed into checkpoint text
