@@ -0,0 +1,62 @@
1+---
2+name: mini-coder
3+description: Architecture and conventions for the mini-coder codebase
4+---
5+
6+# mini-coder
7+
8+mini-coder is a small, fast CLI coding agent built with Bun and TypeScript.
9+
10+## Key source paths
11+
12+| Path | Purpose |
13+|------|---------|
14+| `src/agent/` | Core agent loop, session runner, subagent runner, system prompt builder |
15+| `src/cli/` | CLI commands, custom commands, agents/skills loaders, input/output rendering |
16+| `src/llm-api/` | Provider abstraction, turn streaming, model metadata |
17+| `src/tools/` | All tools (read, replace, insert, create, glob, grep, shell, subagent, exa, …) |
18+| `src/session/` | Session manager and SQLite DB repositories |
19+| `src/mcp/` | MCP client integration |
20+| `.agents/` | Local config: agents, commands, skills, hooks |
21+
22+## Config system
23+
24+All config lives under `.agents/` (or `~/.agents/` globally). Local wins over global; within the same scope, `.agents/` wins over `.claude/`.
25+
26+| Type | Path | Strategy |
27+|------|------|----------|
28+| Agents | `.agents/agents/<name>.md` | flat — one `.md` per agent |
29+| Commands | `.agents/commands/<name>.md` | flat — one `.md` per command |
30+| Skills | `.agents/skills/<name>/SKILL.md` | nested — one directory per skill |
31+
32+### Frontmatter fields
33+
34+- `description` — shown in `/help` and agent/skill listings
35+- `model` — override the LLM model for this config
36+- `mode` — `primary` / `subagent` / `all` (agents only; default: `subagent`)
37+- `agent` — run command under a named agent's system prompt (commands only)
38+- `name` — override the key name (nested skills only; defaults to folder name)
39+
40+### Agent modes
41+
42+- `primary` — activated interactively via `/agent <name>` in the CLI
43+- `subagent` — callable via the `subagent` tool (the default when `mode` is omitted)
44+- `all` — available in both contexts
45+
46+## Tools
47+
48+Every tool is declared in `src/agent/tools.ts`. Core tools: `read`, `glob`, `grep`, `replace`, `insert`, `create`, `shell`, `subagent`, `webSearch`, `webContent`.
49+
50+Hooks in `.agents/hooks/` fire after `create`, `insert`, and `replace` — currently used to auto-format changed files.
51+
52+## Testing
53+
54+```
55+bun run jscpd && bun run knip && bun run typecheck && bun run format && bun run lint && bun test
56+```
57+
58+Tests are `*.test.ts` files co-located with source. Write minimal tests focused on our own logic — no mocks, no stubs, no mock servers.
59+
60+## Data
61+
62+App data: `~/.config/mini-coder/` — SQLite DB for sessions, model info, MCP servers, and settings.