Skip to content

Agent Zero AI framework

Include top-level AGENTS.md in project instructions

frdel08306be6502a
diff --git a/helpers/AGENTS.md b/helpers/AGENTS.md
index dd3c60f3e..bb70bf289 100644
--- a/helpers/AGENTS.md
+++ b/helpers/AGENTS.md
@@ -15,6 +15,7 @@
- Preserve public helper APIs used by core code and plugins unless all callers, docs, and tests are updated.
- Use structured parsers and serializers for YAML, JSON, paths, and URLs instead of ad hoc string handling.
- Keep path handling constrained to intended roots for user files, uploads, downloads, projects, and workdirs.
+- Project metadata defaults must remain backwards-compatible; missing `include_agents_md` is treated as enabled and project instruction file content is injected with an explicit source path.
- Do not hardcode secrets, provider keys, local absolute paths, or environment-specific values.
- Use `RepairableException` for errors an agent may be able to fix.
diff --git a/helpers/projects.py b/helpers/projects.py
index 089656a98..e103e5f87 100644
--- a/helpers/projects.py
+++ b/helpers/projects.py
@@ -1,5 +1,5 @@
import os
-from typing import Literal, TypedDict, TYPE_CHECKING, cast
+from typing import Literal, NotRequired, TypedDict, TYPE_CHECKING, cast
from helpers import files, dirty_json, persist_chat, file_tree
from helpers.print_style import PrintStyle
@@ -13,6 +13,7 @@ PROJECT_META_DIR = ".a0proj"
PROJECT_INSTRUCTIONS_DIR = "instructions"
PROJECT_KNOWLEDGE_DIR = "knowledge"
PROJECT_HEADER_FILE = "project.json"
+PROJECT_AGENTS_MD_FILES = ("AGENTS.md", "Agents.md", "agents.md")
CONTEXT_DATA_KEY_PROJECT = "project"
@@ -32,6 +33,7 @@ class BasicProjectData(TypedDict):
title: str
description: str
instructions: str
+ include_agents_md: NotRequired[bool]
color: str
git_url: str
file_structure: FileStructureInjectionSettings
@@ -159,6 +161,9 @@ def _normalizeBasicData(data: BasicProjectData) -> BasicProjectData:
"title": data.get("title", ""),
"description": data.get("description", ""),
"instructions": data.get("instructions", ""),
+ "include_agents_md": _normalize_include_agents_md(
+ data.get("include_agents_md", True)
+ ),
"color": data.get("color", ""),
"git_url": data.get("git_url", ""),
"file_structure": data.get(
@@ -174,6 +179,9 @@ def _normalizeEditData(data: EditProjectData) -> EditProjectData:
"title": data.get("title", ""),
"description": data.get("description", ""),
"instructions": data.get("instructions", ""),
+ "include_agents_md": _normalize_include_agents_md(
+ data.get("include_agents_md", True)
+ ),
"variables": data.get("variables", ""),
"color": data.get("color", ""),
"git_url": data.get("git_url", ""),
@@ -270,7 +278,7 @@ def load_edit_project_data(name: str) -> EditProjectData:
def save_project_header(name: str, data: BasicProjectData):
# save project header file
- header = dirty_json.stringify(data)
+ header = dirty_json.stringify(_project_header_for_save(data))
abs_path = files.get_abs_path(
PROJECTS_PARENT_DIR, name, PROJECT_META_DIR, PROJECT_HEADER_FILE
)
@@ -423,12 +431,16 @@ def deactivate_project_in_chats(name: str):
def build_system_prompt_vars(name: str):
project_data = load_basic_project_data(name)
main_instructions = project_data.get("instructions", "") or ""
- additional_instructions = get_additional_instructions_files(name)
- complete_instructions = (
- main_instructions
- + "\n\n".join(
- additional_instructions[k] for k in sorted(additional_instructions)
- )
+ instruction_files = get_project_instruction_files(
+ name,
+ include_agents_md=project_data.get("include_agents_md", True),
+ )
+ instruction_parts = [
+ main_instructions,
+ _format_project_instruction_files(instruction_files),
+ ]
+ complete_instructions = "\n\n".join(
+ part.strip() for part in instruction_parts if part.strip()
).strip()
return {
"project_name": project_data.get("title", ""),
@@ -446,6 +458,71 @@ def get_additional_instructions_files(name: str):
return files.read_text_files_in_dir(instructions_folder)
+def get_project_instruction_files(
+ name: str,
+ include_agents_md: bool = True,
+) -> list[tuple[str, str]]:
+ project_folder = get_project_folder(name)
+ result: list[tuple[str, str]] = []
+
+ if include_agents_md:
+ agents_md = get_project_agents_md_instruction_file(name)
+ if agents_md:
+ result.append(agents_md)
+
+ additional_instructions = get_additional_instructions_files(name)
+ for filename in sorted(additional_instructions):
+ path = files.get_abs_path(
+ project_folder,
+ PROJECT_META_DIR,
+ PROJECT_INSTRUCTIONS_DIR,
+ filename,
+ )
+ result.append(
+ (files.normalize_a0_path(path), additional_instructions[filename])
+ )
+
+ return result
+
+
+def get_project_agents_md_instruction_file(name: str) -> tuple[str, str] | None:
+ project_folder = get_project_folder(name)
+ for filename in PROJECT_AGENTS_MD_FILES:
+ matches = files.read_text_files_in_dir(project_folder, pattern=filename)
+ if filename in matches:
+ path = files.get_abs_path(project_folder, filename)
+ return (files.normalize_a0_path(path), matches[filename])
+ return None
+
+
+def _format_project_instruction_files(instruction_files: list[tuple[str, str]]) -> str:
+ if not instruction_files:
+ return ""
+
+ parts = ["## project instruction files"]
+ for path, content in instruction_files:
+ parts.append(f"### path: {path}\n\n{content}")
+ return "\n\n".join(parts)
+
+
+def _normalize_include_agents_md(value: object) -> bool:
+ if value is None:
+ return True
+ if isinstance(value, bool):
+ return value
+ if isinstance(value, str):
+ return value.strip().lower() not in {"0", "false", "no", "off"}
+ return bool(value)
+
+
+def _project_header_for_save(data: BasicProjectData) -> dict:
+ header = dict(data)
+ header["include_agents_md"] = _normalize_include_agents_md(
+ header.get("include_agents_md", True)
+ )
+ return header
+
+
def get_context_project_name(context: "AgentContext") -> str | None:
return context.get_data(CONTEXT_DATA_KEY_PROJECT)
diff --git a/prompts/agent.system.projects.active.md b/prompts/agent.system.projects.active.md
index 8ef406e1e..5736e6e17 100644
--- a/prompts/agent.system.projects.active.md
+++ b/prompts/agent.system.projects.active.md
@@ -6,5 +6,6 @@ path: {{project_path}}
rules:
- work inside {{project_path}}
- do not rename project dir or change `.a0proj` unless asked
+- must always follow project instructions below
{{project_instructions}}
diff --git a/tests/test_projects.py b/tests/test_projects.py
new file mode 100644
index 000000000..fd3a28357
--- /dev/null
+++ b/tests/test_projects.py
@@ -0,0 +1,69 @@
+from pathlib import Path
+
+from helpers import dirty_json, files, projects
+
+
+def _prepare_project_tree(monkeypatch, tmp_path: Path) -> None:
+ monkeypatch.setattr(files, "_base_dir", str(tmp_path))
+ (tmp_path / "usr" / "projects").mkdir(parents=True, exist_ok=True)
+
+
+def test_project_include_agents_md_defaults_true_and_saves(monkeypatch, tmp_path):
+ _prepare_project_tree(monkeypatch, tmp_path)
+ meta = tmp_path / "usr" / "projects" / "demo" / ".a0proj"
+ meta.mkdir(parents=True)
+ (meta / "project.json").write_text('{"title": "Demo"}', encoding="utf-8")
+
+ data = projects.load_basic_project_data("demo")
+
+ assert data["include_agents_md"] is True
+
+ projects.save_project_header("demo", data)
+ saved = dirty_json.parse((meta / "project.json").read_text(encoding="utf-8"))
+
+ assert saved["include_agents_md"] is True
+
+
+def test_project_system_prompt_includes_root_agents_md_with_path(monkeypatch, tmp_path):
+ _prepare_project_tree(monkeypatch, tmp_path)
+ projects.create_project(
+ "demo",
+ {
+ "title": "Demo",
+ "instructions": "Main project rule.",
+ },
+ )
+ project_root = tmp_path / "usr" / "projects" / "demo"
+ (project_root / "AGENTS.md").write_text("Root AGENTS rule.", encoding="utf-8")
+ (
+ project_root / ".a0proj" / "instructions" / "extra.md"
+ ).write_text("Folder instruction rule.", encoding="utf-8")
+
+ prompt_vars = projects.build_system_prompt_vars("demo")
+ instructions = prompt_vars["project_instructions"]
+
+ assert "Main project rule." in instructions
+ assert instructions.count("## project instruction files") == 1
+ assert "## project instruction file\n" not in instructions
+ assert "### path: /a0/usr/projects/demo/AGENTS.md" in instructions
+ assert "Root AGENTS rule." in instructions
+ assert "### path: /a0/usr/projects/demo/.a0proj/instructions/extra.md" in instructions
+ assert "Folder instruction rule." in instructions
+
+
+def test_project_system_prompt_respects_disabled_agents_md(monkeypatch, tmp_path):
+ _prepare_project_tree(monkeypatch, tmp_path)
+ projects.create_project(
+ "demo",
+ {
+ "title": "Demo",
+ "include_agents_md": False,
+ },
+ )
+ project_root = tmp_path / "usr" / "projects" / "demo"
+ (project_root / "AGENTS.md").write_text("Root AGENTS rule.", encoding="utf-8")
+
+ prompt_vars = projects.build_system_prompt_vars("demo")
+
+ assert "Root AGENTS rule." not in prompt_vars["project_instructions"]
+ assert "AGENTS.md" not in prompt_vars["project_instructions"]
diff --git a/webui/components/projects/project-edit-instructions.html b/webui/components/projects/project-edit-instructions.html
index f91cfb70c..f76c7a64d 100644
--- a/webui/components/projects/project-edit-instructions.html
+++ b/webui/components/projects/project-edit-instructions.html
@@ -33,6 +33,20 @@
placeholder="Enter project instructions"></textarea>
</div>
+ <div class="projects-setting-row" style="padding: 1rem 0;">
+ <div class="projects-setting-text">
+ <label class="projects-form-label">Include top-level AGENTS.md</label>
+ <span class="projects-form-description">When turned on, Agent Zero will include the project's
+ top-level AGENTS.md file in the active project instructions when that file exists.</span>
+ </div>
+ <div class="projects-setting-control">
+ <label class="toggle">
+ <input type="checkbox" x-model="$store.projects.selectedProject.include_agents_md">
+ <span class="toggler"></span>
+ </label>
+ </div>
+ </div>
+
<div class="projects-form-group">
<label class="projects-form-label">Instruction files</label>
<div class="projects-input-with-button-wrapper">
@@ -55,4 +69,4 @@
<style>
</style>
-</html>
\ No newline at end of file
+</html>
diff --git a/webui/components/projects/projects-store.js b/webui/components/projects/projects-store.js
index 910200741..8cec83edc 100644
--- a/webui/components/projects/projects-store.js
+++ b/webui/components/projects/projects-store.js
@@ -162,6 +162,7 @@ const model = {
title: project.title,
color: project.color,
git_url: project.git_url,
+ include_agents_md: project.include_agents_md !== false,
git_token: project.git_token || "",
llm: project.llm || null,
},
@@ -407,6 +408,8 @@ const model = {
name: ``,
title: `Project #${this.projectList.length + 1}`,
description: "",
+ instructions: "",
+ include_agents_md: true,
color: "",
git_url: "",
git_token: "",
@@ -425,6 +428,7 @@ const model = {
creating: false,
},
...projectData,
+ include_agents_md: projectData.include_agents_md !== false,
llm: this._normalizeProjectLlmData(projectData.llm, name),
};
},