EN Architecture - jaeseongs95/agent-governance-suite GitHub Wiki
한국어 | English
AGS separates specialist judgment, flow coordination, runtime enforcement, and host integration.
┌─────────────────────────────────────────────┐
│ User / Lead Session │
└──────────────────────┬──────────────────────┘
│ goal / scope
▼
┌─────────────────────────────────────────────┐
│ Orchestrator │
│ capability selection / ordering / handoff │
└──────────────┬──────────────────────────────┘
│
┌───────┴────────┐
▼ ▼
┌───────────────┐ ┌───────────────┐
│ Specialist │ │ Specialist │
│ Skills │ │ Skills │
└───────┬───────┘ └───────┬───────┘
│ provider results │
└─────────┬──────────┘
▼
┌─────────────────────────────────────────────┐
│ Local MCP + Contracts + SQLite │
│ plan / revision / evidence / completion │
└──────────────────────┬──────────────────────┘
│
┌────────┴────────┐
▼ ▼
Codex Adapter Claude Adapter
hooks / wake hooks / inbox
skills/<specialist>/ contains capabilities with distinct judgment responsibilities.
Instead of placing every decision into one large agent prompt, AGS separates concerns such as:
- task framing,
- scope validation,
- mutation risk,
- completion evidence,
- independent audit,
- blocker diagnosis,
- and recovery strategy.
This separation makes the decision chain easier to inspect and allows different responsibilities to be independently reviewed.
The orchestrator discovers available provider capabilities and constructs the execution flow.
It distinguishes bootstrap, workflow, and recovery providers, and orders execution according to artifact dependencies and declared constraints.
The orchestrator coordinates specialist work rather than replacing it.
AGS uses explicit data contracts for workflow execution.
Representative contracts include:
TaskEnvelopeSkillDescriptorProviderResultWorkflowPlanStageResultWorkflowReceipt
These contracts make it possible for the runtime to validate what each stage expects, produces, and depends on.
The runtime is responsible for structural execution guarantees such as:
- plan integrity,
- execution order,
- revision control,
- stage result validation,
- artifact dependencies,
- required stages,
- unresolved blockers,
- completion gates,
- execution-observation claims,
- and state recovery.
Workflow state is stored in SQLite so that server restarts do not erase the execution ledger.
Codex and Claude Code differ in session identity, hook events, transcript formats, installation behavior, and wake transport.
AGS keeps those differences at the edge.
Host adapters and overlays translate vendor-specific behavior into common internal contracts. The core runtime therefore does not need to encode every host product directly into the governance model.
Under strict workflow assurance, caller-supplied JSON is not accepted as proof of the actual model or reasoning effort used for a stage.
Supported host adapters bind observed execution metadata to the relevant call. The server then checks properties such as:
- task / run / stage binding,
- input digest,
- freshness,
- one-time use,
- model-class policy,
- and required reasoning effort.
This mechanism does not prove that a model's output is correct.
Its purpose is narrower: to prevent a lower execution configuration from silently satisfying a stage that requires a higher execution class.
The collaboration layer is separate from the workflow database.
- Session Board — discovers who is doing what.
- Messaging — transports actual requests, evidence, findings, and results.
- ACK — records message processing acknowledgement.
- Wake — notifies an idle host session that new work may be available.
These states must not be collapsed into one concept.
Long-running direct tasks can use a separate continuity database for selected checkpoints.
The workflow ledger remains in the workflow database, while direct-task resume information is handled separately.
This keeps workflow audit history and long-running context restoration as distinct responsibilities.