@@ -2,7 +2,7 @@
22
33 - App data folder is in `~/.config/mini-coder/`. It includes sqlite db file and logs.
44 - README.md is cosmetic for users, don't edit unless asked to.
5-- Known issues are in `docs` as well as the other man-like document about mini-coder.
5+- `docs/KNOWN_ISSUES.md` tracks known issues. `docs/mini-coder.1.md` is the man page.
66 - Create or reuse the `TODO.md` file to track your progress in long tasks. Remove completed items, keep it clean, concise, and up to date at all times. Track it in git.
77 - Write minimal tests, focused on our code's logic. Never test dependencies. Never use mocks or stubs.
88 - Keep the repo pristine: no failing tests, no lint, no build issues, no `ignore`-style comments. No failing hooks.
@@ -16,7 +16,7 @@
1616 - Don't make random test files, if you need to test something, write a proper unit test.
1717 - If you make temp files, clean them up when you are done.
1818 - Use Conventional Commits formatting for commit messages. When you commit, include the whole diff unless told otherwise.
19-- Always use your superpowers skills effectively.
19+- Before starting work, check superpowers skills (`listSkills`) and load any that match the task.
2020
2121 ## Core idea, treat this as the source of truth for the design/implementation.
2222
@@ -35,26 +35,24 @@ An augmented shell prompt coding agent — small, fast, stays out of the way.
3535
3636 **Performance first, style second.** Instant feedback, shell-like output.
3737
38-Focused on dev flow — simple setup, fast to coding.
39-Elegant output focused on the conversation and agent actions. Accurate chronological log with clear hierarchy: actions → results → reasoning → responses.
40-Accurate, reliable, fast core features.
41-Community oriented — follow existing dotfile conventions, don't introduce new specs.
38+Focused on dev flow — minimal setup, fast to coding.
39+Output is a scrolling chronological log with strict hierarchy: actions → results → reasoning → responses. No redraws, no clearing — append-only like a terminal.
40+Core features must be correct and fast before adding new ones.
41+Community oriented — support AGENTS.md and agentskills.io specs, don't introduce new config formats.
4242
4343 ### Features:
4444
45-- We want to do our best to support and autodiscover community config standards:
46- - AGENTS.md -> https://agents.md/
47- - CLAUDE.md (same as AGENTS.md)
48- - Skills -> https://agentskills.io/client-implementation/adding-skills-support (and https://agentskills.io/client-implementation/adding-skills-support.md, https://agentskills.io/llms.txt)
49- - Claude skills too. They claim to follow the spec, we should only need to discover them too.
45+- Autodiscover and load community config standards on startup:
46+ - AGENTS.md / CLAUDE.md → https://agents.md/
47+ - Skills (`.agents/skills/` and `.claude/skills/`) → https://agentskills.io/client-implementation/adding-skills-support
5048
5149 - Auto discovery of providers via ENV (Example: OPENCODE_API_KEY), or local servers (Example: ollama)
52- - `/login` shows OAuth login status. `/login <provider>` starts browser-based OAuth login. `/logout <provider>` clears saved tokens. Currently supports Anthropic. (Both pi and opencode support this too)
50+ - `/login` shows OAuth login status. `/login <provider>` starts browser-based OAuth login. `/logout <provider>` clears saved tokens. Currently supports Anthropic.
5351 - `/model` (alias `/models`) picks a model from connected providers, including thinking effort if supported. Selection persists across sessions with autocomplete.
5452
5553 - Session management and command to create new/resume/list with local sqlite file.
5654 - `/session` command to interactively manage sessions as well as cli flags.
57- - `/new` starts a new session with clean context. Clean UI and fresh session display
55+ - `/new` starts a new session with empty message history and resets the status bar.
5856
5957 - Enriched user prompt:
6058 - Rich line editing/history/image paste. Enter submits.
@@ -68,19 +66,19 @@ Community oriented — follow existing dotfile conventions, don't introduce new
6866 - Rolling context pruning per step; stops with a conversation summary at max context. Must not break prompt caching.
6967 - No max steps or tool call limits — user can interrupt.
7068 - Clear, accurate token tracking.
71- - Recover from errors gracefully, returning user to the prompt.
69+ - On error, log it, display a one-line summary to the user, and return to the input prompt.
7270 - `/undo` removes the last turn from history (does not restore filesystem).
7371
7472 - Shell-first tool surface: `shell`, `listSkills`, `readSkill`, plus connected MCP tools and optional web tools (`EXA_API_KEY`). Keep it small.
7573 - Inspect with shell → mutate with `mc-edit` → verify with shell.
7674 - Auto-truncate large shell outputs for the LLM to avoid context explosions.
7775 - `mc-edit`: exact-text edits only, deterministic failures on stale/ambiguous state.
78- - Cross-model system prompt with clear dev flow guidance.
76+ - Single system prompt that works across all supported models (no provider-specific branches).
7977
8078 - Other Commands in CLI prompt:
8179 - `/reasoning` toggles display of model reasoning output.
8280 - `/verbose` toggles output truncation. When off, large outputs keep start/end sections and truncate the middle. UI-only visibility concern.
83- - `/review` reviews recent changes via a global custom skill installed at app start (`~/.agents/skills/review.md`), and can be customized or shadowed locally.
81+ - `/review` runs the review skill (`~/.agents/skills/review/SKILL.md`). A local `.agents/skills/review/SKILL.md` in the project overrides the global one.
8482
8583 - Connect to MCP servers over Streamable HTTP / SSE fallback or stdio.
8684 - `/mcp` list/add/remove mcp servers. servers are stored in sqlite
@@ -89,13 +87,13 @@ Community oriented — follow existing dotfile conventions, don't introduce new
8987
9088 - Use the 16 ANSI colors so coloring is always inherited from the terminal theme (https://jvns.ca/blog/2024/10/01/terminal-colours/)
9189 - Use pi and claude code as visual inspirations.
92-- Banner at app start, show found configs and context files
93-- history log (like a terminal output scrolls away, pushing the input prompt down)
94- - Skill tools show compact metadata-oriented output
95- - Shell tool shows the command called and its output
96- - MCP tools stay clearly distinguishable from shell work
97-- status bar like prompt, with current model/provider/session/git branch/thinking effort/context usage/token input/token output information grouped logically and human readable.
98-- some prompt colored animation when a turn is processing. Needs to be carefully done, so it shows correctly in wait times and with clear labels
90+- Banner at app start listing discovered AGENTS.md files, context files, and provider status.
91+- Append-only scrolling log (new output pushes the input prompt down, nothing is redrawn):
92+ - Skill tools: one-line name + description, no body content.
93+ - Shell tool: the command, then its stdout/stderr.
94+ - MCP tools: prefixed with server name to distinguish from built-in tools.
95+- Status bar above the input prompt showing: model, provider, session id, git branch, thinking effort, context %, input tokens, output tokens.
96+- Inline spinner with a label (e.g. "thinking", "running shell") while waiting for LLM or tool responses. Must not interfere with scrollback or leave artifacts on interrupt.
9997
10098 ### Tech stack
10199
@@ -105,5 +103,5 @@ Community oriented — follow existing dotfile conventions, don't introduce new
105103
106104 ### Repo structure
107105
108-Clean separation of concerns, use modules to organize the app. Group logical features together for best browsability and readability of the code. Use subdirectories to group files logically.
109-No mocked/offline-servers type of tests. Focused tests on _our_ logic. Do not test our dependencies.
106+One directory per module (e.g. `cli/`, `agent/`, `session/`, `tools/`, `llm-api/`). Each directory owns its types, logic, and tests — no cross-module circular imports.
107+Tests live next to the code they test (`foo.test.ts` beside `foo.ts`). No mock servers, no dependency tests — test only our logic.