codemini-cli 0.3.8 → 0.4.0

package/README.md

@@ -16,7 +16,7 @@ CodeMini CLI is a terminal coding assistant built for teams that want a sharper,
 
 It is designed around a deliberate idea: most coding workflows do not need a huge default tool surface or unrestricted shell behavior. Instead, CodeMini starts with a compact core, loads advanced tools on demand, and keeps the agent grounded in structured code operations, session todos, lightweight project indexing, and shell-aware safety rules.
 
-**Contents** — [Why CodeMini CLI](#why-codemini-cli) · [Installation](#installation) · [Quick Start](#quick-start) · [Commands](#commands) · [Personalities (Souls)](#personalities-souls) · [Tool Model](#how-the-tool-model-works) · [Core Capabilities](#core-capabilities) · [Project Index](#project-index) · [Good Fit](#good-fit) · [Documentation](#documentation) · [Development](#development) · [License](#license)
+**Contents** — [Why CodeMini CLI](#why-codemini-cli) · [Installation](#installation) · [Quick Start](#quick-start) · [Commands](#commands) · [Personalities (Souls)](#personalities-souls) · [Tool Model](#how-the-tool-model-works) · [Core Capabilities](#core-capabilities) · [Dream Loop (Built-in Memory Evolution)](#dream-loop-built-in-memory-evolution) · [Project Index](#project-index) · [Good Fit](#good-fit) · [Documentation](#documentation) · [Development](#development) · [License](#license)
 
 ### Why CodeMini CLI
 
@@ -58,6 +58,15 @@ codemini doctor
 codemini
 ```
 
+### Optional: FFF Search Acceleration
+
+CodeMini CLI can optionally use `fff-mcp` as a faster backend for `grep`, `glob`, and part of `list`.
+
+- If `fff-mcp` is installed and available in `PATH`, CodeMini will reuse it automatically within the current session.
+- If `fff-mcp` is missing or fails to start, CodeMini falls back to its built-in search implementation automatically.
+- This means `fff-mcp` is an enhancement, not a hard dependency.
+- `codemini doctor` now reports `FFF MCP availability` so you can verify whether it is active.
+
 ### Commands
 
 | Command | Description |
@@ -65,6 +74,11 @@ codemini
 | `codemini [prompt]` | Start an interactive coding session with an optional initial prompt |
 | `codemini chat [prompt]` | Chat mode — single-turn or multi-turn conversation |
 | `codemini run <task>` | Run a task non-interactively (e.g. `codemini run "fix the login bug"`) |
+| `codemini run --harness <role> <task>` | Run a task with a specific sub-agent role (e.g. `coder`, `planner`, `reviewer`) |
+| `codemini run --pipeline <task>` | Run a task through the full planning → coding → review pipeline |
+| `codemini run <task> --max-steps N` | Limit the maximum number of agent steps for a run task |
+| `codemini run <task> --model <name>` | Override the default model for a single run |
+| `codemini [prompt] --plain` | Disable TUI and use plain terminal output |
 | `codemini config set\|get\|list <key> [value]` | Manage configuration (gateway, model, shell, UI, soul, etc.) |
 | `codemini doctor` | Run environment diagnostics and validate configuration |
 | `codemini skill list\|install\|enable\|disable\|inspect\|reindex` | Manage skills — list, install, toggle, or inspect bundled/third-party skills |
@@ -79,6 +93,23 @@ Built-in souls: `default`, `professional`, `ceo`, `playful`, `anime`, `caveman`,
 codemini config set soul.preset playful
 ```
 
+### Built-in Skills
+
+Skills are reusable workflow patterns that guide how the agent approaches different types of tasks. They are loaded automatically when applicable.
+
+| Skill | Trigger | Description |
+|-------|---------|-------------|
+| **superpowers-lite** | Default for all coding work | Lightweight operating style: prefer structured tools, keep context tight, use sub-agents, verify before claiming success |
+| **brainstorm** | Multiple reasonable approaches exist | Explores options and tradeoffs before coding; asks one question at a time to resolve uncertainty |
+| **writing-plans** | Non-trivial implementation task | Creates a step-by-step plan with exact file paths, code, and verification steps before touching code |
+
+Skills are installed and managed via `codemini skill`:
+
+```bash
+codemini skill list        # List all available skills
+codemini skill inspect <name>  # Inspect a skill's details
+```
+
 ### How The Tool Model Works
 
 CodeMini CLI intentionally separates tools into two layers:
@@ -108,6 +139,7 @@ Typical flow:
   - AST tools: `ast_query`, `read_ast_node`
   - background task management tools
   - persistent memory tools
+  - dream loop tools: `capture_memory`, `dream_consolidate`
 - Session-level todo checklists via `update_todos`, rendered natively in the TUI
 - Unified shell execution model:
   - one-off commands via `run`
@@ -117,6 +149,34 @@ Typical flow:
 - Reply language control via `ui.reply_language`
 - Safe mode enabled by default
 
+### Dream Loop (Built-in Memory Evolution)
+
+Dream loop is built into the runtime as native tools and slash commands (not a skill-only workflow).
+
+What goes into inbox vs persistent memory:
+
+- Inbox (`memory/inbox/...`) stores raw, recent, event-level signal captured during work.
+- Typical inbox entries: user corrections, repeated failures, stable preferences, workflow wins, capability gaps, and decisions.
+- Inbox is intentionally noisy and temporary; entries are reviewed by consolidation before promotion.
+- User memory stores user-specific stable preferences and habits that should follow the user across repos.
+- Global memory stores stable cross-task learnings and generally reusable rules.
+- Project memory stores repo-specific conventions, workflows, and constraints tied to one codebase.
+- Archive (`memory/archive/...`) keeps rejected/superseded evidence instead of silently deleting it.
+
+- Capture signal during active work:
+  - Tool: `capture_memory`
+  - Slash: `/capture <summary> [--scope global|repo|thread] [--type observation|correction|failure|preference|pattern|win|gap|decision]`
+- Inspect inbox:
+  - Slash: `/inbox [since-YYYY-MM-DD]`
+- Consolidate inbox into long-term/project memory:
+  - Tool: `dream_consolidate`
+  - Slash: `/dream [--dry-run] [--scope=global|repo|thread]`
+
+Execution mode behavior:
+
+- `execution.mode=auto`: dream tools run normally, and auto-dream can trigger when `memory.auto_dream_threshold` is reached.
+- `execution.mode=plan`: model-planned tool calls are not executed, but slash command `/dream` still executes directly in runtime.
+
 ### Project Index
 
 CodeMini CLI maintains a lightweight project index inside `.codemini-project/`:
@@ -231,6 +291,15 @@ codemini doctor
 codemini
 ```
 
+### 可选：FFF 搜索加速
+
+CodeMini CLI 可以可选地使用 `fff-mcp` 作为 `grep`、`glob` 和部分 `list` 的更快后端。
+
+- 如果 `fff-mcp` 已安装并且在 `PATH` 中可用，CodeMini 会在当前会话内自动复用它。
+- 如果 `fff-mcp` 缺失或启动失败，CodeMini 会自动回退到内置搜索实现。
+- 这意味着 `fff-mcp` 是增强项，不是硬依赖。
+- 现在可以通过 `codemini doctor` 里的 `FFF MCP availability` 看到它是否可用。
+
 ### 命令概览
 
 | 命令 | 说明 |
@@ -238,6 +307,11 @@ codemini
 | `codemini [prompt]` | 启动交互式编码会话，可附带初始提示 |
 | `codemini chat [prompt]` | 对话模式——单轮或多轮 |
 | `codemini run <task>` | 非交互式执行任务（如 `codemini run "修复登录 bug"`） |
+| `codemini run --harness <role> <task>` | 以指定 sub-agent 角色执行任务（如 `coder`、`planner`、`reviewer`） |
+| `codemini run --pipeline <task>` | 通过完整计划→编码→审查流水线执行任务 |
+| `codemini run <task> --max-steps N` | 限制单次执行的最大 agent 步数 |
+| `codemini run <task> --model <name>` | 单次执行时覆盖默认模型 |
+| `codemini [prompt] --plain` | 禁用 TUI，使用纯文本终端输出 |
 | `codemini config set\|get\|list <key> [value]` | 管理配置（网关、模型、shell、UI、soul 等） |
 | `codemini doctor` | 运行环境诊断并验证配置 |
 | `codemini skill list\|install\|enable\|disable\|inspect\|reindex` | 管理 skill——列表、安装、启用/禁用、检查 |
@@ -252,6 +326,23 @@ CodeMini CLI 支持可切换的 "soul" 人格，仅改变语气和表达风格
 codemini config set soul.preset playful
 ```
 
+### 内置 Skills
+
+Skill 是可复用的工作流模式，指导 agent 如何处理不同类型的任务。适用时会自动加载。
+
+| Skill | 触发条件 | 说明 |
+|-------|----------|------|
+| **superpowers-lite** | 所有编码工作的默认 skill | 轻量操作风格：优先结构化工具、保持上下文精简、使用 sub-agent、验证后再报告完成 |
+| **brainstorm** | 存在多种合理方案时 | 在编码前探索选项和权衡；每次只问一个问题来消除不确定性 |
+| **writing-plans** | 非平凡的实现任务 | 在动手之前创建包含精确文件路径、代码和验证步骤的分步计划 |
+
+通过 `codemini skill` 管理技能：
+
+```bash
+codemini skill list           # 列出所有可用 skill
+codemini skill inspect <name> # 查看某个 skill 的详细信息
+```
+
 ### 工具模型怎么设计
 
 CodeMini CLI 把工具分成两层：
@@ -281,6 +372,7 @@ CodeMini CLI 把工具分成两层：
   - AST 工具：`ast_query`、`read_ast_node`
   - 后台任务管理工具
   - 持久 memory 工具
+  - dream loop 工具：`capture_memory`、`dream_consolidate`
 - 通过 `update_todos` 维护复杂单任务的会话级待办清单，并直接渲染在 TUI 中
 - 统一的 shell 执行模型：
   - 一次性命令直接 `run`
@@ -290,6 +382,34 @@ CodeMini CLI 把工具分成两层：
 - 支持通过 `ui.reply_language` 控制回复语言
 - safe mode 默认开启
 
+### Dream Loop（内置记忆演化）
+
+Dream loop 是运行时内置能力，不依赖 skill 才能使用。
+
+Inbox 和持久记忆的区别：
+
+- Inbox（`memory/inbox/...`）保存的是工作过程中的原始事件信号，强调“先记下来”。
+- 典型 inbox 条目：用户纠正、重复失败、稳定偏好、流程收益、能力缺口、关键决策。
+- Inbox 本质上是临时且可能带噪的，需经 consolidation 审核后再晋升。
+- User memory 保存“跟这个用户长期相关”的稳定偏好与习惯，可跨仓库复用。
+- Global memory 保存跨任务可复用的稳定经验或规则。
+- Project memory 保存特定仓库的约定、流程和约束。
+- Archive（`memory/archive/...`）用于保留被拒绝/被覆盖证据，而不是静默删除。
+
+- 在工作中捕获高信号：
+  - 工具：`capture_memory`
+  - 斜杠命令：`/capture <summary> [--scope global|repo|thread] [--type observation|correction|failure|preference|pattern|win|gap|decision]`
+- 查看 inbox：
+  - 斜杠命令：`/inbox [since-YYYY-MM-DD]`
+- 把 inbox 整理进长期/项目记忆：
+  - 工具：`dream_consolidate`
+  - 斜杠命令：`/dream [--dry-run] [--scope=global|repo|thread]`
+
+执行模式差异：
+
+- `execution.mode=auto`：dream 工具可正常执行；当达到 `memory.auto_dream_threshold` 时可自动触发 consolidation。
+- `execution.mode=plan`：模型规划出的工具调用不会执行，但 `/dream` 作为运行时命令仍可直接执行。
+
 ### 项目索引
 
 CodeMini CLI 会在 `.codemini-project/` 下维护一份轻量项目索引：

package/deployment.md

@@ -13,13 +13,13 @@ npm pack
 Expected output:
 
 ```text
-codemini-cli-0.1.0.tgz
+codemini-cli-0.4.0.tgz
 ```
 
 If you want to verify the package contents:
 
 ```bash
-tar -tf codemini-cli-0.1.0.tgz
+tar -tf codemini-cli-0.4.0.tgz
 ```
 
 ## 2. Copy To The Target Machine
@@ -34,7 +34,7 @@ Copy the generated `.tgz` file to the Win10 machine by one of these methods:
 Recommended target path:
 
 ```powershell
-C:\temp\codemini-cli-0.1.0.tgz
+C:\temp\codemini-cli-0.4.0.tgz
 ```
 
 ## 3. Environment Requirements
@@ -42,7 +42,7 @@ C:\temp\codemini-cli-0.1.0.tgz
 Target machine requirements:
 
 - Windows 10
-- Node.js 20 or newer
+- Node.js 22 or newer
 - npm available
 - PowerShell available
 
@@ -58,7 +58,7 @@ npm -v
 Global install:
 
 ```powershell
-npm install -g C:\temp\codemini-cli-0.1.0.tgz
+npm install -g C:\temp\codemini-cli-0.4.0.tgz
 ```
 
 If global install is blocked by company policy, install in a working directory instead:
@@ -66,7 +66,7 @@ If global install is blocked by company policy, install in a working directory i
 ```powershell
 mkdir C:\temp\coder-test
 cd C:\temp\coder-test
-npm install C:\temp\codemini-cli-0.1.0.tgz
+npm install C:\temp\codemini-cli-0.4.0.tgz
 ```
 
 ## 5. Confirm Installation

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "codemini-cli",
-  "version": "0.3.8",
+  "version": "0.4.0",
   "description": "Coding CLI optimized for small-model workflows and Windows PowerShell",
   "keywords": [
     "cli",
@@ -47,8 +47,13 @@
   },
   "dependencies": {
     "@cursorless/tree-sitter-wasms": "^0.8.1",
+    "cheerio": "^1.1.2",
+    "cli-truncate": "^6.0.0",
+    "duck-duck-scrape": "^2.2.7",
     "ink": "^7.0.0",
+    "playwright": "^1.54.2",
     "react": "^19.2.5",
+    "strip-ansi": "^7.2.0",
     "web-tree-sitter": "^0.26.8"
   },
   "license": "MIT"

package/skills/brainstorm/SKILL.md

@@ -1,50 +1,70 @@
 ---
 name: brainstorm
-description: Lightweight brainstorming skill for 30B-class models. Use when a feature or behavior request is still unclear and the agent should compare a few approaches before coding.
-version: 0.1.0
+description: Lightweight brainstorming skill. Use when a feature or behavior request has multiple reasonable approaches and the missing piece is user preference, tradeoff choice, or key constraint.
+version: 0.2.0
 ---
 
 Use this skill only when the task needs clarification or option comparison before coding.
 
-Core rules:
-- ask one question at a time
-- if a key uncertainty remains, ask the next best question and stop
-- give 2-3 short options only when the blocking constraint is already clear
-- keep options concrete and focused on the main tradeoff
-- present any conclusion as a suggested decision, not a final choice for the user
-- stop at the decision point unless the user clearly asks to continue
-- do not write code, pseudo-code, file edits, or broad repo exploration while direction is still being chosen
+**Announce:** When entering brainstorm, say "Using brainstorm to explore approaches before implementation."
 
-Output format:
+## Anti-Pattern
 
-Mode A: key constraint missing
+Do NOT skip this skill because "it's simple." Underspecified "simple" tasks cause the most wasted work. Even a few seconds of clarification beats a wrong implementation.
 
+## Process
+
+1. **Ask one question at a time.** If a key uncertainty remains, ask the next best question and STOP. Wait for the user's answer.
+2. **Give 2-3 short options** only when the blocking constraint is already clear. Keep options concrete and focused on the main tradeoff.
+3. **Present conclusions as suggested decisions**, not final choices.
+4. **Do NOT write code, pseudo-code, file edits, or broad repo exploration** while direction is still being chosen.
+
+## Output Formats
+
+### Mode A: key constraint missing
+
+```
 Question:
-- ask:
-- why this matters:
+- ask: <one specific question>
+- why this matters: <1-2 sentences on what this decides>
+```
 
-Wait for the user's answer.
+Wait for the user's answer. Do NOT proceed with options or code.
 
-Mode B: goal is clear but approach choice remains
+### Mode B: goal is clear but approach choice remains
 
+```
 Option 1:
-- idea:
-- pros:
-- cons:
+- idea: <concrete approach>
+- pros: <1-2 points>
+- cons: <1-2 points>
 
 Option 2:
-- idea:
-- pros:
-- cons:
+- idea: <concrete approach>
+- pros: <1-2 points>
+- cons: <1-2 points>
 
 Option 3 (optional):
-- idea:
-- pros:
-- cons:
+- idea: <concrete approach>
+- pros: <1-2 points>
+- cons: <1-2 points>
 
 Suggested decision:
-- recommended:
-- reason:
+- recommended: <option N>
+- reason: <why>
+```
+
+## Self-Review
+
+Before presenting options or a suggested decision, quickly check:
+- Are all options actually different, or are two of them the same idea in different words?
+- Does the recommended option match the user's stated constraints?
+- Did I invent requirements the user never mentioned? Remove them.
+
+## Exit
+
+After the user approves a direction:
+- If the task is small and clear enough to implement directly → proceed to code.
+- If the task is non-trivial or touches multiple areas → YOU MUST invoke `writing-plans` to create an implementation plan before coding.
 
-After suggested decision:
-- stop after the recommended direction unless the user clearly asks to continue into implementation
+Do NOT stop at the brainstorm conclusion when the natural next step is planning.

package/skills/superpowers-lite/SKILL.md

@@ -1,100 +1,92 @@
 ---
 name: superpowers-lite
 description: Concise workflow skill tuned for 30B-class models: prefer structured code tools first, keep context tight, use sub-agents for narrow tasks, and verify before claiming success.
-version: 0.1.0
+version: 0.2.0
 ---
 
-Use this skill as the default lightweight operating style for coding work.
-
-Primary behavior:
-- keep momentum on clear tasks
-- slow down before coding when the request is ambiguous
-- keep edits local
-- verify before claiming success
-
-Routing:
-
-1. If the task is clear, small, and the implementation path is obvious:
-- execute directly
-- do not force brainstorming
-
-2. If the task is a non-trivial implementation that likely needs codebase exploration, touches multiple areas, changes shared behavior, or needs explicit review/testing before coding:
-- prefer `auto plan`
-- inspect first, then present a short implementation plan for approval
-- do not jump straight into coding
-- do not use `brainstorm` as a substitute for implementation planning
-
-3. If the goal is clear but there are multiple reasonable implementation paths and the missing piece is mainly user preference, tradeoff choice, or one key constraint:
-- use `brainstorm`
-- ask exactly one clarifying question first
-- do not give options, recommendations, or a tentative solution in the same response
-- stop after the question and wait for the user's answer before continuing
-
-4. If the request is still missing a key constraint or success condition:
-- ask exactly one clarifying question
-- do not give options yet
-- do not write code yet
-- stop after the question and wait for the user's answer
-
-5. If the request is greenfield and underspecified, such as "build a page", "make a site", "generate an app", or similar:
-- treat it as missing key constraints by default
-- ask one high-value question before coding
-- do not assume features, storage model, or scope unless the user already gave them
-- stop after the question and wait for the user's answer
-
-Decision boundary:
+Use this skill as the default lightweight operating style for all coding work.
+
+**Announce when using a skill:** Before following any route below, say "Using [skill name] to [purpose]" in your response. This signals intent and prevents silent skill skipping.
+
+## Mandatory Skill Check
+
+Before responding to ANY user message, check whether a skill applies. If there is even a small chance a skill is relevant, YOU MUST invoke it. This is not optional.
+
+**Skill check comes BEFORE:**
+- Clarifying questions
+- Code exploration
+- Writing code
+- Anything else
+
+## Anti-Rationalization
+
+If you catch yourself thinking any of the following, STOP — you are about to skip a skill incorrectly:
+
+| Thought | Reality |
+|---|---|
+| "This is too simple for a skill" | Simple tasks derail too. Use the skill. |
+| "I need more context first" | Skills tell you HOW to gather context. Check first. |
+| "The skill is overkill here" | A lightweight pass is cheaper than rework. |
+| "I'll just do this one thing first" | Do the skill check BEFORE anything. |
+| "I already know what to do" | Knowing the concept ≠ following the process. |
+
+## Routing
+
+Evaluate the user's request and YOU MUST follow exactly one route:
+
+1. **Task is clear, small, and obvious path:**
+   - Execute directly
+   - Do NOT invoke brainstorming
+
+2. **Non-trivial implementation that needs codebase exploration, touches multiple areas, or changes shared behavior:**
+   - YOU MUST invoke `writing-plans` skill
+   - Inspect first, then present an implementation plan for approval
+   - Do NOT jump straight into coding
+
+3. **Goal is clear but multiple reasonable approaches exist and the missing piece is user preference or tradeoff choice:**
+   - YOU MUST invoke `brainstorm` skill
+   - Follow brainstorm process — do NOT substitute it with ad-hoc questions
+
+4. **Request is missing a key constraint or success condition:**
+   - Ask exactly one clarifying question
+   - Do NOT give options or write code
+   - Stop and wait for the answer
+
+5. **Request is greenfield and underspecified** ("build a page", "make a site", "generate an app"):
+   - Treat as missing key constraints
+   - Ask one high-value question
+   - Do NOT assume features, scope, or storage model
+   - Stop and wait for the answer
+
+**Decision boundary:**
 - Use `brainstorm` when one focused user answer will determine the direction.
-- Use `auto plan` when the task is already implementation-shaped but the work is large enough that you should explore first and get sign-off on the plan.
-- If both could apply, prefer `brainstorm` first when the core uncertainty is user intent; prefer `auto plan` first when the core uncertainty is codebase impact and execution shape.
-
-Tool order:
-- prefer `grep` first for content search and candidate discovery
-- use `read` to inspect the smallest useful code block
-- use `edit` for minimal focused edits or direct whole-file rewrites when you already have the replacement content
-- use `generate_diff` and `patch` for larger edits or when you already have a diff
-- use `glob` and `list` when you need file or directory discovery
-- use shell search such as `rg` only as a fallback when structured tools are not enough
-
-Core rules:
-
-1. Search first.
-Prefer structured search before broad file reads. Start with `grep`, then inspect with `read`, and only fall back to shell search such as `rg` when the structured tools are not enough.
-
-2. Keep context tight.
-Do not carry full conversation history into every step. Summarize, narrow scope, and work from the most recent relevant evidence.
-
-3. Prefer narrow sub-agents.
-When a task can be split cleanly, use sub-agents for bounded subtasks so the main thread keeps global focus. Give each sub-agent:
-- one clear objective
-- a tiny context summary
-- a tiny file evidence packet
-- a concrete expected output
-
-4. Do not code against unclear requirements.
-If the requested behavior, scope, or acceptance is unclear, do not jump into implementation. First decide which of these applies:
-- missing key constraint -> ask one question
-- multiple valid approaches -> use `brainstorm`
-- clear enough to build -> proceed
-
-5. Read and write with intent.
-Use `read` before broad reads when possible. Use `edit` for focused edits or when you already have the complete replacement content. Use `generate_diff` and `patch` for larger changes. Use `write` only for creating new files or explicit whole-file writes. Avoid unnecessary tool calls and avoid rereading the same file without a reason.
-
-6. Verify before claiming success.
-Run the relevant test, check, or command before saying work is fixed or complete.
-
-Default workflow:
-- Search with `grep`
-- Inspect local context with `read`
-- If the request is unclear, first decide: ask one question, brainstorm, auto plan, or proceed
-- Plan the next smallest step
-- Delegate if the work is independent
-- Edit with `edit`
-- Verify
-- Summarize briefly
-
-Sub-agent guidance:
+- Use `writing-plans` when the task is implementation-shaped but needs a plan before coding.
+- If both could apply, prefer `brainstorm` first when the core uncertainty is user intent; prefer `writing-plans` first when the core uncertainty is codebase impact.
+
+## Tool Order
+
+- Prefer `grep` first for content search and candidate discovery
+- Use `read` to inspect the smallest useful code block
+- Use `edit` for minimal focused edits or whole-file rewrites
+- Use `glob` when you need file or directory discovery
+- Use shell search (`rg`) only as a fallback
+
+## Core Rules
+
+1. **Search first.** Start with `grep`, then `read`. Fall back to shell only when structured tools aren't enough.
+
+2. **Keep context tight.** Do not carry full conversation history into every step. Summarize and narrow scope.
+
+3. **Prefer narrow sub-agents.** When a task splits cleanly, delegate to sub-agents with: one clear objective, tiny context, concrete expected output.
+
+4. **Do not code against unclear requirements.** Missing constraint → ask one question. Multiple approaches → `brainstorm`. Clear enough → proceed.
+
+5. **Verify before claiming success.** Run the relevant test or command before saying work is done.
+
+## Sub-agent Guidance
+
 - `planner`: break work into steps, risks, and checks
 - `coder`: implement one bounded change
 - `reviewer`: look for bugs, regressions, and missing verification
 
-If the task is simple, stay lightweight. Do not expand into a large ceremony unless the problem actually needs it.
+If the task is simple, stay lightweight. Do not expand into ceremony unless the problem needs it.

package/skills/writing-plans/SKILL.md

@@ -0,0 +1,67 @@
+---
+name: writing-plans
+description: Use when you have a clear goal or approved design for a non-trivial task, before touching code. Creates a step-by-step implementation plan with exact file paths, code, and verification steps.
+version: 0.1.0
+---
+
+Use this skill when the task is implementation-shaped but large enough that jumping straight into coding is risky.
+
+**Announce:** When entering writing-plans, say "Using writing-plans to create an implementation plan."
+
+## When to Use
+
+- Task touches 3+ files or multiple areas of the codebase
+- Task changes shared behavior, APIs, or data flow
+- Task has interdependent steps where order matters
+- You need user sign-off before starting work
+
+## When NOT to Use
+
+- Single-file fix with a clear solution → just do it
+- Task is a direct extension of an existing pattern → just do it
+- User explicitly says to skip planning → respect that
+
+## Plan Format
+
+Write the plan as a markdown checklist. Each step is one action (2-5 minutes of work).
+
+```markdown
+# [Task Name] Plan
+
+**Goal:** [one sentence]
+**Files:** [list files that will be created or modified]
+
+### Phase 1: [Phase name]
+
+- [ ] **Step N: [action verb + what]**
+  - File: `exact/path/to/file.ext`
+  - What: [specific change]
+  - Verify: [how to confirm it works]
+
+### Phase 2: [Phase name]
+
+- [ ] ...
+```
+
+## Rules
+
+1. **Exact file paths always.** No "the relevant file" or "in the component directory".
+2. **Show code in steps that change code.** No "add appropriate error handling" without showing the code.
+3. **No placeholders.** No "TBD", "TODO", "implement later", "similar to step N". If a step needs code, write the code.
+4. **Every step is verifiable.** Include a test command, expected output, or visual check.
+5. **YAGNI.** Only plan what was asked for. Do not add "nice to have" steps.
+6. **DRY.** If two steps share logic, plan the shared piece first.
+
+## Self-Review
+
+After writing the plan, check:
+- Can you point to a step for every requirement? If not, add the missing step.
+- Any placeholders or vague descriptions? Replace with specifics.
+- Do types and function names match across steps? Fix inconsistencies.
+- Is the order correct? Steps that depend on earlier work must come after.
+
+## Exit
+
+After the user approves the plan → proceed to implement step by step.
+After each step → verify before moving to the next.
+If a step reveals the plan is wrong → stop, explain, and update the plan before continuing.