molecule-core/docs/agent-runtime/system-prompt-structure.md

# 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