"Where human intent becomes institutional intelligence."

A spec-driven, AI-assisted development framework combining architecture governance, cyberpunk agents, 52 skills, MCPs and engineering workflows.

Upgrading from v2.x? Review the v3 migration guide before moving state, exposing the web side-car, or recompiling catalogs.

• What Is HSEOS?
• What This Does, in Plain English
• How It Works
• The Seven Laws
• Agent Roster
• Prerequisites
• Installation
• Quick Start
• Skills Catalog
• Architecture
• Governance Layers
• Comparison Matrix
• Roadmap
• Getting Help
• Security
• Contributing
• License
• Português (BR)

HSEOS is the Hideaki Software Engineering Operating System — an institutional framework for engineering teams that want AI agents to accelerate delivery without sacrificing architectural integrity or governance.

It solves a specific problem: most AI coding tools are eager but ungoverned. They write code, make assumptions, and forget context between sessions. HSEOS treats the AI as an executor that operates inside an immutable governance layer — constitutional rules, tiered authority boundaries, spec-driven decision gates, and quality hooks that run before every commit.

HSEOS scales from a single developer with a local hseos install to a multi-team enterprise with dedicated agent squads (NYX, VECTOR, CIPHER, GHOST, RAZOR, ORBIT…) each with explicit, auditable scope.

Scenario 1 — You need to implement a new feature safely: Activate GHOST (Code Executor). It reads the spec, checks for relevant ADRs, validates DDD boundaries, and commits only after pre-commit quality gates pass. You get auditable, governed code changes.

Scenario 2 — You need to deploy to production: Activate KUBE (Kubernetes Delivery Operator). It bumps the image tag in platform-gitops, runs Kustomize validation, opens a PR, and waits for ArgoCD sync. No manual manifest editing.

Scenario 3 — You need to evaluate a technical decision: Activate the /rfc skill. It loads your current architecture context from the knowledge vault, structures the problem, evaluates 2+ alternatives, and produces a traceable design doc.

Scenario 4 — You need to document what was just built: Activate QUILL (Knowledge Scribe) or use /doc-project. Full bilingual documentation with placeholder assets, structured guides, and governance templates — generated from the actual codebase.

Scenario 5 — You need to run a full epic from discovery to deploy: Activate ORBIT (Flow Conductor). It orchestrates the full delivery pipeline: NYX → VECTOR → CIPHER → GHOST → GLITCH → FORGE → KUBE → SABLE → QUILL.

Scenario 6 — You have a heterogeneous batch of independent tasks to ship together: Activate SWARM (Parallel Execution Commander). It plans the batch in Opus, dispatches isolated Sonnet/Haiku subagents in parallel waves under .worktrees/, and consolidates 1 commit per task into a single PR.

Scenario 7 — You need to track active agent runs across sessions: HSEOS automatically detects the active run from .hseos/state/project.db at session start. The state-emit-hook.sh shim queries SQLite for the active as_runs entry and wires the session context — no manual env setup required.

Scenario 8 — You need to verify framework integrity after a change: Run hseos verify (integrity check), hseos audit (spec compliance scan), or hseos doctor (full health report). The self-verification suite validates 12 invariants without network calls.

flowchart TD
    H([Human Intent]) --> ORBIT
    ORBIT --> NYX[NYX\nDiscovery]
    ORBIT --> VECTOR[VECTOR\nPlanning]
    NYX --> CIPHER[CIPHER\nArchitecture]
    VECTOR --> CIPHER
    CIPHER --> GHOST[GHOST\nImplementation]
    CIPHER --> PRISM[PRISM\nUX/Design]
    GHOST --> GLITCH[GLITCH\nValidation]
    PRISM --> GHOST
    GLITCH --> FORGE[FORGE\nBuild & Push]
    FORGE --> KUBE[KUBE\nGitOps Deploy]
    KUBE --> SABLE[SABLE\nRuntime Verify]
    SABLE --> QUILL[QUILL\nDocumentation]
    QUILL --> D([Delivered])

    style H fill:#1a1a2e,color:#fff
    style D fill:#1a1a2e,color:#fff
    style ORBIT fill:#4a0080,color:#fff

