agenthome: unify persona contract in AGENTS.md (#749)

Author: jolestar

AGENTS.md

@@ -68,7 +68,7 @@ _ = os.Remove(tempFile)
 ## Agent-Specific Notes
 
 Holon runtime is now centered on `agent_home`:
-- persona and role files live under agent home (for example `AGENTS.md`, `ROLE.md`)
+- the canonical persona contract lives under agent home in `AGENTS.md` (with `CLAUDE.md` as a compatibility pointer)
 - runtime/skill behavior should rely on runtime contract variables and system-recommended directories
 - skills should avoid hardcoded Holon-specific filesystem paths and prefer runtime contract environment variables (for example `HOLON_OUTPUT_DIR`, `HOLON_STATE_DIR`, `HOLON_WORKSPACE_DIR`) instead of literal paths
 

README.md

@@ -12,7 +12,7 @@ Current product split:
 ## Agent Home Model
 
 `agent_home` is the long-lived identity and state root for an agent instance:
-- persona files (`AGENTS.md`, `ROLE.md`, `IDENTITY.md`, `SOUL.md`, `CLAUDE.md`)
+- the persona contract (`AGENTS.md`) plus `CLAUDE.md` as a compatibility pointer
 - runtime state and caches
 - job outputs and other runtime-managed artifacts (which may be associated with per-job workspaces)
 - optional runtime configuration

cmd/holon/agent.go

@@ -405,7 +405,7 @@ func init() {
 	agentInitCmd.Flags().StringVar(&agentInitID, "agent-id", "main", "Agent ID (default: main)")
 	agentInitCmd.Flags().StringVar(&agentInitHome, "agent-home", "", "Agent home directory (overrides --agent-id)")
 	agentInitCmd.Flags().StringVar(&agentInitTemplate, "template", agenthome.DefaultTemplate, "Persona template: default, github-solver, autonomous")
-	agentInitCmd.Flags().BoolVar(&agentInitForce, "force", false, "Overwrite existing persona files (AGENTS.md/ROLE.md/IDENTITY.md/SOUL.md/CLAUDE.md)")
+	agentInitCmd.Flags().BoolVar(&agentInitForce, "force", false, "Overwrite persona files (AGENTS.md/CLAUDE.md) and remove legacy persona files")
 
 	agentInstallCmd.Flags().String("name", "", "Alias name for the agent bundle (required)")
 	_ = agentInstallCmd.MarkFlagRequired("name")

cmd/holon/serve.go

@@ -20,6 +20,7 @@ import (
 	"syscall"
 	"time"
 
+	"github.com/holon-run/holon/pkg/agenthome"
 	holonlog "github.com/holon-run/holon/pkg/log"
 	"github.com/holon-run/holon/pkg/prompt"
 	"github.com/holon-run/holon/pkg/runtime/docker"
@@ -114,7 +115,7 @@ for local development and testing.`,
 		if err != nil {
 			return err
 		}
-		roleSource := filepath.Join(agentResolution.AgentHome, "ROLE.md")
+		roleSource := filepath.Join(agentResolution.AgentHome, "AGENTS.md")
 
 		handler, err := newCLIControllerHandler(
 			serveRepo,
@@ -369,72 +370,24 @@ for local development and testing.`,
 }
 
 func loadControllerRole(agentHome string) (string, error) {
-	rolePath := filepath.Join(agentHome, "ROLE.md")
-	info, err := os.Stat(rolePath)
+	persona, err := agenthome.LoadPersona(agentHome)
 	if err != nil {
-		return "", fmt.Errorf("failed to stat %s: %w", rolePath, err)
-	}
-	if !info.Mode().IsRegular() {
-		return "", fmt.Errorf("role prompt path is not a regular file: %s", rolePath)
-	}
-	data, err := os.ReadFile(rolePath)
-	if err != nil {
-		return "", fmt.Errorf("failed to read role prompt %s: %w", rolePath, err)
-	}
-	content := strings.TrimSpace(string(data))
-	if content == "" {
-		return "", fmt.Errorf("role prompt file is empty: %s (please add a role definition, e.g., '# ROLE: PM')", rolePath)
+		return "", err
 	}
-	return inferControllerRole(content), nil
+	return controllerRoleLabelForPersona(persona.Role), nil
 }
 
-func inferControllerRole(content string) string {
-	lower := strings.ToLower(content)
-	if role := inferRoleFromFrontMatter(lower); role != "" {
-		return role
-	}
+func controllerRoleLabelForPersona(role string) string {
 	switch {
-	case strings.Contains(lower, "role: dev"),
-		strings.Contains(lower, "role dev"),
-		strings.Contains(lower, "developer"),
-		strings.Contains(lower, "software engineer"):
+	case role == "executor", role == "github_solver":
 		return "dev"
-	case strings.Contains(lower, "role: pm"),
-		strings.Contains(lower, "role pm"),
-		strings.Contains(lower, "product manager"):
+	case role == "pm", role == "autonomous":
 		return "pm"
 	default:
 		return "pm"
 	}
 }
 
-func inferRoleFromFrontMatter(lower string) string {
-	trimmed := strings.TrimSpace(lower)
-	if !strings.HasPrefix(trimmed, "---\n") {
-		return ""
-	}
-	lines := strings.Split(trimmed, "\n")
-	for i := 1; i < len(lines); i++ {
-		line := strings.TrimSpace(lines[i])
-		if line == "---" {
-			return ""
-		}
-		if !strings.HasPrefix(line, "role:") {
-			continue
-		}
-		role := strings.TrimSpace(strings.TrimPrefix(line, "role:"))
-		switch role {
-		case "pm", "product-manager", "product_manager":
-			return "pm"
-		case "dev", "developer", "engineer":
-			return "dev"
-		default:
-			return ""
-		}
-	}
-	return ""
-}
-
 func startServeTickEmitter(ctx context.Context, interval time.Duration, repo string, sink func(context.Context, serve.EventEnvelope) error) {
 	if interval <= 0 {
 		return

cmd/holon/serve_test.go

@@ -495,7 +495,7 @@ func TestBuildServeStartupDiagnostics_SubscriptionRPCOnly(t *testing.T) {
 		StateDir:            "/tmp/agent/state",
 		Workspace:           "/tmp/agent/workspace",
 		ConfigSource:        "/tmp/agent/agent.yaml",
-		RoleSource:          "/tmp/agent/ROLE.md",
+		RoleSource:          "/tmp/agent/AGENTS.md",
 		RoleInferred:        "pm",
 		ServeInput:          "-",
 		InputMode:           "subscription",
@@ -515,7 +515,7 @@ func TestBuildServeStartupDiagnostics_SubscriptionRPCOnly(t *testing.T) {
 	if diag.SubscriptionReason != "empty_repos" {
 		t.Fatalf("subscription_reason = %q, want empty_repos", diag.SubscriptionReason)
 	}
-	if diag.RoleSource != "/tmp/agent/ROLE.md" {
+	if diag.RoleSource != "/tmp/agent/AGENTS.md" {
 		t.Fatalf("role_source = %q", diag.RoleSource)
 	}
 	if diag.RoleInferred != "pm" {
@@ -579,7 +579,7 @@ func TestWriteServeStartupDiagnostics(t *testing.T) {
 	td := t.TempDir()
 	diag := serveStartupDiagnostics{
 		AgentID:      "main",
-		RoleSource:   filepath.Join(td, "ROLE.md"),
+		RoleSource:   filepath.Join(td, "AGENTS.md"),
 		RoleInferred: "pm",
 		Preview:      "experimental",
 	}
@@ -961,20 +961,20 @@ func TestClose_StopsControllerAndRemovesSocket(t *testing.T) {
 	}
 }
 
-func TestInferControllerRole(t *testing.T) {
+func TestControllerRoleLabelForPersona(t *testing.T) {
 	t.Parallel()
 
-	if got := inferControllerRole("ROLE: PM\nProduct manager"); got != "pm" {
-		t.Fatalf("infer pm = %q", got)
+	tests := map[string]string{
+		"pm":            "pm",
+		"autonomous":    "pm",
+		"executor":      "dev",
+		"github_solver": "dev",
+		"unknown":       "pm",
 	}
-	if got := inferControllerRole("ROLE: DEV\nSoftware engineer"); got != "dev" {
-		t.Fatalf("infer dev = %q", got)
-	}
-	if got := inferControllerRole("unknown"); got != "pm" {
-		t.Fatalf("infer default = %q", got)
-	}
-	if got := inferControllerRole("---\nrole: dev\n---\nbody"); got != "dev" {
-		t.Fatalf("infer frontmatter dev = %q", got)
+	for role, want := range tests {
+		if got := controllerRoleLabelForPersona(role); got != want {
+			t.Fatalf("controllerRoleLabelForPersona(%q) = %q, want %q", role, got, want)
+		}
 	}
 }
 
@@ -1058,9 +1058,10 @@ func TestLoadControllerRole(t *testing.T) {
 	t.Parallel()
 
 	agentHome := t.TempDir()
-	rolePath := filepath.Join(agentHome, "ROLE.md")
-	if err := os.WriteFile(rolePath, []byte("ROLE: DEV\n"), 0o644); err != nil {
-		t.Fatalf("write role: %v", err)
+	agentsPath := filepath.Join(agentHome, "AGENTS.md")
+	content := "---\npersona_contract: v2\nrole: executor\n---\n# AGENTS.md\nbody\n"
+	if err := os.WriteFile(agentsPath, []byte(content), 0o644); err != nil {
+		t.Fatalf("write AGENTS.md: %v", err)
 	}
 	roleLabel, err := loadControllerRole(agentHome)
 	if err != nil {
@@ -1075,12 +1076,12 @@ func TestLoadControllerRole_EmptyFile(t *testing.T) {
 	t.Parallel()
 
 	agentHome := t.TempDir()
-	rolePath := filepath.Join(agentHome, "ROLE.md")
-	if err := os.WriteFile(rolePath, []byte("   \n"), 0o644); err != nil {
-		t.Fatalf("write role: %v", err)
+	agentsPath := filepath.Join(agentHome, "AGENTS.md")
+	if err := os.WriteFile(agentsPath, []byte("   \n"), 0o644); err != nil {
+		t.Fatalf("write AGENTS.md: %v", err)
 	}
 	if _, err := loadControllerRole(agentHome); err == nil {
-		t.Fatalf("expected error for empty ROLE.md")
+		t.Fatalf("expected error for empty AGENTS.md")
 	}
 }
 

docs/agent-home-persona-redesign.md

@@ -17,8 +17,8 @@ Current `holon agent init` persona files are too thin and inconsistent:
    - `github-solver`
    - `autonomous`
 4. Keep runtime behavior aligned with agent-home model:
-   - Holon contract explains file responsibilities
-   - Persona files are read/written by agent directly from `HOLON_AGENT_HOME`
+   - Holon contract explains the `AGENTS.md` responsibility
+   - Persona is read/written by agent directly from `HOLON_AGENT_HOME`
    - Holon does not inline persona content into the system prompt
 
 ## Non-Goals
@@ -31,13 +31,10 @@ Current `holon agent init` persona files are too thin and inconsistent:
 
 ### 1. Persona File Set
 
-`holon agent init` and `EnsureLayout*` generate the following files:
+`holon agent init` and `EnsureLayout*` generate the following persona files:
 
-- `AGENTS.md` (canonical persona and operating protocol)
+- `AGENTS.md` (canonical persona contract, including role front matter and operating protocol)
 - `CLAUDE.md` (compatibility pointer to `AGENTS.md`)
-- `ROLE.md` (current mission and scope)
-- `IDENTITY.md` (identity and collaboration defaults)
-- `SOUL.md` (decision principles)
 
 `CLAUDE.md` stays minimal and must not become a second source of truth.
 
@@ -73,7 +70,7 @@ Refactor `pkg/prompt/assets/contracts/common.md` into explicit sections:
 5. Reporting requirements
 6. Context handling
 
-The contract should reference `AGENTS.md` (not `AGENT.md`) and reinforce that persona files are loaded from `HOLON_AGENT_HOME`.
+The contract should reference `AGENTS.md` (not `AGENT.md`) and reinforce that persona is loaded from `HOLON_AGENT_HOME`.
 
 ## Implementation Plan
 

docs/agent-home-unification.md

@@ -55,16 +55,13 @@
 2. 可演进层（位于 `agent_home`，agent 可改）
 - `AGENTS.md`
 - `CLAUDE.md`（兼容入口，指向 `AGENTS.md`）
-- `ROLE.md`
-- `IDENTITY.md`
-- `SOUL.md`
 
 3. 运行时组装
 - 每轮重建 system prompt：
   1) immutable contract
   2) mode overlay (`run` / `serve`)
   3) runtime/tool/event context
-  4) agent-home persona files
+  4) agent-home persona contract
 
 ### 3.5 workspace 抽象（与 agent_home 解耦）
 
@@ -110,9 +107,6 @@
   agent.yaml
   AGENTS.md
   CLAUDE.md
-  ROLE.md
-  IDENTITY.md
-  SOUL.md
   state/
     serve-state.json
     goal-state.json
@@ -186,9 +180,6 @@ runtime:
 prompt:
   persona_files:
     - AGENTS.md
-    - ROLE.md
-    - IDENTITY.md
-    - SOUL.md
   system_contract: builtin://contracts/serve
 event_source:
   type: github-webhook
@@ -221,7 +212,7 @@ event_source:
 ### Phase 2: Prompt Loader 统一
 
 1. 新增统一 prompt 组装器
-- 输入：mode + runtime + tools + persona files
+- 输入：mode + runtime + tools + persona contract
 - 输出：system/user prompt
 
 2. 将 `run/solve/serve` 改为共用同一组装器

docs/architecture-current.md

@@ -11,7 +11,7 @@
 Holon executes agents in a sandboxed container runtime and centers persistence on `agent_home`.
 
 `agent_home` holds:
-- agent identity/persona files (`AGENTS.md`, `ROLE.md`, `IDENTITY.md`, `SOUL.md`, `CLAUDE.md`)
+- the canonical persona contract (`AGENTS.md`) and `CLAUDE.md` compatibility pointer
 - persistent runtime state
 - caches
 - long-lived agent/session metadata and optional job input/output history (for example logs, manifests, indexes)

docs/development.md

@@ -127,7 +127,7 @@ Use `holon agent …` to inspect and manage agent bundles/aliases:
 - `holon agent info default`
 - `holon agent init --template <default|github-solver|autonomous> [--force]`
 
-`holon agent init` templates are init-time only. Runtime prompts do not inline persona file bodies from `AGENTS.md/ROLE.md/IDENTITY.md/SOUL.md`; the agent reads them from `HOLON_AGENT_HOME`.
+`holon agent init` templates are init-time only. Runtime prompts do not inline persona file bodies; the agent reads `AGENTS.md` from `HOLON_AGENT_HOME`.
 
 Builtin agent resolution notes:
 - If no explicit agent is provided, Holon can resolve an agent via `--agent-channel` / `HOLON_AGENT_CHANNEL` (default: `latest`).

docs/serve-webhook.md

@@ -85,8 +85,8 @@ holon serve \
 On startup, `holon serve` writes `${state_dir}/serve-startup-diagnostics.json` and logs the same diagnostic snapshot.
 
 Key fields:
-- `role_source`: Always `${agent_home}/ROLE.md` (single source of truth)
-- `role_inferred`: Role inferred from `ROLE.md` content (`pm`/`dev`)
+- `role_source`: Always `${agent_home}/AGENTS.md` (single source of truth)
+- `role_inferred`: Controller role derived from `AGENTS.md` front matter (`pm`/`dev`)
 - `config_source`: `${agent_home}/agent.yaml`
 - `input_mode`: `subscription`, `webhook_legacy`, or `stdin_file`
 - `transport_mode`: `gh_forward`, `websocket`, `webhook`, `rpc_only`, or `none`