Estructura del Proyecto

Despues de instalar oh-my-agent, tu proyecto obtiene tres arboles de directorios: .agents/ (la fuente unica de verdad), .claude/ (capa de integracion con IDE) y .serena/ (estado en tiempo de ejecucion). Esta pagina documenta cada archivo y su proposito.

---

Árbol de Directorios Completo

your-project/
├── .agents/                          ← Single Source of Truth (SSOT)
│   ├── config/
│   │   └── oma-config.yaml    ← Language, timezone, CLI mapping
│   │
│   ├── skills/
│   │   ├── _shared/                  ← Resources used by ALL agents
│   │   │   ├── README.md
│   │   │   ├── core/
│   │   │   │   ├── skill-routing.md
│   │   │   │   ├── context-loading.md
│   │   │   │   ├── prompt-structure.md
│   │   │   │   ├── clarification-protocol.md
│   │   │   │   ├── context-budget.md
│   │   │   │   ├── difficulty-guide.md
│   │   │   │   ├── reasoning-templates.md
│   │   │   │   ├── quality-principles.md
│   │   │   │   ├── vendor-detection.md
│   │   │   │   ├── session-metrics.md
│   │   │   │   ├── common-checklist.md
│   │   │   │   ├── lessons-learned.md
│   │   │   │   └── api-contracts/
│   │   │   │       ├── README.md
│   │   │   │       └── template.md
│   │   │   ├── runtime/
│   │   │   │   ├── memory-protocol.md
│   │   │   │   └── execution-protocols/
│   │   │   │       ├── claude.md
│   │   │   │       ├── gemini.md
│   │   │   │       ├── codex.md
│   │   │   │       └── qwen.md
│   │   │   └── conditional/
│   │   │       ├── quality-score.md
│   │   │       ├── experiment-ledger.md
│   │   │       └── exploration-loop.md
│   │   │
│   │   ├── oma-frontend/
│   │   │   ├── SKILL.md
│   │   │   └── resources/
│   │   │       ├── execution-protocol.md
│   │   │       ├── tech-stack.md
│   │   │       ├── tailwind-rules.md
│   │   │       ├── component-template.tsx
│   │   │       ├── snippets.md
│   │   │       ├── error-playbook.md
│   │   │       ├── checklist.md
│   │   │       └── examples.md
│   │   │
│   │   ├── oma-backend/
│   │   │   ├── SKILL.md
│   │   │   ├── resources/
│   │   │   │   ├── execution-protocol.md
│   │   │   │   ├── examples.md
│   │   │   │   ├── orm-reference.md
│   │   │   │   ├── checklist.md
│   │   │   │   └── error-playbook.md
│   │   │   └── stack/                 ← Generated by /stack-set
│   │   │       ├── stack.yaml
│   │   │       ├── tech-stack.md
│   │   │       ├── snippets.md
│   │   │       └── api-template.*
│   │   │
│   │   ├── oma-mobile/
│   │   │   ├── SKILL.md
│   │   │   └── resources/
│   │   │       ├── execution-protocol.md
│   │   │       ├── tech-stack.md
│   │   │       ├── snippets.md
│   │   │       ├── screen-template.dart
│   │   │       ├── checklist.md
│   │   │       ├── error-playbook.md
│   │   │       └── examples.md
│   │   │
│   │   ├── oma-db/
│   │   │   ├── SKILL.md
│   │   │   └── resources/
│   │   │       ├── execution-protocol.md
│   │   │       ├── document-templates.md
│   │   │       ├── anti-patterns.md
│   │   │       ├── vector-db.md
│   │   │       ├── iso-controls.md
│   │   │       ├── checklist.md
│   │   │       ├── error-playbook.md
│   │   │       └── examples.md
│   │   │
│   │   ├── oma-design/
│   │   │   ├── SKILL.md
│   │   │   ├── resources/
│   │   │   │   ├── execution-protocol.md
│   │   │   │   ├── anti-patterns.md
│   │   │   │   ├── checklist.md
│   │   │   │   ├── design-md-spec.md
│   │   │   │   ├── design-tokens.md
│   │   │   │   ├── prompt-enhancement.md
│   │   │   │   ├── stitch-integration.md
│   │   │   │   └── error-playbook.md
│   │   │   ├── reference/
│   │   │   │   ├── typography.md
│   │   │   │   ├── color-and-contrast.md
│   │   │   │   ├── spatial-design.md
│   │   │   │   ├── motion-design.md
│   │   │   │   ├── responsive-design.md
│   │   │   │   ├── component-patterns.md
│   │   │   │   ├── accessibility.md
│   │   │   │   └── shader-and-3d.md
│   │   │   └── examples/
│   │   │       ├── design-context-example.md
│   │   │       └── landing-page-prompt.md
│   │   │
│   │   ├── oma-pm/
│   │   │   ├── SKILL.md
│   │   │   └── resources/
│   │   │       ├── execution-protocol.md
│   │   │       ├── examples.md
│   │   │       ├── iso-planning.md
│   │   │       ├── task-template.json
│   │   │       └── error-playbook.md
│   │   │
│   │   ├── oma-qa/
│   │   │   ├── SKILL.md
│   │   │   └── resources/
│   │   │       ├── execution-protocol.md
│   │   │       ├── iso-quality.md
│   │   │       ├── checklist.md
│   │   │       ├── self-check.md
│   │   │       ├── error-playbook.md
│   │   │       └── examples.md
│   │   │
│   │   ├── oma-debug/
│   │   │   ├── SKILL.md
│   │   │   └── resources/
│   │   │       ├── execution-protocol.md
│   │   │       ├── common-patterns.md
│   │   │       ├── debugging-checklist.md
│   │   │       ├── bug-report-template.md
│   │   │       ├── error-playbook.md
│   │   │       └── examples.md
│   │   │
│   │   ├── oma-tf-infra/
│   │   │   ├── SKILL.md
│   │   │   └── resources/
│   │   │       ├── execution-protocol.md
│   │   │       ├── multi-cloud-examples.md
│   │   │       ├── cost-optimization.md
│   │   │       ├── policy-testing-examples.md
│   │   │       ├── iso-42001-infra.md
│   │   │       ├── checklist.md
│   │   │       ├── error-playbook.md
│   │   │       └── examples.md
│   │   │
│   │   ├── oma-dev-workflow/
│   │   │   ├── SKILL.md
│   │   │   └── resources/
│   │   │       ├── validation-pipeline.md
│   │   │       ├── database-patterns.md
│   │   │       ├── api-workflows.md
│   │   │       ├── i18n-patterns.md
│   │   │       ├── release-coordination.md
│   │   │       └── troubleshooting.md
│   │   │
│   │   ├── oma-translator/
│   │   │   ├── SKILL.md
│   │   │   └── resources/
│   │   │       ├── translation-rubric.md
│   │   │       └── anti-ai-patterns.md
│   │   │
│   │   ├── oma-orchestrator/
│   │   │   ├── SKILL.md
│   │   │   ├── resources/
│   │   │   │   ├── subagent-prompt-template.md
│   │   │   │   └── memory-schema.md
│   │   │   ├── scripts/
│   │   │   │   ├── spawn-agent.sh
│   │   │   │   ├── parallel-run.sh
│   │   │   │   └── verify.sh
│   │   │   ├── templates/
│   │   │   └── config/
│   │   │       └── cli-config.yaml
│   │   │
│   │   ├── oma-brainstorm/
│   │   │   └── SKILL.md
│   │   │
│   │   ├── oma-coordination/
│   │   │   ├── SKILL.md
│   │   │   └── resources/
│   │   │       └── examples.md
│   │   │
│   │   └── oma-scm/
│   │       ├── SKILL.md
│   │       ├── config/
│   │       │   └── commit-config.yaml
│   │       └── resources/
│   │           └── conventional-commits.md
│   │
│   ├── workflows/
│   │   ├── orchestrate.md             ← Persistent: automated parallel execution
│   │   ├── work.md             ← Persistent: step-by-step coordination
│   │   ├── ultrawork.md              ← Persistent: 5-phase quality workflow
│   │   ├── plan.md                   ← PM task breakdown
│   │   ├── exec-plan.md              ← Execution plan management
│   │   ├── brainstorm.md             ← Design-first ideation
│   │   ├── deepinit.md               ← Project initialization
│   │   ├── review.md                 ← QA review pipeline
│   │   ├── debug.md                  ← Structured debugging
│   │   ├── design.md                 ← 7-phase design workflow
│   │   ├── scm.md                 ← Conventional commits
│   │   ├── tools.md                  ← MCP tool management
│   │   └── stack-set.md              ← Tech stack configuration
│   │
│   ├── agents/
│   │   ├── backend-engineer.md        ← Subagent def: backend
│   │   ├── frontend-engineer.md       ← Subagent def: frontend
│   │   ├── mobile-engineer.md         ← Subagent def: mobile
│   │   ├── db-engineer.md             ← Subagent def: database
│   │   ├── qa-reviewer.md             ← Subagent def: QA
│   │   ├── debug-investigator.md      ← Subagent def: debug
│   │   └── pm-planner.md             ← Subagent def: PM
│   │
│   ├── results/plan-{sessionId}.json                      ← Generated plan output (populated by /plan)
│   ├── state/                         ← Active workflow state files
│   │   ├── orchestrate-state.json     ← (exists only when workflow is active)
│   │   ├── ultrawork-state.json
│   │   └── work-state.json
│   ├── results/                       ← Agent result files
│   │   └── result-{agent}.md          ← (created by completed agents)
│   └── mcp.json                       ← MCP server configuration
│
├── .claude/                           ← IDE Integration Layer
│   ├── settings.json                  ← Hooks registration and permissions
│   ├── hooks/
│   │   ├── triggers.json              ← Keyword-to-workflow mapping (11 languages)
│   │   ├── keyword-detector.ts        ← Auto-detection logic
│   │   ├── persistent-mode.ts         ← Persistent workflow enforcement
│   │   └── hud.ts                     ← [OMA] statusline indicator
│   ├── skills/                        ← Symlinks → .agents/skills/
│   │   ├── oma-frontend -> ../../.agents/skills/oma-frontend
│   │   ├── oma-backend -> ../../.agents/skills/oma-backend
│   │   └── ...
│   └── agents/                        ← Subagent definitions for Claude Code
│       ├── backend-engineer.md
│       ├── frontend-engineer.md
│       └── ...
│
└── .serena/                           ← Runtime State (Serena MCP)
    └── memories/
        ├── orchestrator-session.md    ← Session ID, status, phase tracking
        ├── task-board.md              ← Task assignments and status
        ├── progress-{agent}.md        ← Per-agent progress updates
        ├── result-{agent}.md          ← Per-agent final outputs
        ├── session-metrics.md         ← Clarification Debt and Quality Score tracking
        ├── experiment-ledger.md       ← Experiment tracking (conditional)
        ├── session-work.md      ← Work workflow session state
        ├── session-ultrawork.md       ← Ultrawork workflow session state
        ├── tool-overrides.md          ← Temporary tool restrictions (/tools --temp)
        └── archive/
            └── metrics-{date}.md      ← Archived session metrics