Each step is governed by skills loaded automatically from the registry. Agents cannot skip constitutional rules, cannot commit without passing quality gates, and cannot take destructive actions without a Human-in-the-Loop gate.

1. Specs are sovereign — all agents read specs before acting
2. Ambiguity triggers stop — no autonomous resolution of conflicts
3. ADRs are mandatory for every architectural trade-off
4. Authority is explicit — every agent knows exactly what it can and cannot do
5. GitHub is truth — chat, memory, and assumption are not authoritative
6. Enforcement is structural — governance is not optional
7. Humans decide — agents execute

Plus HSEOS-MASTER (src/core/agents/hseos-master.agent.yaml) — the meta/bootstrap executor for generic core-module tasks, outside the delivery flow.

release_version=3.3.1
release_dir="$(mktemp -d)"
gh release download "v${release_version}" \
  --repo marciohideaki/enterprise-hseos \
  --dir "${release_dir}"
(cd "${release_dir}" && sha256sum -c SHA256SUMS)
npm install --global "${release_dir}/hseos-${release_version}.tgz"
hseos --version
hseos install

Use sudo only when npm prefix --global identifies a system-owned prefix that the current administrator cannot write. Do not use sudo with NVM, fnm, asdf, Volta, or another user-managed Node installation; it selects the wrong runtime context and can leave root-owned files in the user's package directory. Run the verification commands with the same Node/npm context used for installation.

The release is installed from the exact tarball covered by SHA256SUMS; HSEOS is not currently published under the unscoped hseos name on npm. Reinstall the previous verified GitHub asset to roll back.

This sets up:

• .claude/commands/ — agent commands as Claude Code slash commands (one file per agent + helpers)
• .claude/hooks.json — Claude Code PreToolUse / UserPromptSubmit hooks (skill suggestion, CLAUDE.md guard, SWARM gate)
• .codex/config.toml + .codex/hseos-hooks.json — Codex adapter (when codex is in --tools)
• .hseos/ — agent configurations, workflow definitions, local config, install manifest
• .agents/ — vendor-neutral source: instructions/PROJECT.md, skills/<skill>/SKILL.md, hook + command registries
• .enterprise/ — governance overlay copied from the HSEOS source (constitution, agent authority, policies, 49-skill governance library). Preserved if you already have one.
• AGENTS.md — minimal platform adapter at the project root pointing at .agents/instructions/PROJECT.md. Preserved if you already authored one.
• .git/hooks/pre-commit — runs scripts/governance/quality-gates.sh when present. Skipped when .git/ is absent or when you pass --no-git-hooks. Existing hooks are never overwritten.

Installation is driven by an auditable capability catalog (ADR-0016). General profiles include minimal, developer (default), governance, gitops, ado, solo, and full. Agent runtime candidates additionally include agent-reference, agent-openai-compatible-candidate, the delegated hosted-agent candidates, and a sandboxed ACP one-shot candidate. The governance baseline is always included and cannot be deselected; components with external prerequisites (ADO, sandbox, telemetry, axon-bridge, second-brain) are optional and degrade gracefully when unmet.

hseos install-plan --list-profiles     # discover profiles
hseos install-plan --profile gitops    # dry-run: components, skills, paths, prerequisites
hseos install --profile developer      # install a profile
hseos install --skills pr-review,rfc   # or baseline + individual skills
hseos agent-provider-conformance --verify --require-ready # verify selected provider manifests and suites

See docs/capabilities.md for the full profile/component/prerequisite reference.

# Claude Code only (default)
hseos install --tools claude-code

# Multiple tools
hseos install --tools claude-code,codex,gemini

# Governance files only (no IDE setup)
hseos install --tools none

Supported tools: claude-code, cursor, windsurf, gemini, codex, antigravity, github-copilot, cline

hseos status              # installation status + module versions
hseos agent-core verify   # hash-pinned integrity of compiled artifacts

status reports the installation manifest and installed modules; agent-core verify validates every compiled skill/agent against the hashes pinned in .agents/manifest.yaml.

The package includes a vendor-neutral, opt-in setup flow for an operator-supplied PostgreSQL service. It applies migrations, seeds the current governance, writes the project binding, starts the loopback control plane/UI and configures read-only MCP access without persisting secrets. See docs/MANAGED-GOVERNANCE.md for the complete procedure. When configured, a non-blocking session preflight compares the local Constitution with the active catalog projection; adapters without native SessionStart support use the documented CLI fallback.

