ArkOS - Agent Runtime Operating System

ArkOS é um protocolo agnóstico de memória operacional para projetos assistidos por agentes de IA.

A ideia central é simples: todo projeto deveria ter uma memória versionada, legível por humanos e agentes, capaz de preservar contexto, decisões, pendências, riscos, validações e handoffs entre sessões.

O ArkOS não é apenas uma pasta. A pasta .ai/ é a implementação padrão do protocolo.

O problema que o ArkOS resolve

Você abre uma IA no projeto. Ela não sabe o que aconteceu antes.

Você explica o contexto. Ela entende metade.

Você troca de IA. Começa tudo de novo.

A IA mexe onde não devia, esquece uma decisão antiga, sugere refatoração fora de hora ou tenta fazer commit sem autorização.

O ArkOS cria uma memória operacional dentro do repositório para que qualquer agente consiga entrar, observar o estado real do projeto, planejar com segurança e executar apenas o que foi autorizado.

Em linguagem simples:

Git guarda o código.
ArkOS guarda o contexto operacional.

O que você verá funcionando em 5 minutos

Depois de instalar o ArkOS em um projeto, você pode abrir uma IA de código e pedir:

arkos observe

A IA deve:

• ler a memória .ai/;
• rodar git status e git log;
• comparar memória e repositório real;
• apontar riscos e pendências;
• sugerir próximos comandos;
• não alterar código;
• não commitar;
• não fazer push.

Depois você pode pedir:

arkos plan

A IA deve gerar um plano em milestones verificáveis, cada uma com objetivo, critério de sucesso, validações, riscos, rollback e próximo passo.

Quando quiser autorizar uma ação específica:

arkos act "corrigir o menor problema detectado no plano"

A IA deve executar apenas esse escopo.

Primeiros 10 minutos

Este é o caminho mais rápido para sentir o "uau".

1. Entre em qualquer projeto com Git

cd meu-projeto

Confirme que o repositório está saudável:

git status

Se houver mudanças pendentes, tudo bem. O ArkOS pode ajudar a observar, mas não instale às cegas em um repositório com trabalho importante sem antes entender o estado atual.

2. Instale o ArkOS no projeto

npx @arksys/arkos@latest install all

Isso cria ou completa a memória .ai/ e instala instruções para agentes:

.ai/
.ai/ARKOS_AGENT_PROMPT.md
AGENTS.md
CLAUDE.md
.cursor/rules/arkos.mdc
.github/copilot-instructions.md

O comando preserva arquivos existentes quando possível. Use --force apenas quando quiser regenerar instruções conscientemente.

3. Audite a instalação

npx @arksys/arkos@latest audit

Você verá se a estrutura .ai/ está compatível e quais marcadores ainda precisam de preenchimento.

4. Abra sua IA de código no projeto

Pode ser Claude Code, Codex, Cursor, Copilot Chat, Gemini CLI ou outra ferramenta que leia arquivos do repositório.

Envie apenas:

arkos observe

Não explique o projeto. Esse é o teste.

Se tudo estiver funcionando, o agente deve descobrir o estado do projeto sozinho lendo o repositório e a memória .ai/.

5. Peça um plano

arkos plan

O agente deve responder com milestones verificáveis.

Um bom plano deve parecer com isto:

Milestone 1: Sincronizar memória operacional
Objetivo: atualizar .ai/ com o HEAD atual.
Critério de sucesso: git status limpo e .ai/ consistente com git log.
Validações: git status, git log --oneline -10, arkos audit.
Riscos: registrar informação não verificada.
Rollback: git restore .ai/.
Próximo passo: validar ambiente real.

6. Autorize uma ação pequena

arkos act "executar o primeiro milestone do plano"

O agente deve agir com escopo limitado, validar o que fez e parar antes de commit ou push.

7. Feche a sessão

Quando terminar uma sessão relevante:

npx @arksys/arkos@latest close --summary "o que foi feito" --next "próximo passo"

Isso atualiza SESSION.md, HANDOFF.md e LOG.md.

Instalação

Use diretamente com npx, sem instalação global:

