brain/templates/brain_instance.py

"""Brain Instance scaffolding — directory structure + template files."""

from pathlib import Path

# ── Directory structure ────────────────────────────────────

BRAIN_DIRS = [
    "user",
    "projects",
    "agent-configs",
    "agents/claude",
    "agents/cursor",
    "agents/codex",
    "skills",
    "raw",
    "versions",
]

# ── Template content ──────────────────────────────────────

TEMPLATES: dict[str, str] = {
    "user/personality.md": """\
# Personality

<!-- Describe your communication style, tone preferences, and how you like AI agents to interact with you. -->
""",
    "user/preferences.md": """\
# Preferences

## Coding
<!-- Languages, frameworks, patterns you prefer. -->

## Architecture
<!-- Monolith vs microservices, state management, etc. -->

## Communication
<!-- Verbose vs concise, explanation depth, etc. -->
""",
    "user/workflows.md": """\
# Workflows

<!-- Describe your typical development workflows, review processes, deployment habits. -->
""",
    "skills/coding-style.md": """\
# Coding Style

<!-- Conventions, naming patterns, formatting rules you follow. -->
""",
    "skills/debugging.md": """\
# Debugging Workflow

<!-- Your typical debugging approach, tools, and patterns. -->
""",
    "agent-configs/.cursorrules": """\
# Cursor Agent Configuration

Look for the `.brain/` directory in this workspace.
If found, read `.brain/AGENT.md` for full protocol instructions.
Follow the Brain continuity protocol for all operations.
""",
    "agent-configs/CLAUDE.md": """\
# Claude Agent Configuration

Look for the `.brain/` directory in this workspace.
If found, read `.brain/AGENT.md` for full protocol instructions.
Follow the Brain continuity protocol for all operations.
""",
    "AGENT.md": """\
# Brain Protocol

This is a Brain Instance — a persistent cognition environment for AI-assisted development.

## For AI Agents

You are operating inside a Brain-managed environment.
Your responsibilities:

1. Read context from `user/` to understand preferences.
2. Read and update project memory in `projects/<project>/`.
3. Write your session logs to `agents/<your-name>/`.
4. Follow the continuity protocol: read handoff -> work -> update handoff.
5. Record architecture decisions in the project's `decisions.md`.
6. Update `tasks.md` as work progresses.

## Structure

- `user/` — persistent user identity and preferences
- `projects/` — per-project memory (context, architecture, tasks, handoffs)
- `agent-configs/` — agent discovery and protocol configuration
- `agents/` — per-agent operational logs and session history
- `skills/` — reusable workflow conventions
- `raw/` — imported unstructured context
- `versions/` — historical snapshots created by `brain sync`
""",
}


def scaffold_brain_instance(brain_path: Path) -> None:
    """Create a full Brain Instance directory structure with template files."""
    # Create directories
    for d in BRAIN_DIRS:
        (brain_path / d).mkdir(parents=True, exist_ok=True)

    # Write template files
    for rel_path, content in TEMPLATES.items():
        file_path = brain_path / rel_path
        file_path.parent.mkdir(parents=True, exist_ok=True)
        file_path.write_text(content, encoding="utf-8")