Read CLAUDE.md first — always.

# 1. Read the constitutional entry point
cat CLAUDE.md

# 2. Check available agents
cat AGENTS.md

# 3. Activate an agent (example: solo feature dev)
# In Claude Code: type "BLITZ" or activate via slash command

Standard delivery:

NYX (discover) → VECTOR (plan) → CIPHER (architect) → PRISM (ux)
→ RAZOR (sprint prep) → GHOST (implement) → GLITCH (validate)
→ FORGE (build) → KUBE (deploy) → SABLE (verify) → QUILL (document)

Solo / fast delivery:

BLITZ → FORGE → KUBE → SABLE

Orchestrated epic:

# Inspect workflows
hseos workflow list

# Validate readiness before execution
hseos workflow validate <workflow-id> --repo <path> --profile full

# Initialize and advance
hseos workflow init <workflow-id>
hseos workflow advance

52 skills auto-loaded from the registry based on task context. You never load skills manually — agents match triggers and load the minimum tier needed.

See full catalog: docs/skills.md · Registry: .enterprise/governance/agent-skills/SKILLS-REGISTRY.md

graph TB
    subgraph "Human Layer"
        H[Developer / Tech Lead]
    end

    subgraph "HSEOS Framework"
        CLI[hseos CLI\nInstall · Validate · Workflow]
        REGISTRY[SKILLS-REGISTRY.md\n52 skills · trigger-based]
        HOOKS[Git Hooks\npre-commit · commit-msg]
    end

    subgraph "Governance Layer (.enterprise)"
        CONST[Enterprise Constitution\nSupreme Law]
        SPECS[Specs & ADRs\nArchitecture decisions]
        AGENTS_AUTH[Agent Authority\nPer-agent scope]
    end

    subgraph "Agent Layer (.hseos)"
        ORBIT -.orchestrates.-> NYX & VECTOR & CIPHER
        CIPHER -.feeds.-> GHOST & PRISM
        GHOST -.validates via.-> GLITCH
        GLITCH -.feeds.-> FORGE -.feeds.-> KUBE -.feeds.-> SABLE
    end

    H --> CLI
    CLI --> REGISTRY
    REGISTRY --> AGENTS_AUTH
    AGENTS_AUTH --> CONST
    CONST --> SPECS
    HOOKS --> REGISTRY

hseos/
├── .hseos/                         # HSEOS Agent Framework Core
│   ├── agents/                     # 15 agent YAML definitions
│   ├── workflows/                  # Engineering workflow definitions
│   ├── config/                     # Framework configuration
│   └── data/                       # Templates and data files
│
├── .enterprise/                    # Institutional Governance Overlay
│   ├── .specs/constitution/        # Enterprise Constitution (supreme law)
│   ├── .specs/core/                # Org-wide invariants
│   ├── .specs/decisions/           # Architecture Decision Records
│   ├── agents/                     # Agent authority & constraint definitions
│   ├── governance/agent-skills/    # 52 tiered executable skills
│   ├── policies/                   # Operational governance policies
│   └── playbooks/                  # How to operate within governance
│
├── tools/                          # CLI tooling (hseos-cli, workflow runner)
├── src/                            # Core source (hsm, utility modules)
├── test/                           # Agent schema + installation tests
├── docs/                           # Documentation hub
└── CLAUDE.md                       # Master AI entry point

The root package uses an explicit allowlist for standalone runtime, governance, workflows, source modules, and CLI tooling. Tests, run histories, internal graph evidence, CI files, and logs stay repository-only. The package surface is verified during npm test with bounded file-count and unpacked-size contracts.

HSEOS ships @hseos/adapter-sdk (packages/adapter-sdk/) — a minimal base class and utilities for authoring Bring-Your-Own-Adapter (BYOA) integrations.

const { AdapterBase } = require('@hseos/adapter-sdk');
class MyAdapter extends AdapterBase {
  static get id() {
    return 'my-tool';
  }
  async emit(sources, outputDir) {
    /* write platform files */
  }
}
module.exports = MyAdapter;

