diff --git a/content/docs/agent-runtime/system-prompt-structure.md b/content/docs/agent-runtime/system-prompt-structure.md new file mode 100644 index 0000000..995c4d2 --- /dev/null +++ b/content/docs/agent-runtime/system-prompt-structure.md @@ -0,0 +1,160 @@ +# System Prompt Structure + +When a workspace agent starts (or rebuilds its prompt), the system prompt is assembled in a specific order: **specific to general** — the agent's own identity first, then what it can do, then what it can delegate. + +## Assembly Order + +``` +1. Prompt files — agent's core identity and instructions (system-prompt.md or custom list) +2. Parent context — shared files from direct parent (if child workspace) +3. Platform rules & prompts — plugin rules, coordinator prompt +4. Skill instructions — SKILL.md body from each loaded skill +5. Reachable workspace cards — Agent Card skill descriptions from peers +6. Delegation failure handling — always appended +``` + +### 1. system-prompt.md + +The workspace's core identity. Written by the workspace author. Defines the agent's role, personality, and high-level instructions. + +Example for a Developer PM: +```markdown +You are a Developer PM. You coordinate a development team to build features. +When you receive a task, break it into sub-tasks and delegate to your team. +Always review work before reporting completion to the caller. +``` + +### 2. Parent Context (if child workspace) + +If this workspace was created via team expansion (has a `PARENT_ID` env var), it fetches its parent's shared context files at startup via `GET /workspaces/{parent_id}/shared-context`. The parent declares which files to share in its `config.yaml`: + +```yaml +shared_context: + - architecture.md + - conventions.md +``` + +These files are injected as a `## Parent Context` section, with each file rendered under a `### {filename}` heading. This gives children the parent's project knowledge (architecture, conventions, API schemas) without exposing the parent's system prompt or full config. + +**1-level inheritance only:** A grandchild sees its direct parent's shared context, not its grandparent's. This mirrors the L2 Team Memory scope. + +**Graceful degradation:** If the parent is offline or the endpoint returns an error, the child starts normally without parent context. + +### 3. Skill Instructions + +The body (non-frontmatter) content of each `SKILL.md` from loaded skills. Appended in the order listed in `config.yaml`. This tells the agent what it can do directly. + +### 3. Reachable Workspace Agent Cards + +Skill descriptions from Agent Cards of all reachable workspaces (siblings, sub-workspaces, parent). This tells the agent what it can delegate. + +The workspace queries the platform for reachable peers and injects their capabilities: + +```python +async def build_system_prompt(config_path: Path) -> str: + # 1. own identity + prompt = load_markdown(config_path / "system-prompt.md") + + # 2. own skills + for skill in loaded_skills: + prompt += f"\n\n## Skill: {skill.name}\n{skill.instructions}" + + # 3. reachable workspace capabilities + peers = await platform.get(f"/registry/{WORKSPACE_ID}/peers") + for peer in peers: + card = peer["agent_card"] + prompt += f"\n\n## Available Workspace: {card['name']}\n" + prompt += f"Description: {card['description']}\n" + for skill in card.get("skills", []): + prompt += f"- {skill['name']}: {skill['description']}\n" + + return prompt +``` + +## When the Prompt Is Rebuilt + +The workspace subscribes to the platform WebSocket (with `X-Workspace-ID` header) and receives filtered events about reachable peers. The system prompt is rebuilt automatically when any of these events occur: + +| Trigger | Source | What changed | +|---------|--------|-------------| +| Startup | — | Initial build | +| File watcher detects config change | Local filesystem | Own skills, model, or system prompt changed | +| `AGENT_CARD_UPDATED` received | Platform WebSocket | A peer's capabilities changed | +| `WORKSPACE_ONLINE` / `WORKSPACE_OFFLINE` | Platform WebSocket | A peer came online or went offline | +| `WORKSPACE_EXPANDED` | Platform WebSocket | A peer expanded into a team | +| `WORKSPACE_REMOVED` | Platform WebSocket | A peer was deleted | + +## Delegation Behavior + +On each new task, the agent checks the registry for its sub-workspaces and decides what to delegate for best efficiency. The agent uses the injected capability descriptions to make routing decisions — no explicit routing config is needed. + +For example, if Developer PM's prompt includes: +``` +## Available Workspace: Frontend Agent +- Build React Components: Creates React components from Figma designs + +## Available Workspace: Backend Agent +- Build API Endpoints: Creates REST API endpoints with validation + +## Available Workspace: QA Agent +- Run Test Suite: Executes automated tests and reports results +``` + +Then when Developer PM receives "build the login feature", it naturally delegates the UI to Frontend, the API to Backend, and testing to QA — based purely on the skill descriptions in its prompt. + +## Human-in-the-Loop (Hierarchical Approval) + +LangGraph natively supports pausing an agent to ask for human approval. Molecule AI extends this with **hierarchical escalation** — an agent can pause and escalate approval up the workspace hierarchy. + +### How It Works + +When an agent encounters something that requires approval (a destructive action, an expensive operation, or something outside its stated authority): + +1. The agent pauses its current task +2. The agent sends an approval request **up to its parent workspace** via A2A +3. The parent workspace's agent decides: + - **Approve** — the child resumes + - **Deny** — the child aborts or takes an alternative action + - **Escalate** — the parent doesn't have authority either, so it escalates to **its** parent +4. Escalation continues up the hierarchy until either a workspace approves/denies or the request reaches the **root workspace** +5. The root workspace (top of the org chart) surfaces the request to the **human user** via the canvas UI + +### Example Flow + +``` +Frontend Agent wants to delete the production database schema + | + v +Pauses, asks Developer PM for approval (parent) + | + v +Developer PM: "This is too destructive, I need to escalate" + | + v +Asks Business Core for approval (its parent) + | + v +Business Core is the root — surfaces to human on canvas + | + v +Human approves or denies via canvas UI + | + v +Decision flows back down: Business Core -> Developer PM -> Frontend Agent +``` + +### What Triggers Escalation + +The agent's system prompt defines what actions are within its authority and what requires approval. This is part of the workspace author's configuration — not hardcoded. Typical patterns: + +- Destructive actions (deleting data, removing infrastructure) +- Actions above a cost threshold +- Actions not explicitly authorized in the system prompt +- First-time actions the agent hasn't done before + +## Related Docs + +- [Skills](./skills.md) — Skill package structure +- [Agent Card](./agent-card.md) — How cards drive delegation +- [Workspace Runtime](./workspace-runtime.md) — Where prompt is assembled +- [Communication Rules](../api-protocol/communication-rules.md) — Who can talk to whom