oh-my-codex-cli 0.2.1 → 0.2.2

package/AGENTS.md

@@ -1,10 +1,10 @@
-<!-- Generated: 2026-01-31 | Updated: 2026-01-31 -->
+<!-- Generated: 2026-01-31 | Updated: 2026-02-25 -->
 
 # oh-my-codex
 
 Skill pack and workflow orchestration for **OpenAI Codex CLI**.
 
-**Version:** 0.1.0
+**Version:** 0.2.0
 **Purpose:** Make Codex behave like a multi-agent conductor using structured skills
 
 ## Purpose
@@ -20,25 +20,47 @@ oh-my-codex enhances Codex with:
 |------|-------------|
 | `README.md` | Entry point documentation |
 | `docs/CODEX.md` | Codex-specific install and usage guide |
-| `.agent/skills/` | All Codex skill definitions |
+| `.codex/skills/` | All Codex skill definitions |
 | `scripts/install-codex.sh` | Global skill installer |
 
 ## For AI Agents
 
+### High-Priority Rules (Do First)
+
+1. Prefer retrieval-led reasoning over memory-led guessing.
+2. Build project context first, then apply skills/tools.
+3. Keep context lean: load only files needed for the current task.
+4. Verify with concrete evidence before claiming completion.
+
+### Retrieval-Led Reasoning (Mandatory)
+
+For framework/runtime/library-specific work:
+- Read the relevant repo docs/scripts first (`README.md`, `docs/`, `scripts/`, changed files).
+- Treat docs as source of truth when conflict exists with model memory.
+- Avoid speculative edits when version-specific behavior is unclear.
+
+Execution order:
+1. Inspect task + affected files.
+2. Retrieve exact docs/config relevant to that task.
+3. Implement the minimal correct change.
+4. Validate with commands/checks.
+5. Report result with evidence.
+
 ### Skill Invocation
 
-Codex auto-loads skills from:
-- `~/.codex/skills/<skill>/SKILL.md`
-- `<repo>/.codex/skills/<skill>/SKILL.md`
+Use skills as action workflows, not as the only knowledge source.
 
-When the user mentions a skill name or uses `$skill`, you should follow that skill.
+Trigger rules:
+- If user explicitly mentions a skill (or `$skill`), use it.
+- If task clearly maps to a skill's purpose, use the minimal matching skill set.
+- If a skill conflicts with repo source-of-truth docs, follow repo docs and state the conflict briefly.
 
 ### Source-of-Truth Workflow (Mandatory)
 
 For this repository, **`oh-my-codex` is the single source of truth** for skills and docs.
 
 Required order:
-1. Edit and validate files in this repo first (for example `.agent/skills/**/SKILL.md`).
+1. Edit and validate files in this repo first (for example `.codex/skills/**/SKILL.md`).
 2. Commit/push repository changes.
 3. Install/sync to runtime using installer scripts (for example `scripts/install-codex.sh` / `scripts/install-codex-force.sh`).
 
@@ -52,7 +74,7 @@ Codex does **not** support Claude Code plugins, interception lifecycle APIs, or
 - `.claude/` plugin cache paths
 - Claude Code-specific CLI commands
 
-…should be treated as **legacy** references from the original oh-my-claudecode.
+...should be treated as **legacy** references from the original oh-my-claudecode.
 
 ### Testing
 

package/README.md

@@ -57,6 +57,31 @@ Installs:
 ./scripts/install-codex.sh --all --project
 ```
 
+## AGENTS.md Templates (Global + Project)
+
+`omcodex setup` (user scope) now installs global guidance automatically:
+
+- `templates/AGENTS.global.md` -> `~/.codex/AGENTS.md`
+
+Use templates for manual override or project setup:
+
+- Global template: `templates/AGENTS.global.md` -> `~/.codex/AGENTS.md`
+- Project template: `templates/AGENTS.project.md` -> `<repo>/AGENTS.md`
+
+Example:
+
+```bash
+cp templates/AGENTS.global.md ~/.codex/AGENTS.md
+cp templates/AGENTS.project.md ./AGENTS.md
+```
+
+Optional discovery compatibility in `~/.codex/config.toml`:
+
+```toml
+project_doc_fallback_filenames = ["TEAM_GUIDE.md", ".agents.md"]
+project_doc_max_bytes = 65536
+```
+
 ---
 
 ## What You Get

package/README.zh.md

@@ -52,6 +52,31 @@ npx oh-my-codex-cli setup
 ./scripts/install-codex.sh --all --project
 ```
 