Install a third-party adapter via npm (npm install @hseos/adapter-my-tool) — the compiler discovers it automatically via node_modules/@hseos/adapter-*.

Reference BYOA adapter: tools/cli/.../adapters/goose.js implements the Goose (LF AAIF) adapter as the canonical example.

HSEOS ships the dual-format marketplace infrastructure. The four catalog candidates are currently scaffolded: they are visible in plugin list, but are not emitted or installable until their behavior tests pass.

hseos plugin list              # show marketplace catalog
hseos plugin install <id>      # accepts only status: active
hseos plugin doctor            # validates active entries; reports inactive candidates

HSEOS ships a lightweight SQLite-backed state layer at .hseos/state/project.db. It gives you persistent, cross-session visibility into agent runs without a server or cloud dependency.

hseos state-emit start --run <run-id>   # open a run
hseos state list                        # list recent runs
hseos state describe <run-id>           # full run detail
hseos kanban                            # ASCII kanban in terminal

A web side-car (port :3200) serves a real-time kanban board via HTTP + SSE:

hseos state-ui start                     # loopback kanban at localhost:3200
export HSEOS_STATE_UI_TOKEN='replace-with-a-long-random-token'
hseos state-ui start --auth-token-env HSEOS_STATE_UI_TOKEN

Direct non-loopback HTTP is rejected. Remote browser access requires an authenticated TLS reverse proxy forwarding to the loopback side-car; the proxy can inject the configured bearer header.

The state-emit-hook.sh shim is wired as a Claude Code SessionStart hook and auto-detects the active run from SQLite — no HSEOS_CURRENT_RUN_ID env required.

See docs/state-tracking.md for the full reference.

HSEOS ships four native MCP servers, each with dedicated toolsets:

Add to your Claude Code MCP config:

{
  "mcpServers": {
    "hseos-governance": {
      "command": "node",
      "args": ["tools/mcp-hseos-governance/index.js"]
    },
    "hseos-swarm": {
      "command": "node",
      "args": ["tools/mcp-hseos-swarm/index.js"]
    }
  }
}

Three commands for framework health:

hseos agent-core verify   # integrity check — compiled artifacts vs manifest hashes
hseos agent-core audit    # drift scan — warns instead of failing
hseos agent-core doctor   # full health report across the .agents core
hseos pr closeout <num> --approved  # governed PR merge + safe feature branch cleanup

Typical output:

✓ Skill accessibility integrity
✓ Skill adr-compliance integrity
…
✓ Agent SWARM integrity
✓ verify: all checks passed.

• Getting started: docs/getting-started.md — Day 1 guide
• Skills reference: docs/skills.md — full skills catalog
• Workflows: docs/workflows.md — engineering workflows
• State tracking: docs/state-tracking.md — SQLite, kanban, MCP
• Adapter SDK: docs/ADAPTER-GUIDE.md — BYOA adapter authoring
• Migration from v1: docs/MIGRATION-GUIDE-v1-to-v2.md
• Troubleshooting: docs/troubleshooting.md — FAQ and common errors
• Issues: github.com/marciohideaki/hseos/issues
• Discussions: github.com/marciohideaki/hseos/discussions

Please report security vulnerabilities responsibly. See SECURITY.md for our disclosure policy.

Contributions welcome. See CONTRIBUTING.md for setup, commit style, PR checklist, and governance requirements.

MIT — Hideaki Solutions

HSEOS is institutional software. Built for teams that take engineering seriously.

HSEOS é o Hideaki Software Engineering Operating System — um framework institucional para times de engenharia que querem usar agentes de IA para acelerar entregas sem abrir mão da integridade arquitetural ou da governança.

O framework resolve um problema específico: ferramentas de IA são ágeis mas desgoverrnadas. O HSEOS trata a IA como um executor que opera dentro de uma camada de governança imutável — regras constitucionais, limites de autoridade por tier, gates de decisão baseados em spec, e hooks de qualidade que rodam antes de cada commit.

