@miphamai/cli 0.24.6 → 0.24.8

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@miphamai/cli",
-  "version": "0.24.6",
+  "version": "0.24.8",
   "description": "Mipham Code — Multi-model open-core intelligent coding terminal by MiphamAI",
   "keywords": [
     "ai",

package/skills/standard/implement.SKILL.md

@@ -0,0 +1,155 @@
+---
+name: implement
+description: Build work from a spec or tickets with systematic discipline — TDD at pre-agreed seams, incremental verification, code review before commit. Use when implementing features, bugfixes, or any planned work.
+version: 1.0.0
+user-invocable: true
+---
+
+# Implement — Structured Build Execution
+
+融合 Superpowers executing-plans（计划审阅 + 隔离工作区）+ Matt Pocock implement（TDD 接缝 + 增量验证 + 提交前审查）。
+
+## When to Use
+
+- Implementing work from a written spec or ticket set
+- Executing a development plan with clear deliverables
+- Building a feature with predefined success criteria
+
+## When NOT to Use
+
+- Exploratory coding / prototyping → use `prototype` skill
+- Quick one-line fixes → just fix it
+- No spec or tickets exist → use `to-tickets` or `to-spec` first
+
+---
+
+## Step 1: Load and Review
+
+### 1.1 Ensure isolated workspace
+
+Use git worktree or a feature branch. Never implement on main/master without explicit consent.
+
+### 1.2 Read the plan/spec/tickets
+
+Read the full spec or ticket set. Understand:
+
+- What is being built?
+- What are the acceptance criteria?
+- What are the pre-agreed seams (where TDD should be applied)?
+
+### 1.3 Review critically
+
+Before writing any code:
+
+- Are there gaps or ambiguities in the spec?
+- Are the success criteria testable?
+- Do you understand every instruction?
+
+**If concerns exist, raise them before starting.** Don't guess.
+
+---
+
+## Step 2: Execute Tasks
+
+For each task in order:
+
+### 2.1 At pre-agreed seams: TDD
+
+Where the spec specifies (or where interfaces are well-defined):
+
+1. Write a **failing test** that asserts the expected behavior
+2. Watch it fail (red)
+3. Write the **minimum code** to make it pass (green)
+4. Refactor if needed, keeping tests green
+
+Use the `tdd` skill for full red-green-refactor discipline.
+
+### 2.2 Incremental verification
+
+During implementation:
+
+- **Run typecheck** after each significant change: `pnpm typecheck`
+- **Run relevant test file** after each task: `pnpm test -- <file>`
+- **Don't wait** until everything is done to discover type errors
+
+### 2.3 One task at a time
+
+- Follow each step exactly — the plan has bite-sized steps for a reason
+- One change at a time. No "while I'm here" improvements.
+- Mark tasks as complete after verification passes
+
+---
+
+## Step 3: Final Verification
+
+After all tasks are complete:
+
+### 3.1 Full test suite
+
+```bash
+pnpm test
+```
+
+All tests must pass. If any fail, fix before proceeding.
+
+### 3.2 Lint and format
+
+```bash
+pnpm lint
+pnpm format
+```
+
+CI must be green.
+
+---
+
+## Step 4: Code Review
+
+**Before committing**, run code review:
+
+Use the `code-review` skill for a two-axis review:
+
+- **Standards**: Does the diff follow the repo's coding standards?
+- **Spec**: Does it faithfully implement the originating issue/spec?
+
+Fix any findings before committing.
+
+---
+
+## Step 5: Commit
+
+Commit your work to the current branch.
+
+```bash
+git add -A
+git commit -m "<type>: <description>"
+```
+
+- Follow Conventional Commits
+- Reference the spec/ticket in the commit message
+- **Do NOT commit unless explicitly asked** (per CLAUDE.md §关键约束)
+
+---
+
+## When to Stop and Ask
+
+**STOP immediately when:**
+
+- A task is blocked (missing dependency, unclear instruction, verification fails repeatedly)
+- The spec has a critical gap that prevents starting
+- You don't understand an instruction
+- 3+ fix attempts fail — this may be an architectural issue
+
+**Ask for clarification rather than guessing.**
+
+---
+
+## Quick Reference
+
+| Step           | Key Activities                                               | Done When                        |
+| -------------- | ------------------------------------------------------------ | -------------------------------- |
+| **1. Review**  | Load spec, isolate workspace, review critically              | All concerns raised and resolved |
+| **2. Execute** | TDD at seams, incremental typecheck/test, one task at a time | All tasks complete and verified  |
+| **3. Verify**  | Full test suite, lint, format                                | CI-ready (all green)             |
+| **4. Review**  | Two-axis code review (standards + spec)                      | Findings addressed               |
+| **5. Commit**  | Conventional Commits, reference spec/ticket                  | Work committed to branch         |

package/skills/standard/research.SKILL.md

@@ -0,0 +1,147 @@
+---
+name: research
+description: Deep research against primary sources, executed as a background agent. Collects findings into a single cited Markdown file. Use for investigation that requires reading official docs, source code, specs, or first-party APIs — not secondary summaries.
+version: 1.0.0
+user-invocable: true
+allowed-tools:
+  - WebSearch
+  - WebFetch
+  - Agent
+  - Bash
+  - Write
+  - Read
+---
+
+# Research — Background Deep Research
+
+融合 Mipham web-search v3.0（查询构建+验证）+ Matt Pocock research（后台代理+一手来源+Markdown 报告）。
+
+## When to Use
+
+- "Research X for me"
+- "Find out everything about Y from primary sources"
+- "Investigate Z and write up findings"
+- Any question where googling + reading multiple sources is the right answer
+
+## When NOT to Use
+
+- Quick fact lookup → use `/web-search` directly
+- Question answerable from code already in context
+- Pure logic/algorithmic question
+
+---
+
+## Phase 0: Route
+
+```
+Research task is...
+├── Quick (1-2 sources, immediate answer)?
+│   └── → Use web-search skill directly (Phase 0-4)
+│
+├── Deep (multiple sources, needs synthesis)?
+│   └── → THIS SKILL — background agent
+│
+└── Login-walled / SPA-only sources?
+    └── → web-access skill (ComputerUse browser)
+```
+
+---
+
+## Phase 1: Spin Up Background Agent
+
+Launch a **background agent** to do the heavy reading, so you keep working while it researches.
+
+The agent's instructions:
+
+```
+You are a research agent. Your task:
+
+1. Investigate the question against PRIMARY SOURCES ONLY:
+   - Official documentation (docs.*.com, *.org)
+   - Source code repositories (GitHub, GitLab)
+   - Technical specifications (RFCs, standards)
+   - First-party API references
+   - NOT: blog posts, Medium articles, forum threads, secondary summaries
+
+2. For every claim, follow it back to the source that owns it.
+   If a secondary source makes a claim, find the primary source and cite that.
+
+3. Use WebSearch to find sources.
+   Use WebFetch to deep-read promising pages.
+   Cross-reference critical claims across 2+ independent primary sources.
+
+4. Write findings to a SINGLE Markdown file.
+   - Cite every claim with its primary source URL
+   - Distinguish between facts (needs citation) and reasoning (your own)
+   - Flag outdated content ("article from 2024, may be stale")
+   - Note if a source is official docs vs community
+
+5. Save the file where the repo already keeps such notes.
+   Match existing conventions. If none exist, put it in docs/research/.
+```
+
+---
+
+## Phase 2: Report Format
+
+The agent writes findings in this structure:
+
+```markdown
+# [Research Topic]
+
+**Date**: YYYY-MM-DD
+**Sources**: N primary, M cross-references
+
+## Key Findings
+
+- [Finding 1] — [Source](URL)
+- [Finding 2] — [Source](URL)
+
+## Detailed Analysis
+
+### [Subtopic A]
+
+[Claim and citation]
+
+### [Subtopic B]
+
+[Claim and citation]
+
+## Source Evaluation
+
+| Source      | Type          | Authority | Notes                 |
+| ----------- | ------------- | --------- | --------------------- |
+| [Name](URL) | Official docs | High      | Current as of YYYY-MM |
+| [Name](URL) | Source code   | High      | Tag vX.Y.Z            |
+
+## Open Questions
+
+- [Question 1]
+- [Question 2]
+
+Sources:
+
+- [Title](URL) — brief note
+```
+
+---
+
+## Phase 3: Review
+
+When the background agent completes:
+
+1. Read the output file
+2. Spot-check: did it follow the chain back to primary sources?
+3. Flag any claims that need further verification
+4. Surface uncertainties to the user
+
+---
+
+## Research Quality Checklist
+
+- [ ] Every factual claim has a primary source citation
+- [ ] At least one critical claim is cross-referenced (2+ sources)
+- [ ] Source type is clearly identified (official docs / source code / spec / community)
+- [ ] Outdated content is flagged with publication year
+- [ ] Reasoning vs facts are clearly distinguished
+- [ ] File saved in repo-appropriate location

package/skills/standard/systematic-debugging.SKILL.md

@@ -0,0 +1,236 @@
+---
+name: debug-loop
+description: Enhanced diagnosis with feedback loop construction (10 methods) — build a tight red/green signal, minimize, falsifiable hypotheses, tagged instrumentation, seam assessment, post-mortem. Complements systematic-debugging. Use together for thorough debugging.
+version: 1.0.0
+---
+
+# Debug Loop — 反馈闭环诊断
+
+融合 Matt Pocock diagnosing-bugs（反馈闭环方法论）+ Superpowers systematic-debugging（反猜測紀律）。
+
+> **与 `systematic-debugging` 互补**：systematic-debugging 侧重反猜測纪律和根因分析框架；debug-loop 侧重构建可执行的红绿反馈信号。两者配合使用效果最佳。
+
+## The Iron Law
+
+```
+NO FIXES WITHOUT ROOT CAUSE INVESTIGATION FIRST.
+NO HYPOTHESIS WITHOUT A RED-CAPABLE FEEDBACK LOOP FIRST.
+```
+
+---
+
+## Phase 0: Decide Whether to Use This Skill
+
+```
+Issue is...
+├── Test failure?            → USE THIS SKILL
+├── Bug in production?       → USE THIS SKILL
+├── Performance regression?  → USE THIS SKILL
+├── Build/integration break? → USE THIS SKILL
+├── "It's probably X, quick fix" → USE THIS SKILL (especially now)
+└── Trivial typo/syntax?     → fix directly (but still verify)
+```
+
+---
+
+## Phase 1: Build a Feedback Loop 🔴 THE SKILL
+
+**This is the centerpiece.** A tight pass/fail signal for the bug — one that goes red on _this_ bug — makes everything else mechanical. No loop = no debugging, only guessing.
+
+Spend disproportionate effort here. Be aggressive. Be creative. Refuse to give up.
+
+### 1.1 Ways to construct one (try in roughly this order)
+
+1. **Failing test** at whatever seam reaches the bug — unit, integration, e2e.
+2. **Curl / HTTP script** against a running dev server.
+3. **CLI invocation** with fixture input, diffing stdout against known-good snapshot.
+4. **Headless browser script** (Playwright/Puppeteer) — drives UI, asserts on DOM/console/network.
+5. **Replay a captured trace.** Save a real network request/payload/event log to disk; replay through the code path in isolation.
+6. **Throwaway harness.** Spin up minimal subset of the system (one service, mocked deps) that exercises the bug path with a single function call.
+7. **Property/fuzz loop.** If "sometimes wrong output", run 1000 random inputs and look for the failure mode.
+8. **Bisection harness.** Automate "boot at state X, check, repeat" so you can `git bisect run` it.
+9. **Differential loop.** Run same input through old-version vs new-version and diff outputs.
+10. **Multi-component evidence gathering.** For systems with multiple layers:
+    ```
+    For EACH component boundary:
+      - Log what data enters
+      - Log what data exits
+      - Verify environment/config propagation
+      - Check state at each layer
+
+    Run once to identify WHICH layer fails, THEN investigate that component.
+    ```
+
+### 1.2 Tighten the loop
+
+Once you have _a_ loop, make it tighter:
+
+- **Faster**: Cache setup, skip unrelated init, narrow test scope.
+- **Sharper signal**: Assert on the specific symptom, not "didn't crash".
+- **More deterministic**: Pin time, seed RNG, isolate filesystem, freeze network.
+
+A 30-second flaky loop is barely better than no loop; a 2-second deterministic one is a superpower.
+
+### 1.3 Non-deterministic bugs
+
+Goal: higher reproduction rate (not clean repro). Loop 100×, parallelise, add stress, narrow timing windows, inject sleeps. A 50%-flake is debuggable; 1% is not — keep raising it.
+
+### 1.4 When you genuinely cannot build a loop
+
+Stop explicitly. List everything tried. Ask for: (a) access to the reproducing environment, (b) a redacted captured artifact (HAR file, log dump, core dump, screen recording with timestamps), or (c) permission to add temporary production instrumentation. **Do not proceed without a loop.**
+
+### 1.5 Completion criterion
+
+Phase 1 is done when the loop is **tight** and **red-capable**:
+
+- [ ] **Red-capable** — drives the actual bug path and asserts the user's exact symptom. Not "runs without erroring".
+- [ ] **Deterministic** — same verdict every run.
+- [ ] **Fast** — seconds, not minutes.
+- [ ] **Agent-runnable** — you can run it unattended.
+
+> If you catch yourself reading code to build a theory before this loop exists — **STOP.** No red-capable command, no Phase 2.
+
+---
+
+## Phase 2: Reproduce + Minimise
+
+### 2.1 Reproduce
+
+Run the loop. Watch it go red.
+
+- [ ] The loop produces the failure mode the **user** described — not a different nearby failure.
+- [ ] The failure is reproducible (or, for flaky bugs, at a high enough rate).
+- [ ] You have captured the exact symptom so later phases can verify the fix.
+
+### 2.2 Minimise
+
+Shrink the repro to the **smallest scenario that still goes red**. Cut inputs, callers, config, data, and steps **one at a time**, re-running the loop after each cut.
+
+**Why**: A minimal repro shrinks the hypothesis space and becomes the clean regression test in Phase 5.
+
+Done when **every remaining element is load-bearing** — removing any one makes the loop go green.
+
+---
+
+## Phase 3: Pattern Analysis + Hypothesise
+
+### 3.1 Pattern Analysis
+
+Before forming hypotheses:
+
+- Find similar **working** code in the same codebase.
+- Read the reference implementation completely — don't skim.
+- List every difference between working and broken, however small.
+- Understand dependencies, config, environment, assumptions.
+
+### 3.2 Generate 3-5 Ranked Hypotheses
+
+Generate multiple hypotheses **before testing any**. Single-hypothesis generation anchors on the first plausible idea.
+
+Each hypothesis must be **falsifiable**:
+
+> "If <X> is the cause, then <changing Y> will make the bug disappear / <changing Z> will make it worse."
+
+If you cannot state the prediction, the hypothesis is a vibe — discard or sharpen it.
+
+**Show the ranked list to the user before testing.** They often have domain knowledge that re-ranks instantly. Don't block on it if they're AFK.
+
+---
+
+## Phase 4: Instrument
+
+Each probe must map to a specific Phase 3 prediction. **Change one variable at a time.**
+
+Tool preference:
+
+1. **Debugger/REPL** — one breakpoint beats ten logs.
+2. **Targeted logs** at boundaries that distinguish hypotheses.
+3. Never "log everything and grep".
+
+**Tag every debug log** with a unique prefix, e.g. `[DEBUG-a4f2]`. Cleanup at the end becomes a single grep. Untagged logs survive; tagged logs die.
+
+**Perf branch**: For performance regressions, establish a baseline measurement first (timing harness, profiler, query plan), then bisect. Measure first, fix second.
+
+---
+
+## Phase 5: Fix + Regression Test
+
+### 5.1 Seam Assessment
+
+Write the regression test **before the fix** — but only if there is a **correct seam**:
+
+A correct seam exercises the **real bug pattern** at the call site. If the only available seam is too shallow (single-caller test when the bug needs multiple callers), a regression test there gives false confidence.
+
+**If no correct seam exists, that itself is the finding.** Note it. The architecture is preventing the bug from being locked down.
+
+### 5.2 If a correct seam exists
+
+1. Turn the minimised repro into a failing test at that seam.
+2. Watch it fail.
+3. Apply the fix — **ONE change at a time**.
+4. Watch it pass.
+5. Re-run the Phase 1 feedback loop against the original (un-minimised) scenario.
+
+### 5.3 If Fix Doesn't Work
+
+- Try #1 failed? → Return to Phase 3, form new hypothesis.
+- Try #2 failed? → Return to Phase 1, re-check the loop.
+- **If 3+ fixes failed: STOP.** This is an architectural problem, not a bug:
+  - Each fix reveals new problems in different places.
+  - Fixes require "massive refactoring" to implement.
+  - **Question the architecture, not the symptom.**
+  - Discuss with your human partner before attempting more fixes.
+
+---
+
+## Phase 6: Cleanup + Post-Mortem
+
+Required before declaring done:
+
+- [ ] Original repro no longer reproduces (re-run Phase 1 loop)
+- [ ] Regression test passes (or absence of seam is documented)
+- [ ] All `[DEBUG-...]` instrumentation removed (`grep` the prefix)
+- [ ] Throwaway prototypes deleted (or moved to a clearly-marked debug location)
+- [ ] The correct hypothesis is stated in the commit/PR message
+
+**Then ask: what would have prevented this bug?** If architectural change would have prevented it, note the specifics. You have more information now than when you started.
+
+---
+
+## Red Flags — STOP Immediately
+
+If you catch yourself thinking:
+
+| Thought                                        | Reality                                                    |
+| ---------------------------------------------- | ---------------------------------------------------------- |
+| "Quick fix for now, investigate later"         | First fix sets the pattern. Do it right.                   |
+| "Just try changing X and see if it works"      | Guessing. Build a loop instead (Phase 1).                  |
+| "Add multiple changes, run tests"              | Can't isolate what worked. One variable at a time.         |
+| "Skip the test, I'll verify manually"          | Untested fixes don't stick.                                |
+| "It's probably X, let me fix that"             | Seeing symptoms ≠ understanding root cause.                |
+| "I don't fully understand but this might work" | Return to Phase 1.                                         |
+| "Reference too long, I'll adapt the pattern"   | Partial understanding guarantees bugs. Read it completely. |
+| "One more fix attempt" (after 2+ failures)     | 3+ failures = architectural problem. Question the pattern. |
+
+**ALL of these mean: STOP. Return to the earliest incomplete Phase.**
+
+---
+
+## Quick Reference
+
+| Phase                      | Key Activities                                            | Success Criteria                               |
+| -------------------------- | --------------------------------------------------------- | ---------------------------------------------- |
+| **1. Feedback Loop**       | Build tight red/green signal for the bug                  | Deterministic, fast, agent-runnable            |
+| **2. Reproduce+Minimise**  | Confirm + shrink to smallest load-bearing scenario        | Every element is load-bearing                  |
+| **3. Pattern+Hypothesise** | Compare working examples, rank 3-5 falsifiable hypotheses | Each hypothesis has a testable prediction      |
+| **4. Instrument**          | One probe per prediction, tagged logs                     | Identify which hypothesis holds                |
+| **5. Fix+Regression**      | Assess seam → test → single fix → verify                  | Bug resolved, test passes, original loop green |
+| **6. Cleanup+Post-Mortem** | Remove instrumentation, document cause                    | Preventative insight captured                  |
+
+---
+
+## Supporting Techniques
+
+- **Root Cause Tracing**: Trace bug backward through call stack to find original trigger. Where does the bad value originate? Keep tracing up.
+- **Defense in Depth**: After fixing root cause, add validation at multiple layers so this class of bug can't recur.
+- **Condition-Based Waiting**: Replace arbitrary timeouts (`sleep(5)`) with condition polling (`waitFor(selector)`).