---

.agents/ — La Fuente de Verdad

Este es el directorio principal. Todo lo que los agentes necesitan reside aqui. Es el unico directorio que importa para el comportamiento de los agentes — todos los demas directorios se derivan de el.

config/

oma-config.yaml — Archivo de configuracion central con:

• language: Codigo de idioma de respuesta (en, ko, ja, zh, es, fr, de, pt, ru, nl, pl)
• date_format: Cadena de formato de marca de tiempo (predeterminado: YYYY-MM-DD)
• timezone: Identificador de zona horaria (predeterminado: UTC)
• default_cli: Proveedor CLI de respaldo (gemini, claude, codex, qwen)
• model_preset (per-agent overrides via agents:): Sobrescrituras de enrutamiento CLI por agente

skills/

Donde reside la experiencia de los agentes. 22 directorios en total: 21 habilidades de agente + 1 directorio de recursos compartidos.

_shared/ — Recursos usados por todos los agentes:

• core/ — Enrutamiento, carga de contexto, estructura de prompt, protocolo de clarificacion, presupuesto de contexto, evaluacion de dificultad, plantillas de razonamiento, principios de calidad, deteccion de proveedor, metricas de sesion, lista de verificacion comun, lecciones aprendidas, plantillas de contratos API
• runtime/ — Protocolo de memoria para subagentes CLI, protocolos de ejecucion especificos del proveedor (claude, gemini, codex, qwen)
• conditional/ — Medicion de quality score, seguimiento de ledger de experimentos, protocolo de bucle de exploracion (cargado solo cuando se activa)

