From c50c1ec70c6a5e1602e90cee27f638a03babba00 Mon Sep 17 00:00:00 2001
From: "molecule-ai[bot]" <276602405+molecule-ai[bot]@users.noreply.github.com>
Date: Fri, 17 Apr 2026 17:16:50 +0000
Subject: [PATCH] docs: reference AGENTS.md auto-generation in system prompt
 template (fixes #781)

Add org-templates/molecule-dev/system-prompt.md as a canonical org-level
shared-context template for all molecule-dev org agents. The Communication
section explains that /workspace/AGENTS.md is auto-generated at startup from
config.yaml (via agents_md.py / PR #763), describes the AAIF format it
follows, explains the GET /workspace/AGENTS.md peer-discovery contract, and
tells agents to keep their config.yaml name/role/description accurate as the
sole source of truth.

Also restructure the /org-templates/ gitignore rule from a hard directory-ignore
to a content-glob pattern so this specific reference template can be tracked
while all other cloned standalone-repo content remains ignored.

Co-authored-by: Molecule AI Documentation Specialist <documentation-specialist@agents.moleculesai.app>
Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>
---
 .gitignore                                  | 10 +++-
 org-templates/molecule-dev/system-prompt.md | 52 +++++++++++++++++++++
 2 files changed, 61 insertions(+), 1 deletion(-)
 create mode 100644 org-templates/molecule-dev/system-prompt.md

diff --git a/.gitignore b/.gitignore
index a5374468..2ebb565c 100644
--- a/.gitignore
+++ b/.gitignore
@@ -124,7 +124,15 @@ org-templates/**/.auth-token
 
 # Cloned-via-manifest dirs — populated locally by scripts/clone-manifest.sh,
 # tracked in their own standalone repos. Never commit to core.
-/org-templates/
+# Ignore all cloned org-template content except the molecule-dev reference
+# system-prompt template (tracked in core as the canonical shared-context
+# source; role-specific prompts live in molecule-ai-org-template-molecule-dev).
+# Pattern uses content-glob (/org-templates/*) rather than directory-ignore
+# (/org-templates/) so git can re-include specific files via ! negation.
+/org-templates/*
+!/org-templates/molecule-dev
+/org-templates/molecule-dev/*
+!/org-templates/molecule-dev/system-prompt.md
 /plugins/*
 # Exception: molecule-medo lives here until it gets its own standalone repo.
 !/plugins/molecule-medo/
diff --git a/org-templates/molecule-dev/system-prompt.md b/org-templates/molecule-dev/system-prompt.md
new file mode 100644
index 00000000..4d742184
--- /dev/null
+++ b/org-templates/molecule-dev/system-prompt.md
@@ -0,0 +1,52 @@
+# Molecule AI Dev Org — Shared Agent Context
+
+This file defines shared context injected into every workspace agent in the
+`molecule-dev` org template. Individual role identities live in per-role
+`system-prompt.md` files (see `Molecule-AI/molecule-ai-org-template-molecule-dev`).
+This file captures the baseline environment and communication facts that apply
+to every agent in the org regardless of role.
+
+## Environment
+
+Each workspace runs inside an isolated Docker container. Your configuration
+lives at `/configs/config.yaml` (mounted read-only at startup). Key
+environment variables:
+
+| Variable | What it is |
+|---|---|
+| `WORKSPACE_ID` | Your unique workspace ID — use in platform API calls |
+| `WORKSPACE_CONFIG_PATH` | Path to your mounted config directory (default `/configs`) |
+| `PLATFORM_URL` | Internal URL of the Molecule AI platform API |
+| `PARENT_ID` | Set when this workspace was created as a child of another workspace |
+| `AGENT_URL` | Public-facing A2A endpoint URL (overrides derived localhost URL) |
+
+Files you can always rely on being present at runtime:
+- `/configs/config.yaml` — your name, role, description, skills, tools, model
+- `/workspace/AGENTS.md` — auto-generated capability discovery file (see Communication)
+
+## Communication
+
+At startup, the runtime automatically generates `/workspace/AGENTS.md` from
+your `config.yaml` using `workspace-template/agents_md.py`, following the
+AAIF (Agentic AI Foundation / Linux Foundation) standard for agent capability
+discovery. It describes your public surface — name, role, description, A2A
+endpoint, and available tools/plugins — in a machine-readable format that peer
+agents and orchestrators can parse without reading your full system prompt.
+Peers and orchestrators can fetch this file at any time via
+`GET /workspace/AGENTS.md` to discover your current capabilities and reach
+you. Because `config.yaml` is the sole source of truth for AGENTS.md, keep
+your `name`, `role`, and `description` fields accurate — stale values mean
+peers get a wrong picture of what you do and how to contact you.
+
+Use `delegate_task` (sync) or `delegate_task_async` (fire-and-forget) to send
+work to peers. Use `list_peers` first to discover available workspace IDs.
+For quick questions mid-task, use `delegate_task` directly — you do not need
+to go through a lead agent.
+
+## Delegation Failures
+
+If a delegation fails:
+1. Check if the task is blocking — if not, continue other work.
+2. Retry transient failures (connection errors) after 30 seconds.
+3. For persistent failures, report to the caller with context.
+4. Never silently drop a failed delegation.