npx @arksys/arkos@latest install all

Ou instale globalmente:

npm install -g @arksys/arkos
arkos install all

Fluxo recomendado

Para deixar um projeto pronto para agentes de IA:

cd meu-projeto
npx @arksys/arkos@latest install all
npx @arksys/arkos@latest audit

Depois abra Codex, Claude Code, Cursor, Gemini CLI ou Copilot no projeto. O agente encontrará as instruções e executará o protocolo ArkOS.

Em ferramentas com suporte nativo ao comando, você pode digitar:

arkos observe

ou, se a ferramenta tiver slash command configurado:

/arkos

Por segurança, o fluxo ArkOS entra em OBSERVE por padrão: o agente lê, audita, compara e resume, mas não altera código, não commita e não faz push.

Sem suporte nativo, use o handshake:

npx @arksys/arkos@latest handshake

Copie a saída para o agente.

Modos operacionais

ArkOS separa observação, planejamento e execução para evitar que agentes virem workaholics sem autorização humana.

OBSERVE

arkos observe

Modo seguro padrão. O agente deve ler a memória, comparar com o repositório, identificar riscos e sugerir próximos passos.

Ele não deve alterar código de produção, commitar ou fazer push.

PLAN

arkos plan

Modo de planejamento. O agente deve transformar a observação em plano priorizado, sem executar.

O plano deve ser organizado em milestones verificáveis, cada uma com:

1. objetivo;
2. critério de sucesso;
3. validações ou comandos sugeridos;
4. riscos;
5. rollback ou caminho de reversão;
6. próximo passo recomendado.

ACT

arkos act "tarefa autorizada"

Modo de ação. O agente só deve executar a tarefa explicitamente autorizada.

Mesmo em ACT, commit e push exigem autorização separada.

CLOSE

arkos close --summary "sessão concluída" --next "próximo passo"

Fecha a sessão e atualiza a memória operacional.

Rodapé operacional

As instruções geradas pelo ArkOS orientam o agente a terminar respostas operacionais sugerindo próximos comandos ArkOS. O usuário não precisa decorar a CLI.

Exemplo:

Próximos comandos ArkOS sugeridos:
- arkos observe
- arkos plan
- arkos act "corrigir primeiro item do plano"
- arkos close --summary "resumo" --next "próximo passo"

Uso rápido

arkos init        # cria .ai/ no projeto atual
arkos bootstrap   # cria .ai/ e .ai/ARKOS_AGENT_PROMPT.md
arkos install all # cria .ai/ e instruções para agentes
arkos observe     # modo seguro: audita e orienta sem alterar código
arkos plan        # cria plano em milestones verificáveis, sem executar
arkos act "..."   # executa apenas tarefa autorizada
arkos handshake   # imprime o handshake universal em modo observe
arkos open        # alias de handshake
arkos prompt      # imprime o prompt completo para preencher a memória
arkos audit       # verifica estrutura ArkOS, marcadores pendentes e estado Git
arkos doctor      # diagnóstico de saúde operacional da memória ArkOS
arkos status      # mostra resumo operacional
arkos handoff     # imprime .ai/HANDOFF.md
arkos close       # encerra sessão e atualiza SESSION, HANDOFF e LOG

Arquivos gerados por install all

.ai/
.ai/ARKOS_AGENT_PROMPT.md
AGENTS.md                          ← agentes compatíveis com instruções AGENTS.md
CLAUDE.md                          ← Claude Code
.cursor/rules/arkos.mdc             ← Cursor
.github/copilot-instructions.md    ← GitHub Copilot

Exemplo de conversa com uma IA

Você:

arkos observe

IA:

[observado] Memória .ai/ encontrada.
[observado] Branch main sincronizada com origin/main.
[risco] SESSION.md não registra os dois últimos commits.
[pendencia] Atualizar memória operacional antes de nova feature.

Próximos comandos ArkOS sugeridos:
- arkos plan
- arkos act "sincronizar memória ArkOS com HEAD atual"

Você:

arkos plan

IA:

