Skip to content

Architecture

Jump to bottom
Josemalyson Oliveira edited this page Jun 27, 2026 · 1 revision

Architecture

Technical architecture reference for HES.

Conceptual Model

HES is a prompt engineering framework — it is a set of instructions (skill files) that an LLM reads and follows when acting as a coding agent. The LLM IS the runtime.

Core Components

┌─────────────────────────────────────────────────────────────┐
│                      AI Agent (LLM)                         │
├─────────────────────────────────────────────────────────────┤
│                      HES Harness                            │
├─────────────────────────────────────────────────────────────┤
│  SKILL.md (orchestrator)                                    │
│  ├── skills/XX-name.md (phase skills)                       │
│  ├── .hes/state/current.json (state machine)                │
│  ├── .hes/agents/registry.json (agent registry)             │
│  ├── .hes/schemas/*.json (handoff schemas)                  │
│  └── scripts/hooks/*.sh (automation)                        │
└─────────────────────────────────────────────────────────────┘

State Machine

The central mechanism is a phase-locked state machine stored in .hes/state/current.json:

ZERO → DISCOVERY → SPEC → DESIGN → DATA → RED → GREEN → SECURITY → REVIEW → DONE

Bootstrap States

State Condition Action
ZERO No .hes/ directory Trigger auto-install
ORPHAN .hes/ exists but no current.json Trigger legacy recovery
LEGACY No .hes/ but src/ exists Trigger inventory + bootstrap
INSTALLED_INCOMPLETE current.json exists but artifacts missing Silent auto-complete
HARNESS_READY Everything in place Ask "What is the first feature?"

3 Regulation Dimensions

Based on Martin Fowler's framework (2026):

1. Maintainability Harness

Internal code quality:

  • Coverage ≥ 80%
  • Linters
  • Complexity checks

2. Architecture Fitness Harness

Module boundaries:

  • Architectural drift detection
  • ArchUnit rules
  • dependency-cruiser

3. Behaviour Harness

Code does what the spec says:

  • BDD scenarios
  • Traceability: BR → scenario → test

Learning Loop

Hot Path (during session)

Error → write to lessons.md immediately → same lesson 2x → promote to skill file

Offline (every 3 cycles or /hes report)

Analyze events.log → identify patterns → improve guides/sensors

Event Sourcing

Every state transition is logged to events.log:

{
  "timestamp": "2026-06-27T10:00:00Z",
  "event": "phase_transition",
  "from": "DISCOVERY",
  "to": "SPEC",
  "feature": "user-auth",
  "artifacts": ["docs/discovery.md", "docs/business-rules.md"]
}

Multi-Feature Dependency Graph

HES supports multiple concurrent features with dependency tracking:

{
  "features": {
    "auth": { "status": "GREEN", "depends_on": [] },
    "api": { "status": "SPEC", "depends_on": ["auth"] },
    "ui": { "status": "ZERO", "depends_on": ["api"] }
  }
}

v4.0 Multi-Agent Architecture

The target state transforms HES from a sequential orchestrator into an autonomous software factory:

/hes start --parallel
  → planner.md (task decomposition)
  → orchestrator.md (agent fleet dispatch)
  → [Agent Fleet] (parallel execution in Git worktrees)
  → integration
  → sequential flow (SECURITY → REVIEW → DONE)

Design Decisions

Decision Rationale
Markdown as primary format Universal, version-controlled, human-readable
Phase-locked workflow Prevents skipping critical steps
Step budget Prevents infinite loops
Event sourcing Full audit trail
JSON schemas Typed handoffs between phases
Trust policy Controlled self-modification

References

  • Skills — All skill files
  • Phases — Detailed phase descriptions
  • Rules — The 34 rules
  • Agents — Agent registry

Last updated: June 2026

Clone this wiki locally