Funcionalidade de Status do Projeto - Guia do Usuário

🌐 EN | PT | ES

Funcionalidade: Contexto Dinâmico de Status do Projeto para Ativação de Agentes Versão: 1.0 Story: 6.1.2.4 Criado: 2025-01-14

Visão Geral

A funcionalidade de Status do Projeto exibe automaticamente seu contexto de trabalho atual quando qualquer agente AIOS é ativado. Isso inclui:

Branch do Git em que você está atualmente
Arquivos modificados no seu diretório de trabalho
Commits recentes (últimos 2)
Story/Epic atual (se alguma story estiver InProgress)

Isso fornece contexto imediato sobre seu trabalho sem precisar executar manualmente git status ou procurar por stories ativas.

Exemplo de Exibição

Quando você ativa um agente (ex: /dev), você verá:


Dex (Builder) ready. Let's build something great!

Current Project Status:
  - Branch: main
  - Modified: story-6.1.2.4.md, po.md
  - Recent: chore: cleanup Utils Registry, Phase 4: Open-Source Preparation

Type *help to see available commands!

Configuração

Pré-requisitos

Repositório Git - Projeto deve ser inicializado com git init
Framework AIOS-FullStack instalado
Node.js 18+ com pacotes necessários

Configuração Inicial

Execute o comando de inicialização via agente @devops:


/devops
*init-project-status

Isso irá:

Detectar seu repositório git
Habilitar projectStatus no core-config.yaml
Criar arquivo de cache .aios/project-status.yaml
Adicionar arquivo de cache ao .gitignore
Testar a exibição do status

Configuração Manual Alternativa:

Se você preferir configuração manual:

Edite .aios-core/core-config.yaml:


projectStatus:
  enabled: true
  autoLoadOnAgentActivation: true
  showInGreeting: true
  cacheTimeSeconds: 60

Crie o diretório .aios/:
```
mkdir .aios
```
Adicione ao .gitignore:
```
.aios/project-status.yaml
```

Configuração

Opções Completas de Configuração

Localização: .aios-core/core-config.yaml


projectStatus:
  enabled: true                      # Habilitar/desabilitar funcionalidade
  autoLoadOnAgentActivation: true    # Carregar na ativação do agente
  showInGreeting: true               # Exibir no greeting
  cacheTimeSeconds: 60               # TTL do cache (segundos)
  components:                        # Alternar componentes individuais
    gitBranch: true                  # Mostrar nome da branch
    gitStatus: true                  # Mostrar arquivos modificados
    recentWork: true                 # Mostrar commits recentes
    currentEpic: true                # Mostrar epic atual
    currentStory: true               # Mostrar story atual
  statusFile: .aios/project-status.yaml  # Localização do arquivo de cache
  maxModifiedFiles: 5                # Limitar arquivos modificados exibidos
  maxRecentCommits: 2                # Limitar commits exibidos

Exemplos de Personalização

Mostrar apenas branch e story:


projectStatus:
  enabled: true
  components:
    gitBranch: true
    gitStatus: false      # Ocultar arquivos modificados
    recentWork: false     # Ocultar commits
    currentEpic: false
    currentStory: true

Aumentar TTL do cache para 5 minutos:


projectStatus:
  cacheTimeSeconds: 300

Mostrar mais commits e arquivos:


projectStatus:
  maxModifiedFiles: 10
  maxRecentCommits: 5

Como Funciona

Coleta de Status

Quando um agente é ativado, o sistema:

Verifica cache - Procura por .aios/project-status.yaml
Valida TTL - O cache tem menos de 60 segundos?
Retorna em cache - Se válido, usa status em cache (rápido)
Gera novo - Se expirado, executa comandos git e escaneia stories
Atualiza cache - Salva novo status para próxima ativação

Comandos Git Utilizados


# Check if git repo
git rev-parse --is-inside-work-tree
 
# Get branch (modern git >= 2.22)
git branch --show-current
 
# Get branch (fallback for older git)
git rev-parse --abbrev-ref HEAD
 
# Get modified files
git status --porcelain
 
# Get recent commits
git log -2 --oneline --no-decorate

Detecção de Story

Escaneia docs/stories/ por arquivos contendo:


**Status:** InProgress
**Story ID:** STORY-X.Y.Z
**Epic:** Epic X.Y - Name

Mostra apenas stories com status: InProgress ou In Progress.

Performance

Benchmarks

Operação	Tempo	Notas
Primeira Carga	80-100ms	Executa comandos git + scan de arquivos
Carga em Cache	5-10ms	Lê YAML do cache
Cache Miss	80-100ms	TTL expirado, regenera
Overhead do Agente	<100ms	Adicionado ao tempo de ativação

Estratégia de Cache

TTL do Cache: 60 segundos (configurável)
Localização do Cache: .aios/project-status.yaml
Formato do Cache: YAML com objeto de status + timestamp
Invalidação: Automática após TTL expirar

Por que 60 segundos?

Longo o suficiente para evitar chamadas git repetidas durante troca de agentes
Curto o suficiente para refletir mudanças recentes
Equilíbrio ótimo entre performance e atualidade

Agentes Afetados

Todos os 11 agentes AIOS exibem status do projeto:

@dev (Dex - Builder)
@po (Pax - Balancer)
@qa (Quinn - Guardian)
@sm (River - Facilitator)
@pm (Morgan - Strategist)
@architect (Aria - Visionary)
@analyst (Atlas - Decoder)
@devops (Gage - Operator)
@data-engineer (Dara - Sage)
@ux-design-expert (Uma - Empathizer)
@aios-master (Orion - Orchestrator)

