Project Structure

Agent management config lives in one global database. Agents require no project declaration file; a project directory is only a Workspace containing env, Skills, and business runtime data.

Directory layout

my-project/
├── .env                 # project environment variables
├── .agents/
│   └── skills/          # user-managed, versioned Skills
├── .downcity/           # Agent and Plugin runtime data
│   ├── agents/          # sessions and messages
│   ├── chat/            # Chat Access, routing, and history
│   ├── logs/            # runtime logs
│   ├── memory/          # memory data
│   └── task/            # task runtime data
└── src/                 # application code (optional)

Global config

The default database is ~/.downcity/downcity.db. With DC_PLATFORM_ROOT, it becomes $DC_PLATFORM_ROOT/downcity.db. It stores:

• Agent IDs, project paths, and startup options
• Model bindings and Plugin config
• Plugin Resources and Agent Plugin Bindings
• City sessions and other platform management state

The CLI, interactive manager, and Agent daemon all read this database. There is no project config copy.

agent_id is the global primary key; a Workspace path is not an identity. Multiple Agents may bind to one Workspace. Each Agent keeps independent daemon state at ~/.downcity/runtimes/<agent_id>/daemon.json, daemon.pid, and daemon.log.

Project assets

Global Env is stored separately in ~/.downcity/.env. Project .env overrides Global Env, while explicit process environment variables have the highest priority. Project .env is added to .gitignore by default. .agents/skills is the only user-managed Agent capability asset intended for version control.

Runtime data

.downcity/ only contains sessions, Chat Access, tasks, memory, and caches. Management config, PIDs, and daemon metadata do not belong there.

Continue with:

• Project Init
• Agent SDK