mini-coder 0.0.4 → 0.0.6

package/docs/configs.md

@@ -0,0 +1,77 @@
+# Config conventions
+
+mini-coder supports both its native `.agents` convention and Claude Code's `.claude` convention for commands and skills.
+
+## Supported config roots
+
+| Root | Purpose |
+|---|---|
+| `.agents/` | mini-coder native config |
+| `.claude/` | Claude Code-compatible commands/skills |
+
+Each root can exist in:
+
+- **Local (repo):** `./.agents`, `./.claude`
+- **Global (home):** `~/.agents`, `~/.claude`
+
+## Commands
+
+Supported locations:
+
+- `./.agents/commands/*.md`
+- `~/.agents/commands/*.md`
+- `./.claude/commands/*.md`
+- `~/.claude/commands/*.md`
+
+Format:
+
+```md
+---
+description: Optional help text
+model: optional/model-override
+---
+
+Prompt template body with $ARGUMENTS and $1..$9 support.
+```
+
+Filename becomes the command name (`review.md` => `/review`).
+
+## Skills
+
+Supported locations:
+
+- `./.agents/skills/<skill-name>/SKILL.md`
+- `~/.agents/skills/<skill-name>/SKILL.md`
+- `./.claude/skills/<skill-name>/SKILL.md`
+- `~/.claude/skills/<skill-name>/SKILL.md`
+
+Format:
+
+```md
+---
+name: optional-skill-name
+description: Optional help text
+---
+
+Skill instructions/content.
+```
+
+If `name` is omitted, folder name is used.
+
+## Agents (mini-coder specific)
+
+Custom subagents are configured in `.agents`:
+
+- `./.agents/agents/*.md`
+- `~/.agents/agents/*.md`
+
+(There is no `.claude` compatibility path for agents.)
+
+## Precedence and conflicts
+
+Precedence rules:
+
+1. **Local overrides global**
+2. At the **same scope** (both local or both global), if `.agents` and `.claude` define the same command/skill name, **`.agents` wins**
+
+When same-scope conflicts are detected for commands/skills, mini-coder prints a warning and uses the `.agents` version.

package/docs/custom-agents.md

@@ -0,0 +1,70 @@
+# Custom Agents
+
+An agent is a subagent with a custom system prompt and optional model override.
+Use `@agent-name` anywhere in your prompt to route the message through it.
+
+## Where to put them
+
+| Location | Scope |
+|---|---|
+| `.agents/agents/*.md` | Current repo only |
+| `~/.agents/agents/*.md` | All projects (global) |
+
+Local agents override global ones with the same name.
+
+## Create an agent
+
+The filename becomes the agent name.
+
+`~/.agents/agents/reviewer.md`:
+
+```md
+---
+description: Strict code reviewer focused on bugs and structure
+model: zen/claude-sonnet-4-6
+---
+
+You are a senior engineer doing a code review. Be direct and specific.
+Cite file and line number for every finding. Flag bugs first, then
+structure issues, then style — only if they violate project conventions.
+No flattery. End with a one-line verdict.
+```
+
+Then in the REPL:
+
+```
+@reviewer review the auth module for race conditions
+```
+
+The rest of the message (everything except the `@reviewer` token) becomes
+the prompt. The agent runs in its own context window and returns its output
+into the conversation.
+
+## Frontmatter fields
+
+| Field | Required | Description |
+|---|---|---|
+| `description` | No | Shown in `/help`. Defaults to filename. |
+| `model` | No | Override the active model for this agent. |
+
+The markdown body (after frontmatter) is the agent's system prompt.
+
+## Combining with files
+
+`@file` references are resolved before the agent fires:
+
+```
+@reviewer @src/auth/session.ts check this file for issues
+```
+
+## Tab completion
+
+Type `@` and press `Tab` to autocomplete agent names alongside files.
+
+## Listing agents
+
+```
+/help
+```
+
+Agents are listed in magenta, tagged `(local)` or `(global)`.

package/docs/custom-commands.md

