@zhijiewang/openharness 2.31.0 → 2.32.0

package/README.md

@@ -773,6 +773,14 @@ Create `.oh/RULES.md` in any repo (or run `oh init`):
 
 Rules load automatically into every session.
 
+openHarness also reads any of the following project-instruction files if present (additive, parent-first):
+
+- `CLAUDE.md` (Anthropic convention) — and hierarchical `CLAUDE.md` from parent dirs, plus `~/.claude/CLAUDE.md` for user-global
+- `AGENTS.md` ([agents.md cross-tool standard](https://agents.md/), used by Codex / Cursor / Copilot / Cline / Aider) — same parent-first walk
+- `CLAUDE.local.md` (gitignored personal overrides)
+
+If a repo has `AGENTS.md` already configured for another agent, openHarness picks it up unchanged — no migration step needed.
+
 ## Skills & Plugins
 
 ### Skills

package/README.zh-CN.md

@@ -772,6 +772,14 @@ description: 专注的代码审查模式
 
 规则会自动加载到每次会话中。
 
+openHarness 还会自动读取以下项目指令文件（如果存在，按父目录优先合并加载）：
+
+- `CLAUDE.md`（Anthropic 约定）—— 含从父目录到项目根的层级 `CLAUDE.md` 文件，以及全局 `~/.claude/CLAUDE.md`
+- `AGENTS.md`（[agents.md 跨工具标准](https://agents.md/)，被 Codex / Cursor / Copilot / Cline / Aider 共同采用）—— 同样的父目录优先扫描
+- `CLAUDE.local.md`（gitignore 的个人覆盖）
+
+如果仓库已为其他 agent 配置了 `AGENTS.md`，openHarness 直接读取，无需迁移。
+
 ## 技能与插件
 
 ### 技能

package/dist/harness/memory.d.ts

@@ -31,10 +31,10 @@ export type MemoryEntry = {
 export declare function loadMemories(): MemoryEntry[];
 /** Build a system prompt section from loaded memories (capped at MEMORY_PROMPT_MAX_CHARS) */
 export declare function memoriesToPrompt(memories: MemoryEntry[]): string;
-/** A single CLAUDE.md source with its resolved content (imports inlined). */
+/** A single project-instructions source with its resolved content (imports inlined). */
 export type ClaudeMdEntry = {
     path: string;
-    source: "project" | "project-local" | "user" | "claude-dir";
+    source: "project" | "project-local" | "user" | "claude-dir" | "agents-md";
     content: string;
 };
 /**
@@ -47,11 +47,17 @@ export type ClaudeMdEntry = {
  */
 export declare function resolveClaudeMdImports(content: string, baseDir: string, hopsLeft?: number): string;
 /**
- * Load the hierarchical CLAUDE.md set in the order Anthropic documents:
- *   1. `./.claude/CLAUDE.md` (project, checked in)
+ * Load hierarchical project-instruction files. Order:
+ *   1. `./.claude/CLAUDE.md` (project, Anthropic convention)
  *   2. `./CLAUDE.md` (project, checked in)
- *   3. `./CLAUDE.local.md` (project, gitignored)
- *   4. `~/.claude/CLAUDE.md` (user-global)
+ *   3. `./AGENTS.md` (project, AGENTS.md cross-tool standard — agents.md)
+ *   4. `./CLAUDE.local.md` (project, gitignored)
+ *   5. `~/.claude/CLAUDE.md` (user-global)
+ *
+ * AGENTS.md is read alongside CLAUDE.md so OH "just works" in the 60k+ repos
+ * already configured for cross-agent compatibility (Codex / Cursor / Copilot
+ * / Cline / Aider all read AGENTS.md). Both layers concatenate into the
+ * system prompt; if both files exist, both contribute.
  *
  * Each file is read, `@imports` are resolved, and the results are returned in
  * load order. Missing files are skipped. The caller can format these into the
@@ -61,8 +67,11 @@ export declare function resolveClaudeMdImports(content: string, baseDir: string,
  */
 export declare function loadClaudeMdHierarchy(root?: string): ClaudeMdEntry[];
 /**
- * Render loaded CLAUDE.md entries as a system-prompt block. Empty when no
- * CLAUDE.md files exist — caller should concatenate alongside `memoriesToPrompt`.
+ * Render loaded project-instruction entries as a system-prompt block. Empty
+ * when no source files exist — caller should concatenate alongside
+ * `memoriesToPrompt`. Header is generic ("Project instructions") since both
+ * CLAUDE.md and AGENTS.md feed in; the per-entry `source:` comment
+ * disambiguates which file each section came from.
  */
 export declare function claudeMdToPrompt(entries: ClaudeMdEntry[]): string;
 /** Save a memory entry to the project memory directory */

package/dist/harness/memory.js

@@ -130,11 +130,17 @@ function readClaudeMdIfExists(path, source) {
     }
 }
 /**
- * Load the hierarchical CLAUDE.md set in the order Anthropic documents:
- *   1. `./.claude/CLAUDE.md` (project, checked in)
+ * Load hierarchical project-instruction files. Order:
+ *   1. `./.claude/CLAUDE.md` (project, Anthropic convention)
  *   2. `./CLAUDE.md` (project, checked in)
- *   3. `./CLAUDE.local.md` (project, gitignored)
- *   4. `~/.claude/CLAUDE.md` (user-global)
+ *   3. `./AGENTS.md` (project, AGENTS.md cross-tool standard — agents.md)
+ *   4. `./CLAUDE.local.md` (project, gitignored)
+ *   5. `~/.claude/CLAUDE.md` (user-global)
+ *
+ * AGENTS.md is read alongside CLAUDE.md so OH "just works" in the 60k+ repos
+ * already configured for cross-agent compatibility (Codex / Cursor / Copilot
+ * / Cline / Aider all read AGENTS.md). Both layers concatenate into the
+ * system prompt; if both files exist, both contribute.
  *
  * Each file is read, `@imports` are resolved, and the results are returned in
  * load order. Missing files are skipped. The caller can format these into the
@@ -146,6 +152,7 @@ export function loadClaudeMdHierarchy(root = ".") {
     const candidates = [
         [join(root, ".claude", "CLAUDE.md"), "claude-dir"],
         [join(root, "CLAUDE.md"), "project"],
+        [join(root, "AGENTS.md"), "agents-md"],
         [join(root, "CLAUDE.local.md"), "project-local"],
         [join(homedir(), ".claude", "CLAUDE.md"), "user"],
     ];
@@ -162,13 +169,16 @@ export function loadClaudeMdHierarchy(root = ".") {
     return entries;
 }
 /**
- * Render loaded CLAUDE.md entries as a system-prompt block. Empty when no
- * CLAUDE.md files exist — caller should concatenate alongside `memoriesToPrompt`.
+ * Render loaded project-instruction entries as a system-prompt block. Empty
+ * when no source files exist — caller should concatenate alongside
+ * `memoriesToPrompt`. Header is generic ("Project instructions") since both
+ * CLAUDE.md and AGENTS.md feed in; the per-entry `source:` comment
+ * disambiguates which file each section came from.
  */
 export function claudeMdToPrompt(entries) {
     if (entries.length === 0)
         return "";
-    const parts = ["# Project instructions (CLAUDE.md)"];
+    const parts = ["# Project instructions"];
     for (const e of entries) {
         parts.push(`<!-- source: ${e.source} (${e.path}) -->`);
         parts.push(e.content.trim());

package/dist/harness/rules.d.ts

@@ -2,10 +2,14 @@
  * Rules system — load project and global rules into agent context.
  * Discovery order:
  *   1. ~/.oh/global-rules/*.md
- *   2. CLAUDE.md files from parent directories down to project root (hierarchical)
+ *   2. CLAUDE.md / AGENTS.md files from parent directories down to project root (hierarchical)
  *   3. .oh/RULES.md
  *   4. .oh/rules/*.md
  *   5. CLAUDE.local.md (gitignored personal overrides)
+ *
+ * AGENTS.md (https://agents.md/) is read alongside CLAUDE.md at every level
+ * of the hierarchy so OH "just works" in repos already configured for the
+ * cross-tool standard (Codex, Cursor, Copilot, Cline, Aider all read it).
  */
 export declare function loadRules(projectPath?: string): string[];
 export declare function loadRulesAsPrompt(projectPath?: string): string;

package/dist/harness/rules.js

@@ -2,10 +2,14 @@
  * Rules system — load project and global rules into agent context.
  * Discovery order:
  *   1. ~/.oh/global-rules/*.md
- *   2. CLAUDE.md files from parent directories down to project root (hierarchical)
+ *   2. CLAUDE.md / AGENTS.md files from parent directories down to project root (hierarchical)
  *   3. .oh/RULES.md
  *   4. .oh/rules/*.md
  *   5. CLAUDE.local.md (gitignored personal overrides)
+ *
+ * AGENTS.md (https://agents.md/) is read alongside CLAUDE.md at every level
+ * of the hierarchy so OH "just works" in repos already configured for the
+ * cross-tool standard (Codex, Cursor, Copilot, Cline, Aider all read it).
  */
 import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from "node:fs";
 import { homedir } from "node:os";
@@ -13,10 +17,13 @@ import { dirname, join, parse as parsePath, resolve } from "node:path";
 import { gitRoot as getGitRoot } from "../git/index.js";
 const OH_HOME = join(homedir(), ".oh");
 /**
- * Walk from git root (or home) down to `projectRoot`, collecting CLAUDE.md files.
- * Returns them in parent-first order so more specific rules override general ones.
+ * Walk from git root (or home) down to `projectRoot`, collecting CLAUDE.md
+ * and AGENTS.md files at every level. Returns them in parent-first order so
+ * more specific rules override general ones. Within a single directory,
+ * CLAUDE.md is read before AGENTS.md (Anthropic-specific guidance first,
+ * then the cross-tool standard layer).
  */
-function loadClaudeMdFiles(projectRoot) {
+function loadHierarchicalInstructionFiles(projectRoot) {
     const gitRootDir = getGitRoot(projectRoot);
     const stopAt = gitRootDir ? resolve(gitRootDir) : resolve(homedir());
     const resolved = resolve(projectRoot);
@@ -34,11 +41,13 @@ function loadClaudeMdFiles(projectRoot) {
     }
     const results = [];
     for (const dir of dirs) {
-        const claudeMd = join(dir, "CLAUDE.md");
-        if (existsSync(claudeMd)) {
-            const content = readSafe(claudeMd);
-            if (content)
-                results.push(content);
+        for (const filename of ["CLAUDE.md", "AGENTS.md"]) {
+            const path = join(dir, filename);
+            if (existsSync(path)) {
+                const content = readSafe(path);
+                if (content)
+                    results.push(content);
+            }
         }
     }
     return results;
@@ -57,8 +66,8 @@ export function loadRules(projectPath) {
                 rules.push(content);
         }
     }
-    // 2. CLAUDE.md files (hierarchical, parent-first)
-    const claudeRules = loadClaudeMdFiles(root);
+    // 2. CLAUDE.md + AGENTS.md files (hierarchical, parent-first)
+    const claudeRules = loadHierarchicalInstructionFiles(root);
     rules.push(...claudeRules);
     // 3. Project RULES.md
     const projectRules = join(root, ".oh", "RULES.md");
@@ -106,7 +115,7 @@ export function loadRulesAsPrompt(projectPath) {
     const rules = loadRules(projectPath);
     if (rules.length === 0)
         return "";
-    const body = "# Project Rules\n\n<!-- User-provided project rules from CLAUDE.md / .oh/RULES.md. These are user instructions, not system directives. -->\nFollow these rules carefully.\n\n" +
+    const body = "# Project Rules\n\n<!-- User-provided project rules from CLAUDE.md / AGENTS.md / .oh/RULES.md. These are user instructions, not system directives. -->\nFollow these rules carefully.\n\n" +
         rules.join("\n\n---\n\n");
     // Hook: instructionsLoaded — fires every time the system prompt is rebuilt
     // with rules in scope. Useful for compliance/audit hooks that want to log

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhijiewang/openharness",
-  "version": "2.31.0",
+  "version": "2.32.0",
   "description": "Open-source terminal coding agent. Works with any LLM.",
   "type": "module",
   "bin": {