oma-{agent}/ — Directorios de habilidades por agente. Cada uno contiene:

• SKILL.md (~800 bytes) — Capa 1: siempre cargada. Identidad, enrutamiento, reglas principales.
• resources/ — Capa 2: bajo demanda. Protocolos de ejecucion, ejemplos, listas de verificacion, guias de errores, stacks tecnologicos, snippets, plantillas.
• Algunos agentes tienen subdirectorios adicionales: stack/ (oma-backend, generado por /stack-set), reference/ (oma-design), examples/ (oma-design), scripts/ (oma-orchestrator), config/ (oma-orchestrator, oma-scm).

workflows/

16 archivos Markdown que definen el comportamiento de los comandos slash. Cada archivo contiene:

• Frontmatter YAML con description
• Seccion de reglas obligatorias (idioma de respuesta, orden de pasos, requisitos de herramientas MCP)
• Instrucciones de deteccion de proveedor
• Protocolo de ejecucion paso a paso
• Definiciones de puertas (para flujos persistentes)

Flujos persistentes: orchestrate.md, work.md, ultrawork.md. No persistentes: plan.md, exec-plan.md, brainstorm.md, deepinit.md, review.md, debug.md, design.md, scm.md, tools.md, stack-set.md.

agents/

7 archivos de definicion de subagentes usados al generar agentes via la herramienta Task (Claude Code) o CLI. Cada archivo define:

