Codocia AI Map

This file is optimized for AI agents reading the repository structure.

agent

Language: rust Path: crates/agent

Agent owns execution planning and model/tool orchestration.

Owns:

• Agent
• execution input and output
• tool registry consumption
• event production

Must Not:

• own daemon lifecycle
• write durable storage directly
• render UI
• parse UI picker state

Depends On:

• event
• model
• skill
• tool

Verify:

• cargo check -p agent

auth

Language: rust Path: crates/auth

Auth owns secret references and provider access profiles.

Owns:

• SecretRef
• Profile
• provider credential references
• profile repository helpers

Must Not:

• expose secret values in docs
• define model catalog entries
• call UI code

Depends On:

• model
• store

Verify:

• cargo check -p auth

bridge

Language: rust Path: crates/bridge

Bridge owns adapter-safe DTOs for moving legacy boundary data into Core.

Owns:

• migration DTOs
• boundary-safe snapshot shape
• legacy-to-core value conversion
• command conversion helpers

Must Not:

• depend on legacy skrun crates
• read or write durable storage
• execute runtime behavior
• own UI interaction state

Depends On:

• auth
• chat
• model
• run
• skill
• tool

Verify:

• cargo check -p bridge

chat

Language: rust Path: crates/chat

Chat owns sessions, turns, and message history.

Owns:

• Session
• Message
• Role
• chat history composition
• session metadata required for resume and migration
• session repository helpers

Must Not:

• own durable background runs
• render TUI layout
• decide model catalog policy

Depends On:

• agent
• event
• skill
• store

Verify:

• cargo check -p chat

cli

Language: rust Path: crates/cli

CLI owns the minimal executable skill command loop.

Owns:

• skill artifact scaffolding command
• skill artifact build command
• skill artifact run command
• local skill install and list commands

Must Not:

• start the legacy daemon
• render TUI state
• own runtime skill execution
• own Python package behavior

Depends On:

• runtime

Verify:

• cargo test -p cli

engine

Language: rust Path: crates/engine

Engine owns core composition and command execution boundary.

Owns:

• core API entrypoint
• in-memory core composition
• shared store bundle wiring
• model, profile, and skill catalog helpers

Must Not:

• own product transport details
• own persistence
• duplicate module logic

Depends On:

• agent
• auth
• chat
• event
• model
• run
• skill
• store
• tool

Verify:

• cargo check -p engine

event

Language: rust Path: crates/event

Event owns shared stream and trace event types.

Owns:

• text events
• tool call events
• tool result events
• error and completion events
• event constructors

Must Not:

• persist events directly
• render UI
• call tools

Verify:

• cargo check -p event

model

Language: rust Path: crates/model

Model owns provider and model identity for the core.

Owns:

• provider identity
• model identity
• canonical model construction
• model catalog
• model selection

Must Not:

• read secrets
• call model providers
• depend on daemon state

Verify:

• cargo check -p model

proto

Language: rust Path: crates/proto

Proto owns the command and response protocol model.

Owns:

• CoreCommand
• CoreResponse
• CoreSnapshot
• tagged JSON protocol shape

Must Not:

• execute commands
• own transport details
• own storage
• render UI

Depends On:

• auth
• chat
• event
• model
• run
• skill
• tool

Verify:

• cargo check -p proto

python-skrun-skill

Language: python Path: python/skrun/skill.py

Python skill owns the SDK wrapper for executable skill artifacts.

Owns:

• Python artifact dataclasses
• native-backed skill calls
• installed skill lookup helpers
• local skill installation wrapper

Must Not:

• duplicate Rust runtime validation
• execute skill subprocesses directly
• own agent planning

Depends On:

• runtime

Verify:

• python3 -m unittest discover -s python/tests

run

Language: rust Path: crates/run

Run owns durable task and run execution concepts.

Owns:

• Task
• Run
• run status
• durable execution vocabulary
• migration-safe task and run metadata
• task and run repository helpers

Must Not:

• become a second agent loop
• own skill catalog
• create a separate team runtime

Depends On:

• agent
• chat
• event
• skill
• store

Verify:

• cargo check -p run

runtime

Language: rust Path: crates/runtime

Runtime owns executable skill artifacts.

Owns:

• executable skill artifact manifest
• rust binary skill scaffold, build, and run
• uv-backed Python skill scaffold, sync, and run
• stdio JSON skill protocol enforcement
• artifact path validation

Must Not:

• own agent planning
• parse @skill mentions
• render UI
• own durable chat or task state
• manage provider credentials

Depends On:

• serde_json

Verify:

• cargo test -p runtime

server

Language: rust Path: crates/server

Server owns the product ingress boundary.

Owns:

• CoreCommand transport contract
• JSON command decoding and response encoding
• local in-process core endpoint
• shell/API/MCP-facing dispatch shape

Must Not:

• render UI
• own durable storage tables
• implement provider/model logic
• bypass CoreCommand/CoreResponse

Depends On:

• engine
• proto

Verify:

• cargo check -p server

skill

Language: rust Path: crates/skill

Skill owns skill metadata and AI-facing context resolution.

Owns:

• skill catalog
• skill repository loading
• skill source metadata
• skill source references
• @skill mention parsing
• SkillContext resolution
• suggested tool metadata

Must Not:

• render UI overlays
• write session history
• decide tool permissions
• execute tools directly
• own durable Task or Run state

Depends On:

• store

Verify:

• cargo check -p skill

skrun-native

Language: rust Path: crates/py

Py owns the PyO3 module boundary for the core.

Owns:

• skrun_native Python module
• CoreCommand/CoreResponse JSON ABI entrypoint
• executable skill runtime JSON ABI entrypoints
• Python-to-Rust error conversion
• module-local Core state for prototype bindings

Must Not:

• duplicate core business logic in Python
• expose database internals
• render UI

Depends On:

• engine
• server
• model
• runtime

Verify:

• cargo check -p skrun-native

store

Language: rust Path: crates/store

Store owns backend-neutral repository contracts.

Owns:

• Repository trait
• memory repository
• redb repository adapter
• get/list/put/delete repository contract
• backend abstraction boundary

Must Not:

• own business decisions
• expose backend handles to runtime modules
• store UI overlay state

Verify:

• cargo check -p store

tool

Language: rust Path: crates/tool

Tool owns the callable tool contract and registry.

Owns:

• Tool trait
• Registry
• tool specs
• tool lookup
• tool call boundary

Must Not:

• decide per-turn permissions alone
• own agent loop state
• write durable run state

Verify:

• cargo check -p tool