+## AGENTS.md 模板（全局 + 项目）
+
+`omcodex setup`（user scope）现在会自动安装全局 guidance：
+
+- `templates/AGENTS.global.md` -> `~/.codex/AGENTS.md`
+
+模板仍可用于手动覆盖或项目级配置：
+
+- 全局模板：`templates/AGENTS.global.md` -> 复制到 `~/.codex/AGENTS.md`
+- 项目模板：`templates/AGENTS.project.md` -> 复制到 `<repo>/AGENTS.md`
+
+示例：
+
+```bash
+cp templates/AGENTS.global.md ~/.codex/AGENTS.md
+cp templates/AGENTS.project.md ./AGENTS.md
+```
+
+可选：在 `~/.codex/config.toml` 增加发现配置：
+
+```toml
+project_doc_fallback_filenames = ["TEAM_GUIDE.md", ".agents.md"]
+project_doc_max_bytes = 65536
+```
+
 ---
 
 ## 安装后你能获得什么

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "oh-my-codex-cli",
-  "version": "0.2.1",
+  "version": "0.2.2",
   "description": "Codex skill pack and workflow orchestration",
   "bin": {
     "omcodex": "bin/omcodex.js"

package/src/catalog/generated/public-catalog.json

@@ -1,5 +1,5 @@
 {
-  "generatedAt": "2026-02-24T09:53:08.259Z",
+  "generatedAt": "2026-02-25T03:17:26.248Z",
   "counts": {
     "skillCount": 86,
     "promptCount": 3,

package/src/catalog/manifest.json

@@ -1,6 +1,6 @@
 {
   "schemaVersion": 1,
-  "catalogVersion": "2026-02-24",
+  "catalogVersion": "2026-02-25",
   "skills": [
     {
       "name": "agent-kb",

package/src/cli/index.js

@@ -8,7 +8,7 @@ const { route } = require('./route');
 const HELP = `oh-my-codex CLI (omcodex)
 
 Usage:
-  omcodex setup [--scope user|project-local|project] [--force] [--dry-run] [--verbose] [--no-prompts]
+  omcodex setup [--scope user|project-local|project] [--force] [--dry-run] [--verbose] [--no-prompts] [--no-agents]
   omcodex doctor
   omcodex team start \"<task>\"
   omcodex team status
@@ -54,6 +54,7 @@ async function main(args) {
       installSkills: !flags.has('--no-skills'),
       installPrompts: !flags.has('--no-prompts'),
       installRules: !flags.has('--no-rules'),
+      installAgents: !flags.has('--no-agents'),
       installConfig: !flags.has('--no-config'),
     });
     return;

package/src/cli/setup.js

@@ -62,6 +62,16 @@ async function copyDirectory(src, dest, options) {
   return count;
 }
 
+async function copyFile(src, dest, options) {
+  if (!fs.existsSync(src)) return false;
+  if (!options.force && fs.existsSync(dest)) return false;
+  if (!options.dryRun) {
+    await fsp.mkdir(path.dirname(dest), { recursive: true });
+    await fsp.copyFile(src, dest);
+  }
+  return true;
+}
+
 async function setup(options = {}) {
   const cwd = process.cwd();
   const root = path.resolve(__dirname, '..', '..');
@@ -81,6 +91,12 @@ async function setup(options = {}) {
   const rulesDest = scope === 'user'
     ? path.join(os.homedir(), '.codex', 'rules')
     : path.join(cwd, '.codex', 'rules');
+  const globalAgentsSources = [
+    path.join(root, 'templates', 'AGENTS.global.md'),
+    path.join(root, 'templates', 'AGENTS.md'),
+  ];
+  const globalAgentsSource = globalAgentsSources.find((candidate) => fs.existsSync(candidate)) || null;
+  const globalAgentsDest = path.join(os.homedir(), '.codex', 'AGENTS.md');
   const promptsSrc = promptsSource(root);
   const promptsDest = codexPromptsPath(scope, cwd);
 
@@ -97,7 +113,7 @@ async function setup(options = {}) {
 
   await persistScope(cwd, scope, options.dryRun);
 
-  console.log('[1/5] Installing skills...');
+  console.log('[1/6] Installing skills...');
   const shouldInstallSkills = options.installSkills !== false && scope !== 'project';
   const skillCount = shouldInstallSkills
     ? await copyDirectory(skillSrc, skillsDest, options)
@@ -109,7 +125,7 @@ async function setup(options = {}) {
     console.log('  Skipped for project scope');
   }
 
-  console.log('[2/5] Installing prompts...');
+  console.log('[2/6] Installing prompts...');
   const shouldInstallPrompts = options.installPrompts !== false && scope !== 'project';
   if (!shouldInstallPrompts) {
     console.log('  Skipped (--no-prompts or project scope)');
@@ -121,7 +137,7 @@ async function setup(options = {}) {
     console.log(`  ${label} ${promptCount} files -> ${promptsDest}`);
   }
 
-  console.log('[3/5] Installing rules...');
+  console.log('[3/6] Installing rules...');
   if (options.installRules !== false) {
     const ruleCount = await copyDirectory(rulesSource, rulesDest, options);
     const label = options.dryRun ? 'Would install/update' : 'Installed/updated';
@@ -130,7 +146,25 @@ async function setup(options = {}) {
     console.log('  Skipped (--no-rules)');
   }
 
-  console.log('[4/5] Merging config.toml...');
+  console.log('[4/6] Installing global AGENTS.md...');
+  if (options.installAgents === false) {
+    console.log('  Skipped (--no-agents)');
+  } else if (scope !== 'user') {
+    console.log('  Skipped (only applies to user scope)');
+  } else if (!globalAgentsSource) {
+    console.log('  Skipped (missing templates/AGENTS.global.md and templates/AGENTS.md)');
+  } else {
+    const installed = await copyFile(globalAgentsSource, globalAgentsDest, options);
+    const label = options.dryRun ? 'Would install/update' : 'Installed/updated';
+    if (installed || options.force || options.dryRun) {
+      console.log(`  ${label} ${globalAgentsDest}`);
+      console.log(`  Source: ${path.relative(root, globalAgentsSource)}`);
+    } else {
+      console.log(`  Skipped (already exists): ${globalAgentsDest}`);
+    }
+  }
+
+  console.log('[5/6] Merging config.toml...');
   if (options.installConfig !== false && !options.dryRun) {
     mergeConfig(configPath, root, { enableContext7: options.enableContext7 });
   }
@@ -141,7 +175,7 @@ async function setup(options = {}) {
     console.log('  Skipped (--no-config)');
   }
 
-  console.log('[5/5] Catalog check...');
+  console.log('[6/6] Catalog check...');
   const headline = getCatalogHeadlineCounts(root);
   if (headline) {
     console.log(`  Catalog baseline: ${headline.skills} skills, ${headline.prompts} prompts`);

package/templates/AGENTS.global.md

@@ -0,0 +1,80 @@
+# Global AGENTS.md for Codex
+
+This file is designed for `~/.codex/AGENTS.md`.
+It defines stable cross-project behavior and routes work to skills/workflows.
+
+## Objective
+
+- Maximize first-pass execution quality.
+- Make skill usage deterministic.
+- Keep behavior consistent across repositories.
+
+## Priority and Conflict Rules
+
+1. System/developer/user instructions have highest priority.
+2. Repository-local docs and config are source of truth for project specifics.
+3. Skills are execution workflows, not source-of-truth for project facts.
+4. If guidance conflicts, follow the highest-priority applicable source and state the conflict briefly.
+
+## Default Work Contract
+
+For every non-trivial request, execute in this order:
+1. Understand scope and affected files.
+2. Retrieve exact project context (docs/config/code) before implementation.
+3. Choose the minimal skill/toolset needed.
+4. Implement smallest correct change.
+5. Verify with concrete commands.
+6. Report outcome with evidence.
+
+## Skill Router
+
+### Explicit trigger
+
+- If user names a skill (e.g., `$autopilot`, `use review`), invoke it.
+
+### Implicit trigger
+
+- Planning/design requests -> `plan`, `review`, `architect-planner`.
+- Build/test failures -> `build-fix`, `verification-loop`, `ultraqa`.
+- Refactor/cleanup -> `refactor-clean`, `verify`.
+- Security-sensitive changes -> `security-review` + relevant implementation skill.
+- Broad delivery tasks -> `autopilot` (or `ultrapilot` for parallelized ownership).
+
+### Multi-skill composition
+
+- Use the minimal set of skills that fully covers the task.
+- State skill order before execution.
+- Do not carry skills across turns unless user re-mentions or task scope still clearly requires them.
+
+## Retrieval-Led Reasoning
+
+- Prefer current repository facts over memory.
+- For version-sensitive behavior, inspect local docs/config and runtime outputs before editing.
+- Avoid speculative changes when evidence is missing.
+
+## Verification Contract
+
+Before claiming completion, provide:
+
+1. Commands executed for validation.
+2. Key pass/fail results.
+3. Exact file paths changed.
+4. Remaining risks or unverified assumptions.
+
+## Safety and Git Rules
+
+- Never print or persist secrets/tokens in logs or docs.
+- Do not run destructive git operations unless explicitly requested.
+- Do not revert unrelated changes.
+- Prefer reversible, minimal patches.
+
+## Response Contract
+
+Use this output structure:
+
+1. Result summary
+2. Files changed
+3. Validation evidence
+4. Risks / next actions (if any)
+
+Keep responses concise and execution-focused.

package/templates/AGENTS.md

@@ -4,10 +4,16 @@ Skill pack and workflow orchestration for OpenAI Codex CLI.
 
 ## Guidance
 
-- Prefer skills for reusable workflows (`$skill` or explicit skill name in prompt).
-- Use Codex native multi-agent tools when a task benefits from delegation.
-- Verify outcomes with concrete evidence before claiming completion.
-- Keep instructions concise and implementation-focused.
+1. Prefer retrieval-led reasoning over memory-led guessing.
+2. Build project context first, then apply skills.
+3. Keep context lean and implementation-focused.
+4. Verify outcomes with concrete evidence before claiming completion.
+
+## Skill Usage
+
+- Skills are execution workflows; docs/config are source-of-truth knowledge.
+- If the user names a skill (or `$skill`), use it.
+- If a skill conflicts with repository docs, follow repository docs and note the conflict.
 
 ## Notify Compatibility
 

package/templates/AGENTS.project.md

@@ -0,0 +1,65 @@
+# Project AGENTS.md (Enhanced)
+
+This template is designed for repository root `AGENTS.md`.
+It should complement global guidance with project-specific rules.
+
+## Project Identity
+
+- Project name: <project-name>
+- Runtime/stack: <stack>
+- Main build/test commands: <commands>
+- Deploy boundary: <what must not be touched>
+
+## Source of Truth
+
+When rules conflict, use this order:
+1. Current task instructions.
+2. This repository's docs/config (`README`, `docs/`, `config files`).
+3. Skill workflow instructions.
+
+## Repository Working Rules
+
+- Edit files in-repo first; do not patch runtime mirrors first.
+- Keep changes minimal and scoped.
+- If touching scripts or build config, run at least one quick verification command.
+- Preserve existing architecture/style unless migration is explicitly requested.
+
+## Mandatory Execution Sequence
+
+1. Read task + locate impacted files.
+2. Read exact local docs/config related to those files.
+3. Implement minimal change.
+4. Run verification commands.
+5. Report with command evidence and changed file list.
+
+## Skill Policy (Project)
+
+- Use explicit skill requests as-is.
+- For ambiguous tasks, prefer conservative skill composition:
+  - implementation: `start-dev` or `autopilot`
+  - quality: `verification-loop` or `verify`
+  - risk-critical areas: `security-review`
+- If a skill suggests behavior that conflicts with this repo's docs/config, follow repo docs/config.
+
+## Definition of Done
+
+A task is done only when:
+
+1. Requested code/docs changes are applied.
+2. Appropriate checks have been run (or explicitly blocked with reason).
+3. Output includes what changed, where, and validation status.
+
+## High-Risk Guardrails
+
+- No credential leaks in code, logs, or docs.
+- No destructive git commands without explicit user request.
+- No silent behavior changes without documenting impact.
+
+## Suggested Project-Specific Additions
+
+Add concrete sections for your repo:
+
+- Directory ownership (who/what owns `src/*`, `scripts/*`, `docs/*`)
+- Command matrix (`lint`, `typecheck`, `test`, `build`)
+- Release checklist (version bump, changelog, tag, package publish)
+- Runtime compatibility constraints (Node version, package manager, OS)

package/templates/catalog-manifest.json

@@ -1,6 +1,6 @@
 {
   "schemaVersion": 1,
-  "catalogVersion": "2026-02-24",
+  "catalogVersion": "2026-02-25",
   "skills": [
     {
       "name": "agent-kb",