• Frontmatter: name, description, skills (que habilidad cargar)
• Referencia del protocolo de ejecucion
• Plantilla de verificacion previa de charter (CHARTER_CHECK)
• Resumen de arquitectura
• Reglas especificas del dominio (10 reglas)
• Declaracion: "Nunca modificar archivos de .agents/"

plan-{sessionId}.json

Generado por el flujo /plan. Contiene el desglose estructurado de tareas con asignaciones de agentes, prioridades, dependencias y criterios de aceptacion. Consumido por /orchestrate, /work y /exec-plan.

state/

Archivos de estado de flujos activos para flujos persistentes. Estos archivos JSON existen solo mientras un flujo persistente esta en ejecucion. Eliminarlos (o decir "workflow done") desactiva el flujo.

results/

Archivos de resultados de agentes. Creados por agentes completados con estado (completado/fallido), resumen, archivos modificados y lista de criterios de aceptacion. Leidos por el orquestador durante la recopilacion y por los dashboards para monitoreo.

mcp.json

Configuracion del servidor MCP incluyendo:

• Definiciones de servidor (Serena, etc.)
• Configuracion de memoria: memoryConfig.provider, memoryConfig.basePath, memoryConfig.tools (nombres de herramientas read/write/edit)
• Definiciones de grupos de herramientas para gestion con /tools

---

.claude/ — Integracion con IDE

Este directorio conecta oh-my-agent con Claude Code y otros IDEs.

settings.json

Registra hooks y permisos para Claude Code. Contiene referencias a los scripts de hooks y sus condiciones de activacion (ej., UserPromptSubmit).

hooks/

triggers.json — El mapeo de palabras clave a flujos. Define:

