Structure du Projet

Après l'installation d'oh-my-agent, votre projet acquiert trois arborescences de répertoires : .agents/ (la source unique de vérité), .claude/ (couche d'intégration IDE) et .serena/ (état d'exécution). Cette page documente chaque fichier et son rôle.

---

Arborescence complète

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 source de vérité

C'est le répertoire central. Tout ce dont les agents ont besoin s'y trouve. C'est le seul répertoire qui compte pour le comportement des agents -- tous les autres répertoires en sont dérivés.

config/

oma-config.yaml — Central configuration file with:

• language: Response language code (en, ko, ja, zh, es, fr, de, pt, ru, nl, pl)
• date_format: Timestamp format string (default: YYYY-MM-DD)
• timezone: Timezone identifier (default: UTC)
• default_cli: Fallback CLI vendor (gemini, claude, codex, qwen)
• model_preset (per-agent overrides via agents:): Per-agent CLI routing overrides

skills/

Where agent expertise lives. 22 directories total: 21 agent skills + 1 shared resource directory.

_shared/ — Resources used by all agents:

• core/ — Routing, context loading, prompt structure, clarification protocol, context budget, difficulty assessment, reasoning templates, quality principles, vendor detection, session metrics, common checklist, lessons learned, API contract templates
• runtime/ — Memory protocol for CLI subagents, vendor-specific execution protocols (claude, gemini, codex, qwen)
• conditional/ — Quality score measurement, experiment ledger tracking, exploration loop protocol (loaded only when triggered)

oma-{agent}/ — Per-agent skill directories. Each contains:

• SKILL.md (~800 bytes) — Layer 1: always loaded. Identity, routing, core rules.
• resources/ — Layer 2: on-demand. Execution protocols, examples, checklists, error playbooks, tech stacks, snippets, templates.
• Some agents have additional subdirectories: stack/ (oma-backend, generated by /stack-set), reference/ (oma-design), examples/ (oma-design), scripts/ (oma-orchestrator), config/ (oma-orchestrator, oma-scm).

workflows/

16 Markdown files defining slash command behavior. Each file contains:

• YAML frontmatter with description
• Mandatory rules section (response language, step ordering, MCP tool requirements)
• Vendor detection instructions
• Step-by-step execution protocol
• Gate definitions (for persistent workflows)

Persistent workflows: orchestrate.md, work.md, ultrawork.md. Non-persistent: plan.md, exec-plan.md, brainstorm.md, deepinit.md, review.md, debug.md, design.md, scm.md, tools.md, stack-set.md.

agents/

7 subagent definition files used when spawning agents via the Task tool (Claude Code) or CLI. Each file defines:

• Frontmatter: name, description, skills (which skill to load)
• Execution protocol reference
• Charter preflight (CHARTER_CHECK) template
• Architecture summary
• Domain-specific rules (10 rules)
• Statement: "Never modify .agents/ files"

plan-{sessionId}.json

Generated by the /plan workflow. Contains the structured task breakdown with agent assignments, priorities, dependencies, and acceptance criteria. Consumed by /orchestrate, /work, and /exec-plan.

state/

Active workflow state files for persistent workflows. These JSON files exist only while a persistent workflow is running. Deleting them (or saying "workflow done") deactivates the workflow.

results/

Agent result files. Created by completed agents with status (completed/failed), summary, files changed, and acceptance criteria checklist. Read by the orchestrator during collection and by dashboards for monitoring.

mcp.json

MCP server configuration including:

• Server definitions (Serena, etc.)
• Memory configuration: memoryConfig.provider, memoryConfig.basePath, memoryConfig.tools (read/write/edit tool names)
• Tool group definitions for /tools management

---

.claude/ -- Intégration IDE

Ce répertoire connecte oh-my-agent à Claude Code et aux autres IDE.

settings.json

Registers hooks and permissions for Claude Code. Contains references to the hook scripts and their trigger conditions (e.g., UserPromptSubmit).

hooks/

triggers.json — The keyword-to-workflow mapping. Defines:

• workflows: Map of workflow name to { persistent: boolean, keywords: { language: [...] } }
• informationalPatterns: Phrases that indicate questions (filtered out from auto-detection)
• excludedWorkflows: Workflows that require explicit /command invocation
• cjkScripts: Language codes using CJK scripts (ko, ja, zh)

keyword-detector.ts — TypeScript hook that:

1. Scans user input against trigger keywords
2. Checks for informational patterns
3. Injects [OMA WORKFLOW: ...] or [OMA PERSISTENT MODE: ...] into context

persistent-mode.ts — Checks for active state files in .agents/state/ and reinforces persistent workflow execution.

hud.ts — Renders the [OMA] indicator in the status bar showing: model name, context usage (color-coded: green/yellow/red), and active workflow state.

skills/

Symlinks pointing to .agents/skills/. This makes skills visible to IDEs that read from .claude/skills/ while keeping .agents/ as the single source of truth.

agents/

Subagent definitions formatted for Claude Code's Agent tool. These reference the skill files and include the CHARTER_CHECK template.

---

.serena/memories/ -- État d'exécution

L'endroit où les agents écrivent leur progression pendant les sessions d'orchestration. Ce répertoire est surveillé par les tableaux de bord pour les mises à jour en temps réel.

File	Owner	Purpose
orchestrator-session.md	Orchestrator	Session metadata: ID, status, start time, current phase
task-board.md	Orchestrator	Task assignments: agent, task, priority, status, dependencies
progress-{agent}.md	That agent	Turn-by-turn updates: actions taken, files read/modified, current status
result-{agent}.md	That agent	Final output: completion status, summary, files changed, acceptance criteria
session-metrics.md	Orchestrator	Clarification Debt events, Quality Score progression
experiment-ledger.md	Orchestrator/QA	Experiment rows when Quality Score is active
session-work.md	Work workflow	Work-specific session state
session-ultrawork.md	Ultrawork workflow	Ultrawork-specific phase tracking
tool-overrides.md	/tools workflow	Temporary tool restrictions (session-scoped)
archive/metrics-{date}.md	System	Archived session metrics (30-day retention)

Memory file paths and tool names are configurable in .agents/mcp.json via memoryConfig.

---

Structure du dépôt source oh-my-agent

Si vous travaillez sur oh-my-agent lui-même (et pas seulement en tant qu'utilisateur), le dépôt est 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

Dans le dépôt source, les modifications de .agents/ sont autorisées (c'est l'exception SSOT pour le dépôt source lui-même). Les règles de .agents/ interdisant la modification de ce répertoire s'appliquent aux projets consommateurs, pas au dépôt oh-my-agent.

Commandes de développement :

• bun run test — CLI tests (vitest)
• bun run lint — Lint
• bun run build — CLI build
• Commits must follow conventional commit format (commitlint enforced)