xonecas.io
64875
Mc

mini-coder / commit 0d5e7e3

docs: audit and fix docs, agents, and skill accuracy

xonecas2026-03-10 0d5e7e373f2a5d005f68cbed76c05e565acbcb38 parent 38c152e

12 files changed

.agents/commands/n8n-blog-post.md+2−0
@@ -1,8 +1,10 @@
11 ---
22 description: Trigger the n8n workflow to create a blog post using title and content as seeds.
33 model: zen/claude-haiku-4-5
4+context: fork
45 ---
56
7+
68 Arguments: $ARGUMENTS
79
810 Make a GET cURL request to the URL in the `$N8N_BLOG_WEBHOOK_URL` env var with query string params `title` and `content`. Pass the values exactly as given — do not expand or rewrite the content.
.agents/commands/release.md+1−0
@@ -2,6 +2,7 @@
22 description: Create a new tagged npm release (patch/minor/major)
33 ---
44
5+
56 Create a new npm release for this repo. The bump type is: $1 (default to "patch" if not provided).
67
78 Steps to follow exactly:
.agents/commands/search.md+2−0
@@ -1,8 +1,10 @@
11 ---
22 description: Search the codebase for a topic using a subagent
33 model: zen/claude-haiku-4-5
4+context: fork
45 ---
56
7+
68 Search the codebase for: $ARGUMENTS
79
810 Use glob, grep, and read tools to explore thoroughly. Report:
.agents/skills/mini-coder/SKILL.md+6−3
@@ -32,10 +32,12 @@ All config lives under `.agents/` (or `~/.agents/` globally). Local wins over gl
3232 ### Frontmatter fields
3333
3434 - `description` — shown in `/help` and agent/skill listings
35-- `model` — override the LLM model for this config
35+- `model` — override the LLM model for this config (commands: only used when `context: fork`)
3636 - `mode` — `primary` / `subagent` / `all` (agents only; default: `subagent`)
37-- `agent` — run command under a named agent's system prompt (commands only)
37+- `agent` — run command under a named agent's system prompt (commands: only used when `context: fork`)
3838 - `name` — override the key name (nested skills only; defaults to folder name)
39+- `context` — `fork` to run command as isolated subagent; default is inline in current conversation (commands only; Claude Code standard)
40+- `subtask` — `true` to force subagent invocation (commands only; OpenCode compat, equivalent to `context: fork`)
3941
4042 ### Agent modes
4143
@@ -47,7 +49,8 @@ All config lives under `.agents/` (or `~/.agents/` globally). Local wins over gl
4749
4850 Every tool is declared in `src/agent/tools.ts`. Core tools: `read`, `glob`, `grep`, `replace`, `insert`, `create`, `shell`, `subagent`, `webSearch`, `webContent`.
4951
50-Hooks in `.agents/hooks/` fire after `create`, `insert`, and `replace` — currently used to auto-format changed files.
52+Hooks in `.agents/hooks/` fire after any of the 7 hookable tools: `glob`, `grep`, `read`, `create`, `replace`, `insert`, `shell`. The repo currently uses `post-create`, `post-insert`, and `post-replace` to auto-format changed files.
53+
5154
5255 ## Testing
5356
README.md+4−2
@@ -56,7 +56,8 @@ Need more firepower? I connect to **MCP servers** over HTTP or stdio — bolt on
5656 - **Built-in web search** — set `EXA_API_KEY` and I expose `webSearch` + `webContent` tools.
5757 - **Session memory** — conversations are saved in a local SQLite database. Resume where you left off with `-c` or pick a specific session with `-r <id>`.
5858 - **Shell integration** — prefix with `!` to run shell commands inline. Use `@` to reference files in your prompt (with Tab completion).
59-- **Slash commands** — `/model` or `/models` to list/switch models, `/model effort <low|medium|high|xhigh|off>` for reasoning effort, `/plan` for read-only thinking mode, `/ralph` for autonomous looping, `/review` for a code review, `/undo` to roll back a turn, `/new` for a clean session, `/mcp list|add|remove` to manage MCP servers, and `/exit` (`/quit`, `/q`) to leave. See all with `/help`.
59+- **Slash commands** — `/model` or `/models` to list/switch models, `/model effort <low|medium|high|xhigh|off>` for reasoning effort, `/plan` for read-only thinking mode, `/ralph` for autonomous looping, `/review` for a code review (global custom command, auto-created at `~/.agents/commands/review.md`), `/agent [name]` to set or clear an active primary agent, `/undo` to roll back a turn, `/new` for a clean session, `/mcp list|add|remove` to manage MCP servers, and `/exit` (`/quit`, `/q`) to le …
60+
6061 - **Custom commands** — drop a `.md` file in `.agents/commands/` and it becomes a `/command`. Claude-compatible `.claude/commands/` works too. Supports argument placeholders (`$ARGUMENTS`, `$1`…`$9`) and shell interpolation (`` !`cmd` ``). Global commands live in `~/.agents/commands/` and `~/.claude/commands/`. Custom commands take precedence over built-ins. → [docs/custom-commands.md](docs/custom-commands.md)
6162 - **Custom agents** — drop a `.md` file in `.agents/agents/` (or `~/.agents/agents/` globally) and reference it with `@agent-name` in your prompt. The agent runs in its own context window with a custom system prompt and optional model override. → [docs/custom-agents.md](docs/custom-agents.md)
6263 - **Skills** — place a `SKILL.md` in `.agents/skills/<name>/` and inject it into any prompt with `@skill-name`. Claude-compatible `.claude/skills/<name>/SKILL.md` works too. Skills are _never_ auto-loaded — always explicit. → [docs/skills.md](docs/skills.md)
@@ -90,7 +91,8 @@ I follow the [`.agents` convention](https://github.com/agentsmd/agents) — the
9091 | `.agents/hooks/post-<tool>` | Scripts run after supported built-in tool calls |
9192 | `AGENTS.md` | Project context injected into every system prompt |
9293 | `CLAUDE.md` | Fallback project context if `AGENTS.md` is absent |
93-| `~/.config/mini-coder/AGENTS.md` | Global fallback context |
94+| `~/.agents/AGENTS.md` | Global fallback context |
95+
9496
9597 The pecking order is straightforward: local beats global, and `.agents` beats `.claude` at the same scope. Worth noting: custom agents are mini-coder-only — `.claude` compatibility is for commands and skills only. → [docs/configs.md](docs/configs.md)
9698
docs/custom-agents.md+2−0
@@ -46,6 +46,8 @@ into the conversation.
4646 |---|---|---|
4747 | `description` | No | Shown in `/help`. Defaults to filename. |
4848 | `model` | No | Override the active model for this agent. |
49+| `mode` | No | `primary` — interactive only (via `/agent <name>`); `subagent` — callable via the `subagent` tool only (default); `all` — both. |
50+
4951
5052 The markdown body (after frontmatter) is the agent's system prompt.
5153
docs/custom-commands.md+16−6
@@ -20,7 +20,8 @@ Create a markdown file. The filename becomes the command name.
2020 ```md
2121 ---
2222 description: Summarise what changed since yesterday
23-model: zen/claude-3-5-haiku
23+model: zen/claude-haiku-4-5
24+
2425 ---
2526
2627 Run `!`git log --oneline --since=yesterday`` and summarise the changes
@@ -38,7 +39,11 @@ Then in the REPL:
3839 | Field | Required | Description |
3940 |---|---|---|
4041 | `description` | No | Shown in `/help`. Defaults to the command name. |
41-| `model` | No | Override the active model for this command (subagent execution). |
42+| `model` | No | Override the active model for this command (only applies when `context: fork`). |
43+| `context` | No | Set to `fork` to run the command as an isolated subagent; default runs inline. |
44+| `subtask` | No | Set to `true` to force subagent execution (OpenCode-compatible alias for `context: fork`). |
45+| `agent` | No | Run the command under a named agent's system prompt (only applies when `context: fork`). |
46+
4247
4348
4449 ## Arguments
@@ -50,7 +55,8 @@ Use `$ARGUMENTS` for the full argument string, or `$1`, `$2`, … `$9` for indiv
5055 ```md
5156 ---
5257 description: Search the codebase for a topic
53-model: zen/claude-3-5-haiku
58+model: zen/claude-haiku-4-5
59+
5460 ---
5561
5662 Search the codebase for: $ARGUMENTS
@@ -110,7 +116,8 @@ lightweight tasks regardless of what the session is currently set to.
110116 ```md
111117 ---
112118 description: Quick grep for a symbol
113-model: zen/claude-3-5-haiku
119+model: zen/claude-haiku-4-5
120+
114121 ---
115122
116123 Find all usages of $ARGUMENTS across the codebase using grep and glob.
@@ -122,8 +129,11 @@ Large models for deep analysis, small models for search and lookup.
122129
123130 ## Precedence
124131
125-Custom commands shadow built-ins. If you create `.agents/commands/review.md`
126-it will replace the built-in `/review` for that project.
132+Custom commands shadow built-ins. If you create `.agents/commands/plan.md`
133+it will replace the built-in `/plan` for that project. The global `/review`
134+command (auto-created at `~/.agents/commands/review.md` on first run) works
135+the same way — a local `.agents/commands/review.md` will override it.
136+
127137
128138 ## Listing commands
129139
src/cli/commands.ts+9−0
@@ -356,6 +356,15 @@ async function handleCustomCommand(
356356 const src = c.dim(`[${srcPath}]`);
357357 writeln(`${PREFIX.info} ${label} ${src}`);
358358 writeln();
359+
360+ // context: fork (Claude Code) or subtask: true (OpenCode) → isolated subagent.
361+ // Default: run inline in the current conversation.
362+ const fork = cmd.context === "fork" || cmd.subtask === true;
363+
364+ if (!fork) {
365+ return { type: "inject-user-message", text: prompt };
366+ }
367+
359368 try {
360369 const output = await ctx.runSubagent(prompt, cmd.agent, cmd.model);
361370 assertSubagentMerged(output);
src/cli/custom-commands.test.ts+70−0
@@ -69,6 +69,29 @@ describe("loadCustomCommands", () => {
6969 expect(result.get("search")?.description).toBe("local");
7070 expect(result.get("search")?.source).toBe("local");
7171 });
72+
73+ test("loads context: fork from frontmatter", () => {
74+ writeCmd(
75+ dir,
76+ "deploy",
77+ "---\ndescription: Deploy\ncontext: fork\n---\n\nDeploy it",
78+ );
79+ expect(loadCustomCommands(dir).get("deploy")?.context).toBe("fork");
80+ });
81+
82+ test("context is undefined when not specified", () => {
83+ writeCmd(dir, "plain", "---\ndescription: Plain\n---\n\nDo it");
84+ expect(loadCustomCommands(dir).get("plain")?.context).toBeUndefined();
85+ });
86+
87+ test("loads subtask: true from frontmatter", () => {
88+ writeCmd(
89+ dir,
90+ "analyze",
91+ "---\ndescription: Analyze\nsubtask: true\n---\n\nAnalyze it",
92+ );
93+ expect(loadCustomCommands(dir).get("analyze")?.subtask).toBe(true);
94+ });
7295 });
7396
7497 // ─── expandTemplate ───────────────────────────────────────────────────────────
@@ -147,3 +170,50 @@ describe("expandTemplate", () => {
147170 expect(out).toBe("plain text");
148171 });
149172 });
173+
174+// ─── @file reference expansion ───────────────────────────────────────────────
175+
176+describe("expandTemplate @file references", () => {
177+ let dir: string;
178+
179+ beforeEach(() => {
180+ dir = mkdtempSync(join(tmpdir(), "mc-fileref-test-"));
181+ });
182+
183+ afterEach(() => {
184+ rmSync(dir, { recursive: true, force: true });
185+ });
186+
187+ test("replaces @file with code-fenced content", async () => {
188+ writeFileSync(join(dir, "hello.txt"), "world");
189+ const out = await expandTemplate("see @hello.txt for details", "", dir);
190+ expect(out).toBe("see `hello.txt`:\n```\nworld\n``` for details");
191+ });
192+
193+ test("leaves @token unchanged when file does not exist", async () => {
194+ const out = await expandTemplate("@nonexistent.ts", "", dir);
195+ expect(out).toBe("@nonexistent.ts");
196+ });
197+
198+ test("handles nested path like @src/foo.ts", async () => {
199+ mkdirSync(join(dir, "src"), { recursive: true });
200+ writeFileSync(join(dir, "src", "foo.ts"), "export const x = 1;");
201+ const out = await expandTemplate("review @src/foo.ts please", "", dir);
202+ expect(out).toBe(
203+ "review `src/foo.ts`:\n```\nexport const x = 1;\n``` please",
204+ );
205+ });
206+
207+ test("non-file @tokens (e.g. email) are left intact", async () => {
208+ // no file named "user@example.com" or "example.com" exists in cwd
209+ const out = await expandTemplate("contact user@example.com", "", dir);
210+ expect(out).toBe("contact user@example.com");
211+ });
212+
213+ test("multiple @file refs in one template are all replaced", async () => {
214+ writeFileSync(join(dir, "a.md"), "AAA");
215+ writeFileSync(join(dir, "b.md"), "BBB");
216+ const out = await expandTemplate("@a.md and @b.md", "", dir);
217+ expect(out).toBe("`a.md`:\n```\nAAA\n``` and `b.md`:\n```\nBBB\n```");
218+ });
219+});
src/cli/custom-commands.ts+35−2
@@ -1,5 +1,7 @@
11 // ─── Types ────────────────────────────────────────────────────────────────────
22
3+import { existsSync, readFileSync } from "node:fs";
4+import { join } from "node:path";
35 import {
46 baseConfigFields,
57 loadMarkdownConfigs,
@@ -8,10 +10,17 @@ import {
810 export interface CustomCommand {
911 name: string;
1012 description: string;
11- /** Override model for this command (optional) */
13+ /** Override model for this command (only applies when running as a subagent) */
1214 model?: string;
13- /** Run command under a specific agent's system prompt (optional) */
15+ /** Run command under a specific agent's system prompt (only applies when running as a subagent) */
1416 agent?: string;
17+ /**
18+ * Claude Code: `"fork"` runs the command in an isolated subagent context.
19+ * Default (omitted) runs inline in the current conversation.
20+ */
21+ context?: "fork";
22+ /** OpenCode: equivalent to `context: "fork"` — forces subagent invocation */
23+ subtask?: boolean;
1524 /** Raw template string (after frontmatter is stripped) */
1625 template: string;
1726 /** "global" (~/.agents/) or "local" (./.agents/) — local wins on conflict */
@@ -33,6 +42,8 @@ export function loadCustomCommands(
3342 mapConfig: ({ name, meta, body, source }) => ({
3443 ...baseConfigFields(name, meta, source),
3544 ...(meta.agent ? { agent: meta.agent } : {}),
45+ ...(meta.context === "fork" ? { context: "fork" as const } : {}),
46+ ...(meta.subtask ? { subtask: true } : {}),
3647 template: body,
3748 }),
3849 });
@@ -44,6 +55,7 @@ export function loadCustomCommands(
4455 * - `$ARGUMENTS` → full args string
4556 * - `$1`, `$2`, … → positional tokens
4657 * - `!`cmd`` → stdout of running cmd in a shell
58+ * - `@<filepath>` → contents of the file (relative to cwd), wrapped in a code fence
4759 */
4860 export async function expandTemplate(
4961 template: string,
@@ -104,5 +116,26 @@ export async function expandTemplate(
104116 result = result.replaceAll(match[0], output);
105117 }
106118
119+ // Replace @file references — resolve relative to cwd, wrap in code fence.
120+ // Matches @<path> where path is a non-whitespace sequence; silently skips
121+ // tokens that don't resolve to an existing file (e.g. email addresses).
122+ const FILE_REF_RE = /@([^\s,;!?'")\]]+)/g;
123+ const fileMatches = [...result.matchAll(FILE_REF_RE)];
124+ for (const match of fileMatches) {
125+ const filePath = match[1] ?? "";
126+ const fullPath = join(cwd, filePath);
127+ if (!existsSync(fullPath)) continue;
128+ let content = "";
129+ try {
130+ content = readFileSync(fullPath, "utf-8");
131+ } catch {
132+ continue;
133+ }
134+ result = result.replaceAll(
135+ match[0],
136+ `\`${filePath}\`:\n\`\`\`\n${content}\n\`\`\``,
137+ );
138+ }
139+
107140 return result;
108141 }
src/cli/frontmatter.test.ts+20−0
@@ -69,4 +69,24 @@ describe("parseFrontmatter", () => {
6969 "---\ndescription: Run tests\nagent: build\n---\n\nRun npm test";
7070 expect(parseFrontmatter(raw).meta.agent).toBe("build");
7171 });
72+
73+ test("parses context: fork", () => {
74+ const raw = "---\ndescription: Deploy\ncontext: fork\n---\n\nDeploy it";
75+ expect(parseFrontmatter(raw).meta.context).toBe("fork");
76+ });
77+
78+ test("ignores unknown context values", () => {
79+ const raw = "---\ncontext: inline\n---\n\nBody";
80+ expect(parseFrontmatter(raw).meta.context).toBeUndefined();
81+ });
82+
83+ test("parses subtask: true", () => {
84+ const raw = "---\nsubtask: true\n---\n\nBody";
85+ expect(parseFrontmatter(raw).meta.subtask).toBe(true);
86+ });
87+
88+ test("parses subtask: false", () => {
89+ const raw = "---\nsubtask: false\n---\n\nBody";
90+ expect(parseFrontmatter(raw).meta.subtask).toBe(false);
91+ });
7292 });
src/cli/frontmatter.ts+6−0
@@ -8,6 +8,10 @@ export interface Frontmatter {
88 mode?: "primary" | "subagent" | "all";
99 /** For commands: name of the agent to run the command under */
1010 agent?: string;
11+ /** Claude Code: run command in an isolated subagent context instead of inline */
12+ context?: "fork";
13+ /** OpenCode: force subagent invocation (equivalent to context: fork) */
14+ subtask?: boolean;
1115 }
1216
1317 const FM_RE = /^---\r?\n([\s\S]*?)\r?\n---\r?\n?([\s\S]*)$/;
@@ -38,6 +42,8 @@ export function parseFrontmatter(raw: string): {
3842 )
3943 meta.mode = val;
4044 if (key === "agent") meta.agent = val;
45+ if (key === "context" && val === "fork") meta.context = "fork";
46+ if (key === "subtask") meta.subtask = val === "true";
4147 }
4248
4349 return { meta, body: (m[2] ?? "").trim() };