xonecas.io
64875
Mc

mini-coder / commit e682a8b

Add orc agent, mini-coder skill; add homeDir param to config loaders for test isolation

- Add .agents/agents/orc.md: orchestrator agent that decomposes tasks and delegates to subagents
- Add .agents/skills/mini-coder/SKILL.md: architecture reference skill for the codebase
- Add mode: subagent to writer agent frontmatter
- Add optional homeDir param to loadMarkdownConfigs, loadAgents, loadCustomCommands, loadSkills so tests can override the global config directory without touching the real ~/.agents
- Update tests to pass dir as homeDir for full isolation
- Clean up completed TODO items

xonecas2026-03-10 e682a8bb8e89410adfff45f7a6f96449c8805d4a parent a182717

10 files changed

.agents/agents/orc.md+36−0
@@ -0,0 +1,36 @@
1+---
2+description: Orchestrator — decomposes complex tasks and coordinates a fleet of subagents
3+mode: primary
4+---
5+
6+You are **Orc**, an expert orchestration agent. Your superpower is breaking complex problems into well-scoped subtasks and delegating each to the right specialist subagent via the `subagent` tool.
7+
8+## Core principles
9+
10+- **Decompose first.** Before using any tool, think about the full shape of the task. Identify subtasks that are independent and self-contained — those are candidates for delegation.
11+- **Delegate aggressively.** Prefer spawning a focused subagent over doing broad work yourself. Each subagent gets a single, precise goal.
12+- **Stay the coordinator.** You own the big picture. Subagents handle the details. Synthesise their results, resolve conflicts, and report back clearly.
13+- **Parallelise when possible.** If two subtasks don't depend on each other, dispatch them concurrently.
14+- **Fail fast.** If a subagent reports failure or returns unexpected output, stop and reassess before continuing.
15+
16+## How to orchestrate
17+
18+1. Read the user's goal carefully.
19+2. Identify the 2–5 discrete subtasks needed to complete it.
20+3. Write a tight, self-contained prompt for each — include all context the subagent needs; it has no shared memory with you.
21+4. Dispatch subagents (in parallel where safe) and capture their outputs.
22+5. Synthesise results. If something is missing or wrong, spawn a follow-up subagent to fix it.
23+6. Report the final outcome clearly to the user.
24+
25+## Subagent prompt hygiene
26+
27+- Be explicit about _what the subagent should produce_ (a file, a code change, a summary, a decision).
28+- Include relevant paths, constraints, and acceptance criteria in every prompt.
29+- Never give a vague brief — ambiguity leads to rework and wasted tokens.
30+- Prefer named agents (e.g. `writer`) when one fits the task.
31+
32+## When NOT to delegate
33+
34+- Trivial lookups or single-file reads: do them directly with your own tools.
35+- Tasks that require continuous back-and-forth with the user: handle interactively.
36+- Secret or credential-sensitive work: handle yourself; never expose secrets in subagent prompts.
.agents/agents/writer.md+1−0
@@ -1,5 +1,6 @@
11 ---
22 description: Write short prose in a personal, informal style from topics or resources
3+mode: subagent
34 model: zen/claude-sonnet-4-6
45 ---
56
.agents/skills/mini-coder/SKILL.md+62−0
@@ -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.
TODO.md+0−11
@@ -70,17 +70,6 @@ error: script "dev" exited with code 1
7070
7171 ---
7272
73-## Custom commands vs built-in commands
74-
75-Let's clean things up:
76-
77-- `/review` command should use the same code as a custom-commands, consolidate the two. We can create the global `/review` command in `~/.agents/commands` at app start if it doesn't exist. That way it can be a pure custom command and the users are encouraged to edit it for their own custom reviews. Never overwrite the file if it exists. Print a line notifying the user that the command was created.
78-- Ensure we are correctly implementing commands, skills and agents. Use the claude code and opencode documentation online to audit our implementations, identify gaps and inconsistencies. We should support both of these types of configs, as well as our .agents.
79-- Now that we have subagents as subprocesses, let's review how it impacted these features.
80-- We are missing the notion of an active custom agent, we need to add it. It should be documented in the claude code and opencode docs.
81-
82----
83-
8473 ## LSP Diagnostics (not very important, with tool-hooks and strong linting, this is not as necessary, but we should implement asap)
8574
8675 We should have a closed loop feedback for LSP diagnostics on edits/reads.
src/cli/agents.ts+5−1
@@ -21,11 +21,15 @@ export interface AgentConfig {
2121
2222 // ─── Load all agents (global + local, local wins) ─────────────────────────────
2323
24-export function loadAgents(cwd: string): Map<string, AgentConfig> {
24+export function loadAgents(
25+ cwd: string,
26+ homeDir?: string,
27+): Map<string, AgentConfig> {
2528 return loadMarkdownConfigs<AgentConfig>({
2629 type: "agents",
2730 strategy: "flat",
2831 cwd,
32+ homeDir,
2933 includeClaudeDirs: true,
3034 mapConfig: ({ name, meta, body, source }) => ({
3135 ...baseConfigFields(name, meta, source),
src/cli/custom-commands.test.ts+2−2
@@ -24,7 +24,7 @@ describe("loadCustomCommands", () => {
2424 }
2525
2626 test("returns empty map when no .agents/commands dir exists", () => {
27- const result = loadCustomCommands(dir);
27+ const result = loadCustomCommands(dir, dir);
2828 expect(result.size).toBe(0);
2929 });
3030
@@ -59,7 +59,7 @@ describe("loadCustomCommands", () => {
5959 const cmdsDir = join(dir, ".agents", "commands");
6060 mkdirSync(cmdsDir, { recursive: true });
6161 writeFileSync(join(cmdsDir, "script.sh"), "echo hi");
62- expect(loadCustomCommands(dir).size).toBe(0);
62+ expect(loadCustomCommands(dir, dir).size).toBe(0);
6363 });
6464
6565 test("local command overrides global with same name", () => {
src/cli/custom-commands.ts+5−1
@@ -20,11 +20,15 @@ export interface CustomCommand {
2020
2121 // ─── Load all custom commands (global + local, local wins) ───────────────────
2222
23-export function loadCustomCommands(cwd: string): Map<string, CustomCommand> {
23+export function loadCustomCommands(
24+ cwd: string,
25+ homeDir?: string,
26+): Map<string, CustomCommand> {
2427 return loadMarkdownConfigs<CustomCommand>({
2528 type: "commands",
2629 strategy: "flat",
2730 cwd,
31+ homeDir,
2832 includeClaudeDirs: true,
2933 mapConfig: ({ name, meta, body, source }) => ({
3034 ...baseConfigFields(name, meta, source),
src/cli/load-markdown-configs.test.ts+4−0
@@ -37,6 +37,7 @@ describe("loadMarkdownConfigs", () => {
3737 type: "commands",
3838 strategy: "flat",
3939 cwd: dir,
40+ homeDir: dir,
4041 includeClaudeDirs: false,
4142 mapConfig: ({ body, source }) => ({ body, source }),
4243 });
@@ -53,6 +54,7 @@ describe("loadMarkdownConfigs", () => {
5354 type: "commands",
5455 strategy: "flat",
5556 cwd: dir,
57+ homeDir: dir,
5658 includeClaudeDirs: true,
5759 mapConfig: ({ body, source }) => ({ body, source }),
5860 });
@@ -73,6 +75,7 @@ describe("loadMarkdownConfigs", () => {
7375 strategy: "nested",
7476 nestedFileName: "SKILL.md",
7577 cwd: dir,
78+ homeDir: dir,
7679 includeClaudeDirs: false,
7780 mapConfig: ({ name, body, source }) => ({ name, body, source }),
7881 });
@@ -95,6 +98,7 @@ describe("loadMarkdownConfigs", () => {
9598 type: "commands",
9699 strategy: "flat",
97100 cwd: dir,
101+ homeDir: dir,
98102 includeClaudeDirs: false,
99103 mapConfig: ({ body }) => body,
100104 });
src/cli/load-markdown-configs.ts+15−5
@@ -35,13 +35,23 @@ interface MarkdownConfigLoaderOptions<T> {
3535 /** Whether to include `.claude` fallback dirs */
3636 includeClaudeDirs: boolean;
3737 cwd: string;
38+ /** Override home directory — used in tests to isolate global config loading. */
39+ homeDir: string | undefined;
3840 }
3941
4042 export function loadMarkdownConfigs<T>(
4143 opts: MarkdownConfigLoaderOptions<T>,
4244 ): Map<string, T> {
43- const { type, strategy, nestedFileName, mapConfig, includeClaudeDirs, cwd } =
44- opts;
45+ const {
46+ type,
47+ strategy,
48+ nestedFileName,
49+ mapConfig,
50+ includeClaudeDirs,
51+ cwd,
52+ homeDir: homeOverride,
53+ } = opts;
54+ const home = homeOverride ?? homedir();
4555
4656 function loadFromDir(
4757 dir: string,
@@ -97,7 +107,7 @@ export function loadMarkdownConfigs<T>(
97107 }
98108
99109 if (!includeClaudeDirs) {
100- const globalAgentsDir = join(homedir(), ".agents", type);
110+ const globalAgentsDir = join(home, ".agents", type);
101111 const localAgentsDir = join(cwd, ".agents", type);
102112
103113 const globalAgents = loadFromDir(globalAgentsDir, "global");
@@ -106,8 +116,8 @@ export function loadMarkdownConfigs<T>(
106116 return new Map([...globalAgents, ...localAgents]);
107117 }
108118
109- const globalAgentsDir = join(homedir(), ".agents", type);
110- const globalClaudeDir = join(homedir(), ".claude", type);
119+ const globalAgentsDir = join(home, ".agents", type);
120+ const globalClaudeDir = join(home, ".claude", type);
111121 const localAgentsDir = join(cwd, ".agents", type);
112122 const localClaudeDir = join(cwd, ".claude", type);
113123
src/cli/skills.ts+2−1
@@ -13,12 +13,13 @@ interface Skill {
1313
1414 // ─── Load all skills (global + local, local wins) ────────────────────────────
1515
16-export function loadSkills(cwd: string): Map<string, Skill> {
16+export function loadSkills(cwd: string, homeDir?: string): Map<string, Skill> {
1717 return loadMarkdownConfigs<Skill>({
1818 type: "skills",
1919 strategy: "nested",
2020 nestedFileName: "SKILL.md",
2121 cwd,
22+ homeDir,
2223 includeClaudeDirs: true,
2324 mapConfig: ({ name, meta, raw, source }) => ({
2425 name,