@@ -2,20 +2,19 @@
22
33 ## Status at a glance
44
5-This refactor is mostly done.
5+This refactor is complete on this branch.
66
7-The branch has already moved mini-coder toward the intended shell-first model:
7+mini-coder now follows the intended shell-first model:
88
99 - `mc-edit` exists as a dedicated helper binary
10-- shared file-edit logic was extracted under `src/internal/file-edit/`
11-- shell now exposes `mc-edit` as the preferred targeted edit path
12-- the system prompt and tool surface were simplified around shell usage
13-- model-facing local file tools have been removed or are in the process of being fully deleted from the old path
14-- hook support has been removed as part of the same cleanup
10+- shared file-edit logic lives under `src/internal/file-edit/`
11+- shell exposes `mc-edit` as the targeted edit path
12+- the system prompt and tool surface are simplified around shell usage
13+- old model-facing local file tools are removed
14+- hook support is removed
15+- `/undo` is conversation-turn undo only
1516
16-The undo cleanup has now landed too.
17-
18-`/undo` is now a conversation-turn undo only. It no longer tries to restore filesystem state, which keeps the architecture honest with the real shell + `mc-edit` edit path.
17+`/undo` no longer tries to restore filesystem state, which keeps the architecture honest with the real shell + `mc-edit` edit path.
1918
2019 ---
2120
@@ -32,8 +31,8 @@ Problems with the old approach:
3231 - failures regularly degraded into reread-and-repair loops
3332 - when that happened, shell was already the practical fallback
3433
35-The point of this refactor is **not** to improve that protocol.
36-The point is to replace it with a simpler contract that matches how models already work best:
34+The point of this refactor was **not** to improve that protocol.
35+The point was to replace it with a simpler contract that matches how models already work best:
3736
3837 - inspect with shell
3938 - edit with a narrow helper
@@ -47,7 +46,7 @@ That is why `mc-edit` exists.
4746
4847 ### Final model-facing tool surface
4948
50-The intended steady state is:
49+The steady state is:
5150
5251 - connected **MCP tools**
5352 - **`shell`**
@@ -81,7 +80,7 @@ The intended workflow is:
8180
8281 ---
8382
84-## What has landed on this branch
83+## What landed on this branch
8584
8685 ### 1. Shared file-edit internals were extracted
8786
@@ -114,7 +113,7 @@ Implemented by removing the hashline edit flow built around `replace` and `inser
114113
115114 ### 5. The local tool surface was reduced
116115
117-The branch now targets a much smaller local runtime surface centered on:
116+The local runtime surface is now centered on:
118117
119118 - `shell`
120119 - `subagent`
@@ -122,15 +121,13 @@ The branch now targets a much smaller local runtime surface centered on:
122121 - `readSkill`
123122 - optional Exa tools
124123
125-That is the right direction and should remain the end state.
126-
127124 ### 6. Hook support was removed instead of redesigned
128125
129-This cleanup is part of the refactor because hooks were tied to the old, heavier local tool story and were not worth carrying forward in the middle of this architecture change.
126+This cleanup was part of the refactor because hooks were tied to the old, heavier local tool story and were not worth carrying forward in the middle of this architecture change.
130127
131-### 7. CLI and docs cleanup has started
128+### 7. CLI and docs cleanup was completed
132129
133-Prompt text, tool rendering, help text, and docs have already been pushed toward the shell-first model, but this part still needs a final consistency pass now that undo is settled.
130+Prompt text, tool rendering, help text, and docs now consistently reflect the shell-first model and the conversation-only `/undo` behavior.
134131
135132 ---
136133
@@ -138,7 +135,7 @@ Prompt text, tool rendering, help text, and docs have already been pushed toward
138135
139136 ### 1. Shell is the primary interface for repo work
140137
141-Shell should be the default for:
138+Shell is the default for:
142139
143140 - reading files
144141 - searching
@@ -186,13 +183,13 @@ Their names and descriptions should stay concise and easy to distinguish from sh
186183
187184 ---
188185
189-## What is left to do
186+## Completion status
190187
191188 ### 1. Redesign `/undo`
192189
193190 This work is done.
194191
195-### What changed
192+#### What changed
196193
197194 Undo no longer depends on the old snapshot path.
198195 The snapshot-specific pieces were removed, including:
@@ -204,7 +201,7 @@ The snapshot-specific pieces were removed, including:
204201 `/undo` now removes only the most recent conversation turn from session history.
205202 It does not try to infer or restore filesystem state from shell-driven edits.
206203
207-### Result
204+#### Result
208205
209206 - `/undo` doesn't manage filesystem changes
210207 - snapshotting is removed from runtime code and docs
@@ -213,32 +210,11 @@ It does not try to infer or restore filesystem state from shell-driven edits.
213210
214211 ### 2. Finish the docs and help-text consistency pass
215212
216-This is partially done.
217-
218-The repo is already telling the new story in several places, and the `/undo` wording has now been updated in the core help/manpage/README surfaces, but there is still not one fully consistent source of truth yet.
219-
220-### Sweep targets
221-
222-- `mini-coder-idea.md` Note: keep it focused and in the existing idea style.
223-- `README.md`
224-- `docs/mini-coder.1.md`
225-- `docs/configs.md`
226-- `docs/custom-commands.md`
227-- `docs/custom-agents.md`
228-- `docs/skills.md`
229-- `.agents/commands/*`
230-- `.agents/agents/*`
231-- `.agents/skills/*`
232-
233-### What to check
213+This work is done.
234214
235-- mini-coder is described as shell-first
236-- `mc-edit` is clearly named as the targeted edit path
237-- removed local file tools are not described as active runtime tools
238-- removed hook support is not described anywhere
239-- `/undo` wording matches the redesigned guarantee everywhere it is documented
215+README, config/docs pages, bundled commands/skills guidance, and `mini-coder-idea.md` consistently describe the shell-first model, name `mc-edit` as the targeted edit path, and keep `/undo` scoped to conversation history only.
240216
241-### Done when
217+#### Done when
242218
243219 - docs match implementation
244220 - examples reinforce shell + `mc-edit`
@@ -249,25 +225,11 @@ The repo is already telling the new story in several places, and the `/undo` wor
249225
250226 ### 3. Final prompt, CLI, and rendering polish
251227
252-Most of this is already moving in the right direction, and the undo-specific wording cleanup is now done, but it still needs a final pass for overall consistency.
253-
254-### Areas to review
255-
256-- `src/agent/system-prompt.ts`
257-- `src/cli/tool-render.ts`
258-- `src/cli/tool-result-renderers.ts`
259-- `src/cli/commands-help.ts`
260-- `src/mcp/client.ts`
261-
262-### What to improve
228+This work is done.
263229
264-- ensure the prompt matches the final tool surface exactly
265-- keep shell guidance crisp and unambiguous
266-- make MCP descriptions more context-efficient if needed
267-- keep result previews compact and useful for shell and MCP output
268-- remove any remaining wording tied to old snapshot behavior
230+The system prompt names the final built-in tool surface explicitly, `/help` keeps `/undo` aligned with the conversation-only guarantee, MCP tool descriptions are tighter, and skill-tool call/result rendering is compact and readable.
269231
270-### Done when
232+#### Done when
271233
272234 - prompt text exactly matches runtime behavior
273235 - CLI output reflects only the remaining architecture
@@ -277,17 +239,11 @@ Most of this is already moving in the right direction, and the undo-specific wor
277239
278240 ### 4. Verify the cleanup end-to-end
279241
280-Before this refactor is considered complete, we should do one final dead-code and behavior sweep.
281-
282-### Check for
242+This work is done on this branch.
283243
284-- no runtime registration of removed local file tools
285-- no dead hashline or old edit-protocol code left behind
286-- no hook runtime/UI/doc code left behind
287-- tests aligned with the new tool surface
288-- shell + `mc-edit` workflow working in practice
244+The runtime tool set is reduced to the intended surface, the bundled hook example files were removed, and the full repo verification command passes.
289245
290-### Repo verification command
246+#### Repo verification command
291247
292248 Run:
293249
@@ -295,7 +251,7 @@ Run:
295251 bun run jscpd && bun run knip && bun run typecheck && bun run format && bun run lint && bun run test
296252 ```
297253
298-Status on this branch: this command passes after the undo cleanup.
254+Status on this branch: this command passes after the full shell-first cleanup.
299255
300256 ---
301257
@@ -306,7 +262,7 @@ This refactor is complete when all of the following are true:
306262 - the model-visible tool surface is shell, subagent, listSkills, readSkill, connected MCP tools, and optional Exa tools
307263 - `mc-edit` is the clear targeted edit path
308264 - the old hashline edit path is fully gone
309-- hooks are fully gone from runtime, UI, and docs
265+- hooks are fully gone from runtime, UI, and docs/examples
310266 - `/undo` is aligned with the shell-first architecture by only undoing conversation history
311267 - prompt, CLI, and docs all describe the same architecture
312268 - bundled commands/skills/examples reinforce the shell-first workflow
@@ -327,12 +283,13 @@ This effort is not trying to:
327283
328284 ## Practical conclusion
329285
330-Compared to `main`, the branch has already done the hard architectural shift: `mc-edit` exists, shell is the primary path, and the old local edit model has been largely dismantled.
286+Compared to `main`, this branch completed the hard architectural shift: `mc-edit` exists, shell is the primary path, the old local edit model is gone, hooks are gone, and `/undo` is aligned with conversation history rather than filesystem restoration.
331287
332-What remains is mostly about making the new architecture complete and honest:
288+At this point, the refactor is complete in the intended sense:
333289
334-- finish the remaining docs/help/prompt consistency pass
335-- do one final MCP/CLI polish sweep
336-- verify no stale code or messaging remains
290+- the model-visible tool surface is small and shell-first
291+- `mc-edit` is the clear targeted edit path
292+- prompt, CLI, docs, and bundled examples describe the same architecture
293+- verification passes on the branch
337294
338-That is the real endgame for this refactor.
295+Future work can build on this baseline, but the file-helper refactor itself has reached its intended end state.