@@ -0,0 +1,133 @@
+# Custom Commands
+
+Custom commands let you define reusable prompts that run as `/command` in the mini-coder REPL.
+
+## Where to put them
+
+| Location | Scope |
+|---|---|
+| `.agents/commands/*.md` | Current repo only |
+| `~/.agents/commands/*.md` | All projects (global) |
+
+Local commands override global ones with the same name.
+
+## Create a command
+
+Create a markdown file. The filename becomes the command name.
+
+`.agents/commands/standup.md`:
+
+```md
+---
+description: Summarise what changed since yesterday
+model: zen/claude-3-5-haiku
+---
+
+Run `!`git log --oneline --since=yesterday`` and summarise the changes
+as a short standup update. Group by theme, skip merge commits.
+```
+
+Then in the REPL:
+
+```
+/standup
+```
+
+## Frontmatter fields
+
+| Field | Required | Description |
+|---|---|---|
+| `description` | No | Shown in `/help`. Defaults to the command name. |
+| `model` | No | Override the active model for this command. |
+
+## Arguments
+
+Use `$ARGUMENTS` for the full argument string, or `$1`, `$2`, … `$9` for individual tokens.
+
+`.agents/commands/search.md`:
+
+```md
+---
+description: Search the codebase for a topic
+model: zen/claude-3-5-haiku
+---
+
+Search the codebase for: $ARGUMENTS
+
+Use glob, grep, and read tools to explore thoroughly. Report all
+relevant files, key code snippets with line numbers, and a short summary.
+Be exhaustive but concise. No edits — read only.
+```
+
+```
+/search session management
+/search error handling in providers
+```
+
+Positional tokens:
+
+```md
+---
+description: Create a new component
+---
+
+Create a React component named $1 in the $2 directory.
+Use TypeScript, include prop types and a default export.
+```
+
+```
+/component Button src/ui
+```
+
+## Shell interpolation
+
+Use `` !`cmd` `` to inject shell output into the prompt at expansion time.
+Commands time out after 10 seconds.
+
+```md
+---
+description: Review failing tests
+---
+
+The following tests are currently failing:
+
+!`bun test 2>&1 | grep "fail\|✗" | head -20`
+
+Investigate the failures and suggest fixes. Read the relevant source
+files before drawing conclusions.
+```
+
+```
+/fix-tests
+```
+
+## Model override
+
+Specify a model in frontmatter to use a faster or cheaper model for
+lightweight tasks regardless of what the session is currently set to.
+
+```md
+---
+description: Quick grep for a symbol
+model: zen/claude-3-5-haiku
+---
+
+Find all usages of $ARGUMENTS across the codebase using grep and glob.
+List each occurrence with file path and line number. No explanations needed.
+```
+
+Large models for deep analysis, small models for search and lookup.
+
+## Precedence
+
+Custom commands shadow built-ins. If you create `.agents/commands/review.md`
+it will replace the built-in `/review` for that project.
+
+## Listing commands
+
+```
+/help
+```
+
+Custom commands are listed at the bottom under **custom commands**, tagged
+with `(local)` or `(global)`.

package/docs/skills.md

@@ -0,0 +1,71 @@
+# Skills
+
+A skill is a reusable instruction file injected inline into your prompt.
+Use `@skill-name` to load it — the content is inserted into the message
+before it's sent to the LLM.
+
+> **Skills are never auto-loaded.** They must be explicitly referenced
+> with `@skill-name` in your prompt. Nothing is injected automatically.
+
+## Where to put them
+
+Each skill is a folder containing a `SKILL.md`:
+
+| Location | Scope |
+|---|---|
+| `.agents/skills/<name>/SKILL.md` | Current repo only |
+| `~/.agents/skills/<name>/SKILL.md` | All projects (global) |
+
+Local skills override global ones with the same name.
+
+## Create a skill
+
+The folder name becomes the skill name (unless overridden by `name:` in frontmatter).
+
+`.agents/skills/conventional-commits/SKILL.md`:
+
+```md
+---
+name: conventional-commits
+description: Conventional commit message format rules
+---
+
+# Conventional Commits
+
+All commit messages must follow this format:
+
+  <type>(<scope>): <short summary>
+
+Types: feat, fix, docs, refactor, test, chore
+- Summary is lowercase, no period at the end
+- Breaking changes: add `!` after type, e.g. `feat!:`
+- Body is optional, wrapped at 72 chars
+```
+
+Then in the REPL:
+
+```
+@conventional-commits write a commit message for my staged changes
+```
+
+The skill content is wrapped in `<skill name="…">…</skill>` tags and
+included in the message sent to the LLM.
+
+## Frontmatter fields
+
+| Field | Required | Description |
+|---|---|---|
+| `name` | No | Skill name for `@` reference. Defaults to folder name. |
+| `description` | No | Shown in `/help`. Defaults to name. |
+
+## Tab completion
+
+Type `@` and press `Tab` to autocomplete skill names alongside files.
+
+## Listing skills
+
+```
+/help
+```
+
+Skills are listed in yellow, tagged `(local)` or `(global)`.

