Workspace Initialization

Running toporic init bootstraps a new project workspace. You can do this from the CLI or from within the TUI.

From the CLI:

toporic init
toporic init --workspace /path/to/project

From the TUI:

/init

What it creates

.toporic/
├── config.json       ← project-level config defaults
├── skills/           ← place your project-local skill files here
├── tasks/            ← task list managed by the agent
├── data/             ← vector store and embedding cache
└── logs/             ← rotating debug logs
AGENTS.md             ← project instructions read by the agent on every turn

The operation is idempotent — running toporic init on an existing workspace reports what already exists without overwriting anything. It also runs git init if the directory isn’t already a Git repository.

If Toporic detects that .toporic/ doesn’t exist when it starts, it shows a one-time hint:

Workspace not initialized. Run /init to set up .toporic/ and AGENTS.md.

AGENTS.md

AGENTS.md is a Markdown file at the project root that the agent reads on every turn. Use it to give the agent project-specific instructions, conventions, and context — similar to a CONTRIBUTING.md but written for the AI.

Example:

# Project Instructions

- This is a Rust workspace using Cargo workspaces.
- Always run `cargo clippy` and `cargo test` after making changes.
- Follow the error handling conventions in `crates/toporic-harness/src/`.
- Do not modify generated files in `target/`.

For more advanced per-workflow instructions, see Skills.