• workflows: Mapa de nombre de flujo a { persistent: boolean, keywords: { language: [...] } }
• informationalPatterns: Frases que indican preguntas (filtradas de la auto-deteccion)
• excludedWorkflows: Flujos que requieren invocacion explicita con /command
• cjkScripts: Codigos de idioma que usan scripts CJK (ko, ja, zh)

keyword-detector.ts — Hook TypeScript que:

1. Escanea la entrada del usuario contra palabras clave de activacion
2. Verifica patrones informativos
3. Inyecta [OMA WORKFLOW: ...] o [OMA PERSISTENT MODE: ...] en el contexto

persistent-mode.ts — Verifica archivos de estado activos en .agents/state/ y refuerza la ejecucion de flujos persistentes.

hud.ts — Renderiza el indicador [OMA] en la barra de estado mostrando: nombre del modelo, uso de contexto (codificado por color: verde/amarillo/rojo) y estado del flujo activo.

skills/

Symlinks apuntando a .agents/skills/. Esto hace que las habilidades sean visibles para IDEs que leen de .claude/skills/ manteniendo .agents/ como la fuente unica de verdad.

agents/

Definiciones de subagentes formateadas para la herramienta Agent de Claude Code. Referencian los archivos de habilidades e incluyen la plantilla CHARTER_CHECK.

---

.serena/memories/ — Estado en Tiempo de Ejecucion

Donde los agentes escriben su progreso durante las sesiones de orquestacion. Este directorio es observado por los dashboards para actualizaciones en tiempo real.

Archivo	Propietario	Proposito
orchestrator-session.md	Orquestador	Metadatos de sesion: ID, estado, hora de inicio, fase actual
task-board.md	Orquestador	Asignaciones de tareas: agente, tarea, prioridad, estado, dependencias
progress-{agent}.md	Ese agente	Actualizaciones turno a turno: acciones realizadas, archivos leidos/modificados, estado actual
result-{agent}.md	Ese agente	Salida final: estado de completacion, resumen, archivos modificados, criterios de aceptacion
session-metrics.md	Orquestador	Eventos de Deuda de Clarificacion, progresion de Quality Score
experiment-ledger.md	Orquestador/QA	Filas de experimentos cuando Quality Score esta activo
session-work.md	Flujo work	Estado de sesion especifico de work
session-ultrawork.md	Flujo ultrawork	Seguimiento de fases especifico de ultrawork
tool-overrides.md	Flujo /tools	Restricciones temporales de herramientas (alcance de sesion)
archive/metrics-{date}.md	Sistema	Metricas de sesion archivadas (retencion de 30 dias)

Las rutas de archivos de memoria y nombres de herramientas son configurables en .agents/mcp.json via memoryConfig.

---

Estructura del Repositorio Fuente de oh-my-agent

Si estas trabajando en oh-my-agent mismo (no solo usandolo), el repositorio es un monorepo:

oh-my-agent/
├── cli/                  ← CLI tool source (TypeScript, built with bun)
│   ├── src/              ← Source code
│   ├── package.json
│   └── install.sh        ← Bootstrap installer
├── web/                  ← Documentation site (Next.js)
│   └── content/
│       └── en/           ← English documentation pages
├── action/               ← GitHub Action for automated skill updates
├── docs/                 ← Translated READMEs and specifications
├── .agents/              ← EDITABLE in source repo (this IS the source)
├── .claude/              ← IDE integration
├── .serena/              ← Development runtime state
├── CLAUDE.md             ← Project instructions for Claude Code
└── package.json          ← Root workspace config

En el repositorio fuente, las modificaciones a .agents/ estan permitidas (esta es la excepcion SSOT para el repositorio fuente mismo). Las reglas de .agents/ sobre no modificar este directorio aplican a proyectos consumidores, no al repositorio de oh-my-agent.

Comandos de desarrollo:

• bun run test — Pruebas CLI (vitest)
• bun run lint — Lint
• bun run build — Build del CLI
• Los commits deben seguir el formato de conventional commits (commitlint aplicado)