Agent Zero AI framework
Include top-level AGENTS.md in project instructions
frdel08306be6502a
diff --git a/helpers/AGENTS.md b/helpers/AGENTS.mdindex 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.pyindex 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, castfrom helpers import files, dirty_json, persist_chat, file_treefrom 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: strdescription: strinstructions: str+ include_agents_md: NotRequired[bool]color: strgit_url: strfile_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.mdindex 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.pynew file mode 100644index 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.htmlindex 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.jsindex 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),};},