otherness — Contexto do Agente de Projeto

O Que Isto É

otherness é um sistema autônomo de desenvolvimento de software. Uma única sessão desempenha os papéis de coordenador, engenheiro, QA adversário, scrum master e gerente de produto — sequencialmente, em um loop, sem entrada humana. Ele opera em qualquer projeto hospedado no GitHub, lendo AGENTS.md, docs/aide/ e .otherness/state.json, e gera filas de trabalho, implementa funcionalidades, revisa PRs e lança versões de forma autônoma.

otherness está rodando em si mesmo. Quando este agente melhora o otherness, essas melhorias são implantadas em todos os projetos que usam otherness na sua próxima execução, através do mecanismo de auto-atualização (git -C ~/.otherness pull).

Status: Ativo. Loop principal estável. Modo de auto-melhoria habilitado.

⚠️ AVISO DE IMPLANTAÇÃO GLOBAL — LEIA ANTES DE CADA MERGE Alterações em agents/standalone.md ou agents/bounded-standalone.md são implantadas imediatamente em todos os projetos que usam otherness mundialmente na inicialização da próxima sessão. Esses arquivos são a superfície de mudança de maior risco. Consulte §Níveis de Risco de Mudança abaixo.

Processo SDLC

O processo da equipe está embutido em ~/.otherness/agents/standalone.md. Este arquivo contém apenas o contexto específico do projeto.

Configuração do Projeto

PROJECT_NAME:   otherness
CLI_BINARY:     ""
PR_LABEL:       otherness
REPORT_ISSUE:   741
REPORT_URL:     https://github.com/pnz1990/otherness/issues/741
BOARD_URL:      ""
BUILD_COMMAND:  bash scripts/validate.sh
TEST_COMMAND:   bash scripts/test.sh
LINT_COMMAND:   bash scripts/lint.sh
VULN_COMMAND:   ""

Arquitetura

otherness é uma coleção de arquivos de instrução markdown lidos pelo OpenCode (o runtime do agente de codificação de IA). Não há binário compilado, servidor ou banco de dados. O "produto" é a qualidade do loop do agente autônomo que essas instruções produzem.

Modelo de implantação: ~/.otherness/agents/ é um repositório git. Cada agente se auto-atualiza via git -C ~/.otherness pull na inicialização. Um PR mesclado em pnz1990/otherness:main é implantado para todos os usuários na sua próxima execução.

Dependências de runtime: OpenCode (executa os agentes), CLI gh (toda interação com GitHub), git (VCS + isolamento de worktree + auto-atualização), stdlib python3 (análise YAML, estado JSON).

Estado: .otherness/state.json em uma branch _state dedicada. Nunca em main. Sessões paralelas usam push de branch como um bloqueio distribuído.