• Implementar feature com segurança → Ative GHOST. Ele lê a spec, verifica ADRs, valida boundaries DDD e commita apenas após os quality gates passarem.
• Fazer deploy em produção → Ative KUBE. Ele atualiza o image tag no platform-gitops, valida o Kustomize e abre o PR.
• Avaliar decisão técnica → Use /rfc. Carrega contexto de arquitetura, estrutura o problema, avalia 2+ alternativas e produz design doc rastreável.
• Documentar o que foi construído → Use /doc-project ou ative QUILL. Documentação bilíngue completa gerada a partir do codebase real.
• Executar epic do discovery ao deploy → Ative ORBIT. Ele orquestra: NYX → VECTOR → CIPHER → GHOST → GLITCH → FORGE → KUBE → SABLE → QUILL.

versao_release=3.3.1
diretorio_release="$(mktemp -d)"
gh release download "v${versao_release}" \
  --repo marciohideaki/enterprise-hseos \
  --dir "${diretorio_release}"
(cd "${diretorio_release}" && sha256sum -c SHA256SUMS)
npm install --global "${diretorio_release}/hseos-${versao_release}.tgz"
hseos --version
hseos install                       # instala o perfil padrão
hseos install --no-git-hooks        # opção sem pre-commit hook

A distribuição oficial atual é o artefato imutável da release no GitHub. O pacote sem escopo hseos não está publicado no npm; por isso npx hseos não é um caminho de instalação suportado. Para rollback, reinstale o asset verificado da versão anterior.

O instalador cria, por padrão:

• .claude/commands/ + .claude/hooks.json (quando claude-code está nos adapters)
• .codex/config.toml + .codex/hseos-hooks.json (quando codex está nos adapters)
• .hseos/ (config, módulos, manifest de instalação)
• .agents/ (skills, hooks registry, instructions/PROJECT.md)
• .enterprise/ copiado do HSEOS source (constituição, agentes, policies, 52 skills de governança) — preservado se já existir
• AGENTS.md na raiz, stub mínimo apontando para .agents/instructions/PROJECT.md — preservado se já existir
• .git/hooks/pre-commit invocando scripts/governance/quality-gates.sh (silencioso se .git/ não existir; existing hook nunca é sobrescrito)

1. Specs são soberanas — todos os agentes leem specs antes de agir
2. Ambiguidade ativa parada — nenhuma resolução autônoma de conflitos
3. ADRs são obrigatórias para toda trade-off arquitetural
4. Autoridade é explícita — cada agente sabe exatamente o que pode e não pode fazer
5. GitHub é a verdade — chat, memória e suposição não são autoritativos
6. Enforcement é estrutural — governança não é opcional
7. Humanos decidem — agentes executam

O HSEOS inclui uma camada de estado baseada em SQLite em .hseos/state/project.db:

hseos kanban          # Kanban ASCII no terminal
hseos state-ui start  # Servidor web com kanban em tempo real (localhost:3200)
hseos verify          # Verificação de integridade
hseos doctor          # Relatório de saúde completo

Veja docs/state-tracking.md para a referência completa.

O HSEOS inclui @hseos/adapter-sdk (packages/adapter-sdk/) — uma classe base mínima e utilitários para criar integrações Bring-Your-Own-Adapter (BYOA).

const { AdapterBase } = require('@hseos/adapter-sdk');
class MeuAdapter extends AdapterBase {
  static get id() {
    return 'minha-ferramenta';
  }
  async emit(sources, outputDir) {
    /* escreve arquivos da plataforma */
  }
}
module.exports = MeuAdapter;

Instale um adapter de terceiros via npm (npm install @hseos/adapter-minha-ferramenta) — o compiler o descobre automaticamente via node_modules/@hseos/adapter-*.

Adapter BYOA de referência: tools/cli/.../adapters/goose.js implementa o adaptador Goose (LF AAIF) como exemplo canônico.

O HSEOS inclui a infraestrutura de marketplace dual-format. Os quatro candidatos do catálogo estão scaffolded: aparecem em plugin list, mas não são emitidos nem instaláveis até passarem por testes de comportamento.

hseos plugin list              # exibir catálogo do marketplace
hseos plugin install <id>      # aceita somente status: active
hseos plugin doctor            # valida ativos e informa candidatos inativos

• Guia de início
• Catálogo de skills
• Workflows de engenharia
• Contribuindo
• Segurança