package/docs/tool-hooks.md

@@ -0,0 +1,142 @@
+# Tool Hooks
+
+A tool hook is an executable script that runs automatically after a specific tool call succeeds. Use hooks to trigger side effects — linting, formatting, logging, notifications — without modifying the agent's behaviour.
+
+> Hooks fire **after** the tool succeeds. Failures are silently swallowed and never crash the agent.
+
+## Where to put them
+
+Hooks live in a `hooks/` folder inside an `.agents` config root:
+
+| Location | Scope |
+|---|---|
+| `.agents/hooks/post-<tool>` | Current repo only |
+| `~/.agents/hooks/post-<tool>` | All projects (global) |
+
+Local hooks take precedence over global ones. The filename must match `post-<tool>` exactly — no extension.
+
+## Supported tools
+
+| Tool | Hook filename |
+|---|---|
+| `glob` | `post-glob` |
+| `grep` | `post-grep` |
+| `read` | `post-read` |
+| `create` | `post-create` |
+| `replace` | `post-replace` |
+| `insert` | `post-insert` |
+| `shell` | `post-shell` |
+
+MCP tools are not hookable.
+
+## Script requirements
+
+The script must be executable (`chmod +x`). It can be written in any language — bash, Python, Node, etc. It receives context via environment variables and its exit code is reported in the UI (zero = success, non-zero = failure).
+
+## Environment variables
+
+All hooks receive:
+
+| Variable | Description |
+|---|---|
+| `TOOL` | Name of the tool that fired |
+| `CWD` | Working directory of the session |
+
+Plus tool-specific variables:
+
+### `post-create`
+
+| Variable | Description |
+|---|---|
+| `FILEPATH` | Absolute path of the file written |
+| `DIFF` | Unified diff of the change |
+| `CREATED` | `true` if the file was newly created, `false` if overwritten |
+
+### `post-replace`
+
+| Variable | Description |
+|---|---|
+| `FILEPATH` | Absolute path of the file modified |
+| `DIFF` | Unified diff of the change |
+| `DELETED` | `true` if lines were deleted (no replacement content), `false` otherwise |
+
+### `post-insert`
+
+| Variable | Description |
+|---|---|
+| `FILEPATH` | Absolute path of the file modified |
+| `DIFF` | Unified diff of the change |
+
+### `post-shell`
+
+| Variable | Description |
+|---|---|
+| `COMMAND` | The shell command that was run |
+| `EXIT_CODE` | Exit code of the command |
+| `TIMED_OUT` | `true` if the command timed out |
+| `STDOUT` | Captured standard output |
+| `STDERR` | Captured standard error |
+
+### `post-glob`
+
+| Variable | Description |
+|---|---|
+| `PATTERN` | The glob pattern that was searched |
+
+### `post-grep`
+
+| Variable | Description |
+|---|---|
+| `PATTERN` | The regex pattern that was searched |
+
+### `post-read`
+
+| Variable | Description |
+|---|---|
+| `FILEPATH` | Absolute path of the file read |
+
+## Examples
+
+### Auto-format on write
+
+`.agents/hooks/post-create`:
+
+```bash
+#!/usr/bin/env bash
+# Run the project formatter whenever the agent creates or overwrites a file.
+bun run format -- "$FILEPATH"
+```
+
+```bash
+chmod +x .agents/hooks/post-create
+```
+
+Pair with a matching `post-replace` and `post-insert` to cover all write tools.
+
+### Log every shell command
+
+`~/.agents/hooks/post-shell`:
+
+```bash
+#!/usr/bin/env bash
+# Append a record of every shell command to a global audit log.
+echo "$(date -u +%FT%TZ)  exit=$EXIT_CODE  $COMMAND" >> ~/.config/mini-coder/shell-audit.log
+```
+
+```bash
+chmod +x ~/.agents/hooks/post-shell
+```
+
+### Notify on file write
+
+`.agents/hooks/post-replace`:
+
+```bash
+#!/usr/bin/env bash
+# macOS notification when the agent edits a file.
+osascript -e "display notification \"$FILEPATH\" with title \"mini-coder wrote a file\""
+```
+
+## Hook lookup
+
+Hooks are resolved once at session start and cached in memory — there is no filesystem access per tool call. Changing a hook script takes effect on the next session.

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "mini-coder",
-	"version": "0.0.4",
+	"version": "0.0.6",
 	"description": "A small, fast CLI coding agent",
 	"module": "src/index.ts",
 	"type": "module",