Internals

Architecture: the grounding map.

This page exists so a developer — or a coding agent you point at the repo — can find the owner of any behavior without a tour guide. It's intentionally copy-pasteable into a coding-agent prompt.

Code root vs. instance root

The repository holds code; a separate instance root holds everything mutable: data/ (SQLite, settings), workspaces/, snapshots/, and .global/ (global agents, skills, tasks, templates). Resolution goes through core/instance_init.py — never hard-code repository-relative mutable paths. Start with python start.py, optionally --instance-dir <path>.

Application shape

A single FastAPI app: start.py boots AppPortal (app_portal.py), which builds shared state and registers routes with app_routes.py. Templates are Jinja2 in templates/; the web UI and the /api surface share one server and port. Routes orchestrate; managers own domain behavior — that boundary is the codebase's main rule.

Concept → owner

Concept	On disk	Owner module
Workspace	`workspaces/<ws>/WORKSPACE.md`	`core/workspace_manager.py`
Agent	`goto_agents/<agent>/AGENT.md`	`core/agent_manager.py`, runtime in `core/agent_runtime.py`
Skill	`skills/<name>/SKILL.md`	`core/skill_manager.py`
Activity	activity folders + playbook	`core/activity_manager.py`
Task	`TASK_*.md`	`core/task_manager.py`, `core/task_execution_manager.py`
Tool	workspace tool definitions	`core/tool_manager.py`, built-ins in `core/project_file_tools.py`
MCP	per-scope JSON registrations	`core/mcp_manager.py`, `core/mcp_client_manager.py`
Project	any folder + `GOTOAGENTS.md` + `.gotoagents/`	`core/project_context.py`, `core/project_manager.py`
Profile	profile root: `PROFILE.md`, `MEMORY.md`	`core/profile_manager.py`
Prompt	`system_template.md` per scope	`core/prompt_builder.py` (data only)
Sessions	SQLite	`core/chat_session_manager.py`
Database	`data/` SQLite	`core/database_manager.py` (raw sqlite3, no ORM)

Idioms worth knowing

Markdown + frontmatter everywhere, parsed only through core/file_parser.py. See Conventions.
Expected failures return error dataclasses (WorkspaceError, AgentError, SkillError, ...) rather than raising; callers check, not catch.
Prompt behavior lives in templates, not Python strings — PromptBuilder resolves and formats data only.
Defaults seed instances: defaults/ and init_config/ are source data for initialization, updated together with their tests.

Tests

pytest, tests under test/, focused-first: python -m pytest test/test_workspace_manager.py, then broaden. Filesystem tests use temporary instance roots, never a developer's real data.