Habilidades: agents/skills/*.md — listas de verificação reutilizáveis carregadas pelas fases de engenharia e QA. Crescidas por /otherness.learn.

Layout do Pacote

~/.otherness/              ← raiz do repositório (clone git neste caminho)
  agents/
    standalone.md          ← orquestrador thin: gerenciamento de estado, inicialização, esqueleto do loop, regras rígidas
    bounded-standalone.md  ← agente com escopo — 50 linhas encapsulando standalone.md
    onboard.md             ← onboarding de projeto existente
    otherness.learn.md     ← agente de aprendizado — internalizar de código aberto
    otherness.arch-audit.md← agente de auditoria arquitetural
    gh-features.md         ← referência da API do GitHub
    phases/                ← implementações de fase (carregadas por standalone.md)
      coord.md             ← Fase 1: heartbeat, rate-limit, bloqueio de geração de fila, watchdog de stale, claim
      eng.md               ← Fase 2: espec/planejamento/tarefas (integração speckit), implementar, memória
      qa.md                ← Fase 3: revisão adversarial, conformidade com espec, merge, arquivar
      sm.md                ← Fase 4: triagem, recuperação de stale, métricas, aprendizado entre projetos
      pm.md                ← Fase 5: validação de produto, saúde do roadmap, verificação competitiva
    skills/                ← arquivos de habilidade reutilizáveis
      declaring-designs.md           ← padrão de qualidade de espec
      reconciling-implementations.md ← lista de verificação de QA
      agent-coding-discipline.md     ← mudanças cirúrgicas, objetivos verificáveis
      autonomous-workflow-patterns.md← padrões de design de workflow
      architectural-audit.md         ← metodologia de auditoria de quatro lentes
      contribution-hygiene.md        ← disciplina de PR e commit
      agent-responsibility.md        ← padrões de julgamento e responsabilidade
      role-based-agent-identity.md   ← padrões de identidade de papel
      ephemeral-pr-artifacts.md      ← padrões operacionais de PR
      explicit-anti-patterns.md      ← documentação de anti-padrões
      triage-discipline.md           ← processo de triagem de SM
      PROVENANCE.md                  ← trilha de auditoria de sessão de aprendizado
      README.md                      ← índice de habilidades
  boundaries/
    README.md
    example.boundary
  docs/
    aide/
      vision.md
      roadmap.md
      definition-of-done.md
      progress.md
  .otherness/
    state.json            ← apenas na branch _state
  .opencode/
    command/
      otherness.run.md
      otherness.run.bounded.md
      otherness.setup.md
      otherness.status.md
      otherness.upgrade.md
      otherness.learn.md
      otherness.arch-audit.md
      otherness.cross-agent-monitor.md
  otherness-config.yaml
  otherness-config-template.yaml
  AGENTS.md
  README.md
  onboarding-new-project.md
  onboarding-existing-project.md
  scripts/
    validate.sh            ← alvo BUILD_COMMAND
    test.sh                ← alvo TEST_COMMAND
    lint.sh                ← alvo LINT_COMMAND

Níveis de Risco de Mudança

Esta é a seção mais importante. Cada PR deve ser classificado antes do merge.

Nível	Arquivos	Risco	Portão de Merge
CRÍTICO	`agents/standalone.md`, `agents/bounded-standalone.md`, `agents/phases/*.md`	Implanta em TODOS os projetos imediatamente. Uma instrução quebrada pode travar a próxima sessão de cada usuário do otherness.	[PRECISA DE HUMANO] revisão necessária antes do merge. Nenhum merge autônomo.
ALTO	`agents/onboard.md`, `agents/otherness.learn.md`, `otherness-config-template.yaml`, `onboarding-*.md`	Afeta a configuração de novos projetos ou o loop de aprendizado.	QA deve verificar contra o projeto de referência. Merge autônomo permitido se os testes passarem.
MÉDIO	`agents/skills/*.md`, `agents/gh-features.md`, `boundaries/`	Conhecimento aditivo. Regressões têm baixo impacto.	Ciclo de QA padrão. Merge autônomo.
BAIXO	`docs/`, `README.md`, `AGENTS.md`, `scripts/`	Documentação e scaffolding. Nenhum impacto em runtime.	Merge autônomo.

Regra do nível CRÍTICO: Qualquer PR que toque em agents/standalone.md, agents/bounded-standalone.md ou agents/phases/*.md deve publicar [PRECISA DE HUMANO: mudança-nível-crítico] no PR e NÃO ser mesclado autonomamente. Deixe para revisão humana.

O Que "Testes" Significam para otherness

otherness não tem testes unitários. Sua correção só pode ser validada executando-o em um projeto real e observando o comportamento.

scripts/validate.sh (BUILD_COMMAND) realiza estas verificações estruturais:

Nenhum caminho de projeto codificado — arquivos de agente, fase e habilidade não devem referenciar projetos específicos em contexto de instrução executável. PROVENANCE.md e metadados de proveniência em comentários HTML estão isentos.
Referências de habilidade resolvem — toda referência Carregar habilidade: ler ... em standalone.md e agents/phases/*.md aponta para um arquivo existente em disco ou no repositório.
Arquivos necessários presentes — todos os arquivos de agente, fase, habilidade, docs e comando listados no conjunto necessário existem.
Auto-atualização presente — standalone.md contém o bloco de auto-atualização git -C ~/.otherness pull.

scripts/test.sh (TEST_COMMAND) executa todas as 4 verificações de validação mais:

Teste de integração — verificar se o otherness está rodando corretamente no projeto de referência (primeira entrada não-otherness em monitor.projects em otherness-config.yaml) verificando que a branch _state mostra atividade nas últimas 72 horas.

scripts/lint.sh (LINT_COMMAND) verifica a correção estrutural dos arquivos de agente usando python3 (nenhuma ferramenta externa necessária): finais de linha CRLF, bytes nulos, cabeçalhos de fase necessários em standalone.md.

O Loop de Auto-Melhoria

Quando otherness roda em si mesmo, as áreas de melhoria são:

Qualidade do loop do agente — o agente autônomo toma melhores decisões? Medida: menos escalações [PRECISA DE HUMANO] por lote em projetos de referência, menor tempo para merge por item.
Profundidade das habilidades — os arquivos de habilidades estão crescendo a partir de sessões /otherness.learn? Medida: entradas PROVENANCE.md, contagem de arquivos de habilidade.
Atrito de onboarding — /otherness.onboard produz arquivos docs/aide/ completos e precisos? Medida: quantas edições manuais são necessárias após o onboarding.
Precisão da documentação — README.md corresponde ao comportamento real? Medida: jornada de validação do PM passa.
Ferramentas — scripts/validate.sh, scripts/test.sh, scripts/lint.sh capturam regressões reais? Medida: esses scripts melhoram com o tempo.

A fase de PM deve comparar o otherness com a comunidade de onde veio (Hermes, Multica, Archon) a cada lote, e identificar lacunas que valem a pena fechar.

Anti-Padrões (QA bloqueia PRs contendo estes)

Padrão	Capturado por
Mesclar PR de nível CRÍTICO sem rótulo `[PRECISA DE HUMANO]`	QA — bloqueio rígido
Codificar caminhos específicos de projeto em `standalone.md` (por exemplo, nomes de projeto fleet, slugs owner/repo)	QA
Instrução de agente que bloqueia em arquivo opcional ausente sem fallback gracioso	QA
Arquivo de habilidade que referencia ferramentas não disponíveis em todas as sessões do OpenCode	QA
Remover ou enfraquecer o `git pull` de auto-atualização na inicialização	QA — bloqueio rígido
Alterar o padrão de escrita da branch `_state` sem verificar a segurança de sessão paralela	QA — bloqueio rígido
Tarefa `[x]` sem implementação	QA

Taxonomia de Rótulos

Grupo	Rótulos
Tipo	`kind/enhancement`, `kind/bug`, `kind/chore`, `kind/docs`
Área	`area/agent-loop`, `area/skills`, `area/onboarding`, `area/tooling`, `area/docs`
Prioridade	`priority/critical`, `priority/high`, `priority/medium`, `priority/low`
Tamanho	`size/xs`, `size/s`, `size/m`, `size/l`, `size/xl`
Risco	`risk/critical`, `risk/high`, `risk/medium`, `risk/low`
Tipo	`epic`
Fluxo de trabalho	`otherness`, `needs-human`, `blocked`

Cenários de Validação de Produto (Fase PM)

O agente PM valida o otherness observando-o em projetos de referência. O projeto de referência é a primeira entrada não-otherness em otherness-config.yaml sob monitor.projects. Comandos abaixo usam $REFERENCE_PROJECT como um espaço reservado — substitua pelo slug real do seu projeto (por exemplo, owner/my-project).

Cenário 1: projeto de referência está vivo

REFERENCE_PROJECT=$(python3 -c "
import re
in_monitor=in_projects=False
for line in open('otherness-config.yaml'):
    if re.match(r'^monitor:',line): in_monitor=True
    if in_monitor and re.match(r'\s+projects:',line): in_projects=True
    if in_projects:
        m=re.match(r'\s+- (.+)',line)
        if m:
            r=m.group(1).strip()
            if not r.endswith('/otherness'): print(r); break
")
gh api "repos/$REFERENCE_PROJECT/branches/_state" \
  --jq '.commit.commit.committer.date'
# Deve estar dentro de 72 horas. Se mais antigo: otherness parou no projeto de referência.

Passa: _state mostra commits dentro de 72 horas.

Cenário 2: projeto de referência tem PRs abertos ou merges recentes

gh pr list --repo $REFERENCE_PROJECT --json number,title,state,createdAt \
  --jq '.[] | "\(.state) \(.createdAt) \(.title)"' | head -5

Passa: pelo menos um PR aberto ou mesclado nos últimos 7 dias.

Cenário 3: habilidades estão crescendo

ls ~/.otherness/agents/skills/ | wc -l
# Deve ser ≥ 4 (os 4 com que começamos). Crescer significa que /otherness.learn rodou.
tail -20 ~/.otherness/agents/skills/PROVENANCE.md

Passa: PROVENANCE.md tem pelo menos uma entrada datada nos últimos 30 dias.

Cenário 4: README corresponde ao comportamento real

Leia README.md e faça referência cruzada com agents/standalone.md. Verifique: todo comando listado no README existe em .opencode/command/. Verifique: todo arquivo de agente listado no diagrama de pilha existe em disco. Abra um issue kind/docs para cada discrepância encontrada.

Cenário 5: auto-melhoria está acontecendo

OTHERNESS_REPO=$(python3 -c "
import re
for line in open('otherness-config.yaml'):
    m=re.match(r'^\s+repo:\s*(.+)',line)
    if m: print(m.group(1).strip()); break
")
gh pr list --repo $OTHERNESS_REPO --state merged \
  --json mergedAt,title --jq '.[] | "\(.mergedAt) \(.title)"' | head -10

Passa: pelo menos um PR mesclado nos últimos 14 dias. Se zero: otherness não se melhorou recentemente. Investigue por que e abra um issue.

Arquivos que os Agentes Não Devem Modificar

AGENTS.md (este arquivo)
docs/aide/vision.md
docs/aide/roadmap.md
otherness-config-template.yaml (nível de risco de mudança ALTO — apenas QA, não autônomo)

Risco Futuro: Modelo de Implantação Global

Documento para consideração futura (Opção B):

Atualmente, qualquer PR mesclado na branch main do otherness é implantado imediatamente em todos os projetos que usam otherness via git -C ~/.otherness pull. Esta é a Opção A — rápida, simples, sem sobrecarga de versionamento.

O risco: um bug em agents/standalone.md quebra todas as sessões do otherness em todos os lugares simultaneamente. Atualmente mitigado por: nível CRÍTICO exigindo revisão humana, teste de integração no projeto de referência, e o fato de que o loop do agente é resiliente (uma instrução ruim causa um [PRECISA DE HUMANO] em vez de uma falha).

Quando atualizar para a Opção B (lançamentos versionados):

Quando otherness for usado por >10 repositórios distintos
Quando uma regressão de nível CRÍTICO tiver causado danos reais a um projeto não-teste
Quando os usuários precisarem de garantias de estabilidade entre sessões

Design da Opção B: tags git como lançamentos, projetos fixam uma tag em otherness-config.yaml, /otherness.upgrade aumenta o pino com uma etapa de revisão de changelog. A auto-atualização git pull se torna git checkout <tag-fixada>.

pnz1990/otherness

O que é otherness?

Perguntar na sua IA favorita

Documentação