brain/templates/agent_protocol.py

"""Deterministic AGENT.md generation for workspace runtime.

This is a STABLE TEMPLATE with simple variable substitution.
Same inputs -> identical output every time.
No dynamic prompt construction. No conditional paragraphs.
"""

_AGENT_MD_TEMPLATE = """\

## Brain Instance

- **Name:** {brain_name}
- **Path:** {brain_path}
- **Project:** {project_name}

## Agent Instructions

### On Session Start

1. Read user context from `{brain_path}/user/` to understand preferences and workflows.
2. Read project handoff from `{brain_path}/projects/{project_name}/handoff.md` for continuity.
3. Read active tasks from `{brain_path}/projects/{project_name}/tasks.md`.

### During Development

1. Update `{brain_path}/projects/{project_name}/tasks.md` as work progresses.
2. Record architecture decisions in `{brain_path}/projects/{project_name}/decisions.md`.
3. Write session logs to `{brain_path}/agents/<your-agent-name>/`.

### On Session End

1. Update `{brain_path}/projects/{project_name}/handoff.md` with current state.
2. Ensure tasks reflect completed and remaining work.

## Key Paths

| Resource | Path |
|----------|------|
| User Context | `{brain_path}/user/` |
| Project Memory | `{brain_path}/projects/{project_name}/` |
| Agent Logs | `{brain_path}/agents/<your-agent-name>/` |
| Skills | `{brain_path}/skills/` |

## Continuity Protocol

Read handoff -> Work -> Update handoff.

Agents self-identify and write logs to their own directory under `agents/`.
"""


def generate_agent_md(
    brain_name: str, brain_path: "Path", project_name: str = ""
) -> str:
    """Generate deterministic AGENT.md content via simple substitution."""
    display_project = project_name if project_name else "<not-attached>"
    return _AGENT_MD_TEMPLATE.format(
        brain_name=brain_name,
        brain_path=str(brain_path.resolve()),
        project_name=display_project,
    )