Milestone 1: Sincronizar memória
Objetivo: alinhar .ai/ com o estado real do Git.
Critério de sucesso: SESSION e HANDOFF refletem o HEAD atual.
Validações: git status, git log --oneline -10, arkos audit.
Riscos: registrar inferências como fatos.
Rollback: git restore .ai/.
Próximo passo: validar testes do projeto.

Você:

arkos act "executar milestone 1"

IA:

[observado] Alterei apenas .ai/SESSION.md, .ai/HANDOFF.md e .ai/LOG.md.
[observado] Nenhum código de produção foi alterado.
[observado] Não fiz commit nem push.

Para quais ferramentas funciona?

ArkOS é agnóstico. Ele funciona melhor com agentes que conseguem ler arquivos e rodar comandos no repositório.

Testado em fluxo real com:

• Claude Code;
• OpenAI Codex CLI;
• Gemini CLI;
• Cursor;
• GitHub Copilot instructions.

A regra é simples: se a ferramenta consegue ler o repositório, ela consegue seguir o protocolo.

Quando usar

Use ArkOS quando:

• você trabalha com mais de uma IA no mesmo projeto;
• você alterna entre sessões e perde contexto;
• você precisa que agentes respeitem limites antes de agir;
• você quer handoff claro entre humano e IA;
• você quer registrar decisões, riscos, pendências e validações no próprio repositório.

Evite usar como substituto de Git, testes, issues ou documentação real. ArkOS complementa essas camadas.

O problema, em termos técnicos

Projetos modernos são trabalhados por humanos, assistentes de código, agentes de CLI, copilotos, modelos locais e ferramentas diferentes. Cada agente entra no projeto com pouco contexto e pode repetir análise, desfazer decisões antigas, ignorar riscos ou quebrar fluxos críticos.

Código mostra o que existe. Commits mostram o que mudou. Issues mostram parte do plano. Mas falta uma camada persistente para responder o que o projeto é, como funciona, qual é o estado atual, quais decisões importam e como validar mudanças com segurança.

ArkOS é essa camada.

Princípios

1. O repositório é a fonte da verdade.
2. A memória deve refletir o estado real do projeto.
3. Fatos, inferências e dúvidas devem ser separados.
4. Segredos nunca devem ser copiados para a memória.
5. O próximo agente deve conseguir continuar o trabalho sem perguntar onde está.
6. A memória deve ser útil antes de ser bonita.
7. O protocolo deve ser agnóstico de stack, linguagem, framework e ferramenta de IA.
8. Observar vem antes de planejar; planejar vem antes de agir.
9. Execução exige autorização explícita.

Roadmap

Entregues

• [x] Publicação npm @arksys/arkos
• [x] Especificação inicial do protocolo
• [x] Especificação ArkOS Handshake v1
• [x] Template padrão .ai/
• [x] Prompt de inicialização manual
• [x] CLI arkos init
• [x] CLI arkos bootstrap
• [x] CLI arkos install all (Codex, Claude, Cursor, Copilot)
• [x] CLI arkos observe
• [x] CLI arkos plan com milestones verificáveis
• [x] CLI arkos act
• [x] CLI arkos handshake / arkos open
• [x] CLI arkos audit
• [x] CLI arkos status
• [x] CLI arkos handoff
• [x] CLI arkos close
• [x] Testes automatizados do CLI
• [x] CLI arkos doctor — diagnóstico com Structural Score, Git Score e Memory Score
• [x] Semantic Memory Validator v1 — CONTEXT, DECISIONS, LOG, CHECKLIST e consistência cruzada

Pendentes

• [ ] Estudos de caso reais por tipo de projeto — ver examples/README.md (ga-core, marketplace Dr. Saulo, tutoria)

Divulgação (opcional, sem prazo)

• [ ] Tutorial em vídeo ou GIF curto

Status

ArkOS está publicado no npm como @arksys/arkos.

A versão atual é 0.1.3, com todos os modos operacionais (OBSERVE, PLAN, ACT, CLOSE), arkos doctor com Semantic Memory Validator, e cobertura de testes automatizados.