Solução de Problemas

Status Não Aparece

Sintoma: Agente ativa sem exibição de status

Verificar:

O projectStatus.enabled: true está no core-config.yaml?
Este é um repositório git? (git rev-parse --is-inside-work-tree)
O arquivo .aios-core/infrastructure/scripts/project-status-loader.js existe?
Há erros na saída de ativação do agente?

Solução:


# Re-run initialization
/devops
*init-project-status

Dados de Status Desatualizados

Sintoma: Status mostra dados antigos

Causa: Cache não está invalidando corretamente

Solução:


# Manually clear cache
rm .aios/project-status.yaml
 
# Or restart agent session

Comandos Git Falhando

Sintoma: Branch mostra “unknown”, arquivos faltando

Verificar:

O git está no PATH? (git --version)
A versão do git é >= 2.0? (2.22+ recomendado)
Repositório corrompido? (git fsck)

Fallback: O sistema usa comandos git mais antigos automaticamente se comandos modernos falharem.

Problemas de Performance

Sintoma: Ativação do agente > 200ms consistentemente

Causa: Repositório grande ou I/O de disco lento

Solução:


# Reduce data collected
projectStatus:
  maxModifiedFiles: 3    # Default: 5
  maxRecentCommits: 1     # Default: 2
  components:
    recentWork: false     # Disable commits

Projetos Sem Git

Comportamento Esperado:


Current Project Status:
  (Not a git repository)

Isso é normal e inofensivo. Agentes funcionam normalmente sem git.

Uso Avançado

Desabilitar para Agentes Específicos

Atualmente, o status é exibido em todos os agentes. Para desabilitar globalmente:


projectStatus:
  enabled: false

Nota: Desabilitar por agente ainda não implementado (veja Melhorias Futuras).

Localização Personalizada do Arquivo de Status


projectStatus:
  statusFile: .custom/my-status.yaml

Não esqueça de atualizar o .gitignore.

Acesso Programático


const { loadProjectStatus, formatStatusDisplay } = require('./.aios-core/infrastructure/scripts/project-status-loader.js');
 
// Get raw status object
const status = await loadProjectStatus();
console.log(status);
 
// Get formatted display string
const display = formatStatusDisplay(status);
console.log(display);
 
// Clear cache manually
const { clearCache } = require('./.aios-core/infrastructure/scripts/project-status-loader.js');
await clearCache();

Rollback

Desabilitar Funcionalidade

Editar config:
```
projectStatus:
  enabled: false
```
Limpar cache:
```
rm .aios/project-status.yaml
```
Reiniciar agentes - Novas ativações não mostrarão status

Remoção Completa

Para remover completamente a funcionalidade:


# Remove script
rm .aios-core/infrastructure/scripts/project-status-loader.js
 
# Remove task
rm .aios-core/tasks/init-project-status.md
 
# Remove cache
rm .aios/project-status.yaml
 
# Remove tests
rm .aios-core/infrastructure/scripts/__tests__/project-status-loader.test.js
 
# Remove config section from core-config.yaml
# (manually edit file)
 
# Revert agent files to pre-6.1.2.4 state
git revert <commit-hash>

Compatibilidade de Versão do Git

Recomendado: git >= 2.22

Usa comando moderno:


git branch --show-current

Suportado: git >= 2.0

Fallback para:


git rev-parse --abbrev-ref HEAD

Mínimo: git 2.0+

Versões mais antigas podem funcionar mas não são testadas.

Verifique sua versão:


git --version

Melhorias Futuras

Melhorias potenciais (ainda não implementadas):

Toggle de status por agente (ex: desabilitar apenas para @qa)
Indicadores de status coloridos (verde limpo, amarelo modificado, vermelho conflitos)
Porcentagem de progresso da story (tarefas completadas / total)
Tempo estimado para completar story atual
Detecção de múltiplas stories (mostrar todas InProgress)
Componentes de status personalizados via plugins
Observação de arquivos em tempo real (remover delay do cache)

FAQ

P: Isso vai deixar a ativação do agente mais lenta? R: A carga inicial adiciona ~100ms. Cargas em cache adicionam ~10ms. Isso é mínimo e vale o benefício do contexto.

P: Posso desabilitar para agentes específicos? R: Ainda não. Você pode desabilitar globalmente via projectStatus.enabled: false.

P: E se eu não estiver usando git? R: O status mostra “(Not a git repository)” e os agentes funcionam normalmente.

P: Com que frequência o status é atualizado? R: A cada 60 segundos por padrão (configurável via cacheTimeSeconds).

P: Isso funciona no Windows/Linux/macOS? R: Sim, testado em todas as plataformas.

P: Posso personalizar o formato do status? R: Ainda não. O formato é fixo em project-status-loader.js:formatStatusDisplay().

P: O cache é compartilhado entre agentes? R: Sim, todos os agentes usam o mesmo arquivo de cache (.aios/project-status.yaml).

Documentação Relacionada

Story: docs/stories/aios migration/story-6.1.2.4-project-status-context.md
Config: .aios-core/core-config.yaml (seção projectStatus)
Script: .aios-core/infrastructure/scripts/project-status-loader.js
Task de Init: .aios-core/tasks/init-project-status.md
Testes: .aios-core/infrastructure/scripts/__tests__/project-status-loader.test.js

Versão: 1.0 Status: Pronto para Produção Última Atualização: 2025-01-14