@miphamai/cli 0.25.0 → 0.27.0

package/package.json

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

package/skills/standard/codebase-design.SKILL.md

@@ -0,0 +1,189 @@
+---
+name: codebase-design
+description: Deep module design principles for designing or improving module interfaces. Use when designing a new module, refactoring an existing one, or finding deepening opportunities in the codebase.
+version: 1.0.0
+user-invocable: true
+allowed-tools:
+  - Read
+  - Glob
+  - Grep
+  - Edit
+  - Write
+---
+
+# Codebase Design — Deep Module Principles
+
+Based on John Ousterhout's "A Philosophy of Software Design." The core idea: the greatest single factor in software complexity is the depth of modules — how much functionality they provide relative to the size of their interface.
+
+## When to Use
+
+- Designing a new module, API, or component
+- Reviewing existing code for design quality
+- Deciding where to split or join modules
+- User asks: "is this well-designed?", "where should this go?", "how should I structure this?"
+
+---
+
+## Core Concepts
+
+### Deep vs Shallow Modules
+
+```
+Deep Module (good):            Shallow Module (bad):
+┌─────────────────┐            ┌─────────────────┐
+│ small interface  │            │ large interface  │
+│ ┌─────────────┐ │            │ (many params,    │
+│ │             │ │            │  complex setup)  │
+│ │   large     │ │            ├─────────────────┤
+│ │ implementation│            │ small            │
+│ │             │ │            │ implementation   │
+│ └─────────────┘ │            │ (just passes     │
+└─────────────────┘            │  through)        │
+                               └─────────────────┘
+```
+
+**Deep**: Unix file I/O — 5 syscalls (`open`, `read`, `write`, `lseek`, `close`), incredibly powerful implementation.
+
+**Shallow**: A function that takes 12 parameters, validates 3 of them, then calls another function. Interface cost > implementation value.
+
+### The Rule of Deep Modules
+
+> The interface should be as small as possible while providing as much functionality as possible.
+
+- **Cost** = interface complexity (parameters, configuration, setup required)
+- **Benefit** = functionality provided (what the caller no longer needs to worry about)
+- **Depth** = Benefit / Cost
+
+---
+
+## The 5 Design Checks
+
+When evaluating a module design, run through these:
+
+### Check 1: Interface Size
+
+Count the effective parameters:
+
+- Required parameters + optional parameters with non-trivial defaults
+- Configuration methods that MUST be called before use
+- Implicit dependencies (global state, env vars, singletons)
+
+**Red flag**: > 4 effective parameters → the module may be too shallow.
+
+**Fix**: Bundle related parameters into a config object. Or split the module.
+
+### Check 2: Information Hiding
+
+Does the module expose information that callers don't need?
+
+- Internal data structures leaked through the interface
+- Implementation details exposed via parameter types
+- Error types that reveal internal architecture
+
+**Red flag**: Callers import types they don't use directly.
+
+**Fix**: Define a public API type layer. Return opaque handles instead of raw data.
+
+### Check 3: Abstraction Quality
+
+Does the module represent a single, coherent idea?
+
+- Can you describe what it does in one sentence without "and"?
+- Would a new team member guess where to find this functionality?
+- If you remove the module, does exactly one concept go missing?
+
+**Red flag**: Module name contains "and", "Utils", "Common", "Helpers".
+
+**Fix**: Split by concept. `UserService` + `EmailService` instead of `UserAndEmailUtils`.
+
+### Check 4: General-Purpose vs Special-Purpose
+
+Is the module solving the general case or a specific use case?
+
+- Would the interface work if requirements changed slightly?
+- Are there hardcoded assumptions that could be parameters?
+- Is the module useful in contexts other than its creator imagined?
+
+**Red flag**: Module only works for one specific call site.
+
+**Fix**: Make the specific case a thin wrapper around the general case. The general module is deep; the wrapper is shallow (and that's fine — wrappers are allowed to be shallow).
+
+### Check 5: Seam Placement
+
+Where you split modules matters as much as what they do.
+
+- Does the split happen at a natural boundary?
+- Are there circular dependencies across the seam?
+- Can each side be tested independently?
+
+**Red flag**: Circular imports, or modules that are always imported together.
+
+**Fix**: Use dependency inversion. Define interfaces at the seam, not implementations.
+
+---
+
+## Finding Deepening Opportunities
+
+Scan the codebase for these patterns:
+
+### Shallow Pass-Through
+
+```typescript
+// Shallow — just delegates with no added value
+function getUser(id: string) {
+  return db.findUser(id)
+}
+
+// Deep — handles errors, caching, authorization in one call
+function getUser(id: string, ctx: RequestContext) {
+  const cached = cache.get(`user:${id}`)
+  if (cached) return cached
+  ctx.auth.assertCanRead('user', id)
+  const user = db.findUser(id)
+  if (!user) throw new NotFoundError('User', id)
+  cache.set(`user:${id}`, user)
+  return user
+}
+```
+
+### Temporal Decomposition
+
+When a module's methods must be called in a specific order, the interface is too wide.
+
+```typescript
+// Shallow — caller manages lifecycle
+const conn = new Connection()
+conn.open()
+conn.authenticate(token)
+conn.send(data)
+conn.close()
+
+// Deep — module manages lifecycle
+const conn = await Connection.create(token)
+conn.send(data)
+// clean up automatically
+```
+
+### Overexposure
+
+When internal types leak through the public API:
+
+```typescript
+// Shallow — exposes ORM internals
+interface UserService {
+  findUser(id: string): Promise<PrismaUser | null> // ❌ PrismaUser is internal
+}
+
+// Deep — owns its types
+interface UserService {
+  findUser(id: string): Promise<User | null> // ✅ User is a domain type
+}
+```
+
+---
+
+## Integration With Mipham Code
+
+- **code-review**: This skill fills the architecture dimension that code-review's 7 dimensions don't cover. Use `/code-review` for correctness/security/perf; use `/codebase-design` for interface depth/abstraction quality/seam placement.
+- **domain-modeling**: Good domain modeling makes deep modules easier — the CONTEXT.md glossary defines the concepts that modules should represent.
+- **Critical Thinking Layer**: The counter-example search applies directly: "what would break if I changed the implementation of this module?"

package/skills/standard/domain-modeling.SKILL.md

@@ -0,0 +1,129 @@
+---
+name: domain-modeling
+description: Build and sharpen a project's domain model. Use when the user wants to pin down domain terminology or a ubiquitous language, record an architectural decision, or when another skill needs to maintain the domain model.
+version: 1.0.0
+user-invocable: true
+allowed-tools:
+  - Read
+  - Write
+  - Edit
+  - Glob
+  - Grep
+---
+
+# Domain Modeling — Continuous Shared Language
+
+Actively build and sharpen the project's domain model as you work. This is the _active_ discipline — challenging terms, inventing edge-case scenarios, and writing the glossary and decisions down the moment they crystallize. (Merely _reading_ `CONTEXT.md` for vocabulary is not this skill — that's a one-line habit any skill can do. This skill is for when you're changing the model, not just consuming it.)
+
+## File Structure
+
+```
+/
+├── CONTEXT.md              ← shared language glossary
+├── docs/
+│   └── adr/
+│       ├── 0001-slug.md    ← architectural decisions
+│       └── 0002-slug.md
+└── src/
+```
+
+Create files lazily — only when you have something to write.
+
+**Multiple contexts**: If a `CONTEXT-MAP.md` exists, read it to find which context the current topic relates to.
+
+---
+
+## During the Session
+
+### Challenge Against the Glossary
+
+When the user uses a term that conflicts with existing language in `CONTEXT.md`, call it out immediately:
+
+> "Your glossary defines 'cancellation' as X, but you seem to mean Y — which is it?"
+
+### Sharpen Fuzzy Language
+
+When the user uses vague or overloaded terms, propose a precise canonical term:
+
+> "You're saying 'account' — do you mean the Customer or the User? Those are different things."
+
+### Discuss Concrete Scenarios
+
+When domain relationships are discussed, stress-test them with specific scenarios. Invent scenarios that probe edge cases and force precision about boundaries between concepts.
+
+### Cross-Reference With Code
+
+When the user states how something works, check whether the code agrees. Surface contradictions:
+
+> "Your code cancels entire Orders, but you just said partial cancellation is possible — which is right?"
+
+### Update CONTEXT.md Inline
+
+When a term is resolved, update `CONTEXT.md` right there. Don't batch — capture as they happen.
+
+### Offer ADRs Sparingly
+
+Only create an ADR when ALL three are true:
+
+1. **Hard to reverse** — changing your mind later has real cost
+2. **Surprising without context** — a future reader would wonder "why?"
+3. **The result of a real trade-off** — there were genuine alternatives
+
+---
+
+## CONTEXT.md Format
+
+```markdown
+# {Context Name}
+
+{One or two sentence description of what this context is and why it exists.}
+
+## Language
+
+**{Term}**:
+{One or two sentence definition of what it IS.}
+_Avoid_: {alternative terms that should not be used}
+```
+
+### Rules
+
+- **Be opinionated.** Pick the best term, ban the rest.
+- **Keep definitions tight.** One or two sentences max.
+- **Only domain-specific terms.** Not general programming concepts.
+- **Group under subheadings** when natural clusters emerge.
+
+---
+
+## ADR Format
+
+```markdown
+# {Short title of the decision}
+
+{1-3 sentences: context, decision, and why.}
+```
+
+Number sequentially (`docs/adr/0001-slug.md`, `0002-slug.md`, ...).
+
+Optional sections (only when they add value):
+
+- **Status** frontmatter: `proposed | accepted | deprecated | superseded by ADR-NNNN`
+- **Considered Options**: rejected alternatives worth remembering
+- **Consequences**: non-obvious downstream effects
+
+### When an ADR Qualifies
+
+- Architecture shape (monorepo, event sourcing, microservices)
+- Integration patterns between contexts
+- Technology choices with lock-in (database, message bus, auth)
+- Boundary and scope decisions ("X owns Y, Z references by ID only")
+- Deliberate deviations from convention
+- Constraints not visible in code (compliance, latency SLA)
+- Rejected alternatives when non-obvious (stops someone suggesting it again in 6 months)
+
+---
+
+## Integration With Mipham Code
+
+- **Memory System**: Domain terms discovered through this skill persist to project memory
+- **grill-with-docs**: For initial domain establishment, use `/grill-with-docs`. This skill handles ongoing maintenance
+- **Critical Thinking Layer**: Apply counter-example search to domain definitions — "does this definition hold for all edge cases?"

package/skills/standard/grill-with-docs.SKILL.md

@@ -0,0 +1,199 @@
+---
+name: grill-with-docs
+description: A relentless interview to sharpen a plan or design, creating CONTEXT.md (shared language) and ADRs (architectural decisions) as we go. Use before any non-trivial implementation to align on requirements and terminology.
+version: 1.0.0
+user-invocable: true
+allowed-tools:
+  - Read
+  - Write
+  - Edit
+  - Bash
+  - Glob
+  - Grep
+  - WebSearch
+  - WebFetch
+---
+
+# Grill With Docs — Deep Requirements Alignment
+
+Inspired by Matt Pocock's `grill-with-docs` and `domain-modeling` skills. Before writing code, run a structured interview to align on requirements, establish shared language, and record architectural decisions.
+
+## When to Use
+
+- Before any non-trivial feature implementation
+- When requirements are fuzzy ("make it faster", "add X")
+- When you need to establish project terminology
+- When architectural decisions need to be recorded
+- User says: "plan X", "design Y", "what should we do about Z"
+
+## When NOT to Use
+
+- Trivial bug fixes with clear expected behavior
+- One-line changes
+- Tasks where the requirements are already crystal clear
+
+---
+
+## The Interview Flow
+
+### Phase 1: Understand the Intent
+
+Start by understanding what the user actually wants. Don't ask "what should I build?" — ask about their goal.
+
+**Core Questions:**
+
+1. What problem are you solving? (Not what feature you're building)
+2. Who is this for? (End user, developer, internal tool?)
+3. What does success look like? (How will you know when it's done?)
+4. What's the deadline or priority context?
+
+**Anti-pattern**: Jumping to implementation questions ("Do you want REST or GraphQL?") before understanding the problem.
+
+### Phase 2: Sharpen the Language
+
+Identify vague or overloaded terms and pin them down **immediately**. This is the single highest-leverage activity — shared language reduces token waste and prevents misunderstandings.
+
+**Technique: The Canonical Term**
+
+- When the user uses multiple words for the same thing, pick one as canonical
+- List rejected alternatives under `_Avoid_`
+- Be opinionated — the glossary is prescriptive, not descriptive
+
+```
+User: "We need a way for users to save articles for later."
+You: "Let's pin that down. 'Save for later' could mean bookmarking, or a reading list, or offline download. Which one?"
+User: "Like a reading list — they can come back to it."
+You: "Got it. Let's call it a **Reading List**. Avoid 'bookmark', 'save', 'favorites'."
+→ Write to CONTEXT.md immediately.
+```
+
+**Technique: The Boundary Test**
+
+- When a term is proposed, test its boundaries with edge cases
+- "Does X include Y? What about Z?"
+
+**Technique: The Code Cross-Reference**
+
+- When the user describes how something works, check if existing code agrees
+- Surface contradictions immediately
+
+### Phase 3: Probe Edge Cases
+
+Before accepting any requirement, stress-test it with edge cases.
+
+**Edge Case Inventory:**
+
+- **Empty state**: What does the user see when there's nothing yet?
+- **Error state**: What happens when things go wrong?
+- **Extreme values**: What about 0? What about 10,000?
+- **Concurrency**: What if two people do this at the same time?
+- **Permissions**: Who can do this? Who cannot?
+- **Scale**: What changes at 10x the current volume?
+
+**Technique: The 5 Whys**
+When a requirement seems odd, dig deeper:
+
+```
+User: "We need real-time updates."
+You: "Why real-time?"
+User: "Because users need to see changes immediately."
+You: "Why do they need to see changes immediately?"
+User: "Because they're collaborating on the same document."
+→ Now you know the REAL requirement is collaboration, not real-time.
+```
+
+### Phase 4: Make Architecture Decisions
+
+When a design decision meets ALL three criteria, offer to record it as an ADR:
+
+1. **Hard to reverse** — changing your mind later has real cost
+2. **Surprising without context** — a future reader would wonder "why?"
+3. **The result of a real trade-off** — there were genuine alternatives
+
+**What qualifies for an ADR:**
+
+- Architecture shape (monorepo vs polyrepo, event sourcing vs CRUD)
+- Integration patterns between contexts
+- Technology choices with lock-in (database, message bus, auth provider)
+- Deliberate deviations from convention ("we use raw SQL because...")
+- Constraints not visible in code ("we can't use X because compliance")
+
+**ADR Format** (write to `docs/adr/NNNN-slug.md`):
+
+```markdown
+# {Short title of the decision}
+
+{1-3 sentences: context, decision, and why.}
+```
+
+Only add optional sections (Status, Considered Options, Consequences) when they add genuine value. Most ADRs are a single paragraph.
+
+### Phase 5: Write the CONTEXT.md
+
+After the interview, synthesize everything into `CONTEXT.md`.
+
+**Format** (`CONTEXT.md` at project root):
+
+```markdown
+# {Project Name} Context
+
+{One or two sentence description of the project domain.}
+
+## Language
+
+**{Term}**:
+{One or two sentence definition of what it IS.}
+_Avoid_: {alternative terms that should not be used}
+
+## Decisions
+
+- [ADR 0001: {Title}](docs/adr/0001-slug.md) — {one-line summary}
+```
+
+**Rules:**
+
+- Be opinionated — pick the best term, ban the rest
+- Only include domain-specific terms (not general programming concepts)
+- Keep definitions tight — one or two sentences
+- Update inline during the conversation, don't batch
+- CONTEXT.md is a glossary, NOT a spec or implementation plan
+
+---
+
+## During the Conversation
+
+### DO
+
+- Challenge the user when they use vague terms — "What do you mean by 'fast'?"
+- Propose canonical terms and write them down immediately
+- Invent edge cases and probe boundaries
+- Offer ADRs sparingly (only when all 3 criteria are met)
+- Cross-reference with existing code if available
+- Call out contradictions between what the user says and what the code does
+
+### DON'T
+
+- Rush to implementation questions before understanding the problem
+- Write ADRs for trivial decisions
+- Let fuzzy language slide — pin it down now or pay later
+- Treat CONTEXT.md as a spec or scratch pad
+- Ask yes/no questions when open-ended ones would reveal more
+
+---
+
+## Output
+
+After the interview, the user should have:
+
+1. **CONTEXT.md** — shared language glossary (created or updated)
+2. **ADRs** (if needed) — architectural decisions in `docs/adr/`
+3. **Clear requirements** — edge cases explored, assumptions surfaced
+4. **Shared understanding** — you and the user now mean the same thing by the same words
+
+---
+
+## Integration with Mipham Code
+
+- **Memory System**: Key terms go to project memory for persistence across sessions
+- **Critical Thinking Layer**: Apply the 5-dimension self-check (evidence standard, equivalence verification, counter-example search, confidence calibration, depth check) to your own interview questions
+- **Workflow**: For complex projects, the output of this skill feeds directly into `/implement`

package/skills/standard/to-spec.SKILL.md

@@ -0,0 +1,138 @@
+---
+name: to-spec
+description: Turn a conversation into a structured specification document. Use after a grill-with-docs session or any requirements discussion to capture decisions in a durable, shareable format.
+version: 1.0.0
+user-invocable: true
+allowed-tools:
+  - Read
+  - Write
+  - Edit
+  - Bash
+---
+
+# To Spec — Conversation → Specification
+
+Turn the output of a requirements discussion into a structured specification document. This is the bridge between `/grill-with-docs` (alignment) and `/triage` (task decomposition).
+
+## When to Use
+
+- After a `/grill-with-docs` session — capture what was decided
+- After any requirements discussion — before starting implementation
+- User asks: "write this up", "create a spec", "document the plan"
+- Before handing off work to another session or person
+
+## When NOT to Use
+
+- The requirements are a single sentence and obvious
+- You're in the middle of a grill session — finish the interview first
+- The scope is so small that the spec would be longer than the implementation
+
+---
+
+## Spec Format
+
+Write to `docs/specs/YYYY-MM-DD-slug.md`:
+
+```markdown
+---
+status: draft | approved | implemented
+created: 2026-08-10
+---
+
+# {Title}
+
+## Problem
+
+{What problem are we solving? Why now? 1-3 sentences.}
+
+## Scope
+
+### In Scope
+
+- {What we're building}
+
+### Out of Scope (Explicit)
+
+- {What we're NOT building — prevents scope creep}
+
+## Requirements
+
+### Functional
+
+- **{Requirement}**: {Description}. Acceptance: {measurable criterion}.
+
+### Non-Functional
+
+- **Performance**: {latency, throughput targets}
+- **Security**: {auth, data protection, threat model}
+- **Scale**: {expected volume, growth projections}
+
+## Design Decisions
+
+- **Decision**: {What we decided}. Because: {why}. Alternatives considered: {options + reasons rejected}.
+
+## Domain Model
+
+{Key terms and their definitions — from CONTEXT.md or the grill session.}
+
+## Edge Cases
+
+- **{Scenario}**: {Expected behavior}
+- **{Scenario}**: {Expected behavior}
+
+## Open Questions
+
+- {Question} — {who needs to answer / when needed}
+```
+
+---
+
+## The Spec Workflow
+
+### Step 1: Extract from Conversation
+
+Scan the conversation history for:
+
+- Decisions made (explicit and implicit)
+- Terms defined (candidates for CONTEXT.md)
+- Edge cases discussed
+- Alternatives rejected (and why)
+- Open questions that remain
+
+### Step 2: Fill Gaps
+
+For each gap you find:
+
+- Edge cases not discussed → flag as Open Questions
+- Terms used but not defined → propose definitions
+- Assumptions not stated → make them explicit
+
+### Step 3: Validate with User
+
+Present the spec and ask:
+
+1. "Does this match your understanding?"
+2. "What's missing?"
+3. "What's wrong?"
+4. "What surprised you?"
+
+### Step 4: Feed Into Triage
+
+Once approved, the spec's functional requirements become tickets in `/triage`. Non-functional requirements become acceptance criteria.
+
+---
+
+## Anti-Patterns
+
+- **Waterfall trap**: Don't try to spec everything upfront. Spec the next increment. Specs are living documents, not contracts.
+- **Premature detail**: Don't spec API signatures or DB schemas in the spec — those are implementation details.
+- **Vague acceptance**: "Works well" is not acceptance criteria. "Returns 200 with valid JWT within 500ms" is.
+
+---
+
+## Integration With Mipham Code
+
+- **grill-with-docs**: Input — the grill session produces the raw material
+- **triage**: Output — the spec feeds into ticket decomposition
+- **domain-modeling**: Terms discovered during spec writing go to CONTEXT.md
+- **Memory System**: The spec file persists as project reference across sessions

package/skills/standard/triage.SKILL.md

@@ -0,0 +1,155 @@
+---
+name: triage
+description: Structured task decomposition and tracking across sessions. Use for breaking complex plans into trackable tickets with dependency graphs, checking task status, or continuing work from a previous session.
+version: 1.0.0
+user-invocable: true
+allowed-tools:
+  - Read
+  - Write
+  - Edit
+  - Bash
+  - Glob
+  - Grep
+---
+
+# Triage — Cross-Session Task Tracking
+
+Turn plans into trackable tickets with dependency management. Inspired by Matt Pocock's `triage` + `to-tickets` + `wayfinder` skills, consolidated into one Mipham Code skill.
+
+## When to Use
+
+- Breaking a large plan into actionable tickets
+- Tracking work across multiple sessions
+- User asks: "what's next?", "where did I leave off?", "what's the status?"
+- Complex tasks with dependencies between them
+
+---
+
+## The Ticket Format
+
+Tickets live in `.mipham/tickets/` as individual Markdown files:
+
+```markdown
+---
+id: T-001
+title: Add user authentication
+status: in-progress
+priority: P0
+depends_on: []
+blocks: [T-003]
+created: 2026-08-10
+tags:
+  - auth
+  - backend
+---
+
+## Description
+
+Add JWT-based authentication with refresh token rotation.
+
+## Acceptance Criteria
+
+- [ ] Login endpoint returns access + refresh tokens
+- [ ] Refresh endpoint rotates tokens
+- [ ] Invalid tokens return 401
+- [ ] Rate limiting on login attempts
+
+## Notes
+
+- OAuth not in scope for T-001 (punted to T-005)
+```
+
+### Status Values
+
+| Status        | Meaning                                    |
+| ------------- | ------------------------------------------ |
+| `backlog`     | Not yet planned for any session            |
+| `planned`     | Scoped and ready to work                   |
+| `in-progress` | Currently being worked on                  |
+| `review`      | Implementation done, awaiting verification |
+| `done`        | Verified and merged                        |
+| `blocked`     | Cannot proceed due to dependency           |
+| `wontfix`     | Decided not to do                          |
+
+---
+
+## The Triage Workflow
+
+### Phase 1: Decompose (Plan → Tickets)
+
+Given a plan or feature request:
+
+1. **Identify the smallest independently-valuable units of work**
+   - Each ticket should deliver value on its own
+   - If a ticket requires 3+ files touched, it's probably too big
+   - If a ticket can be done in < 15 minutes, it's probably too small
+
+2. **Map dependencies**
+   - What must be done first? (hard dependency)
+   - What would be easier after something else? (soft dependency)
+   - What blocks other work? (reverse dependency)
+
+3. **Assign priorities**
+   - **P0**: Blocks other work, must do first
+   - **P1**: High value, should do soon
+   - **P2**: Nice to have, can defer
+   - **P3**: Optional, do if time permits
+
+4. **Write acceptance criteria**
+   - Specific, testable, unambiguous
+   - "Login works" is bad. "POST /auth/login with valid credentials returns 200 + JWT" is good.
+
+### Phase 2: Status Check
+
+When the user asks "what's next?" or "what's the status?":
+
+1. Read `.mipham/tickets/` directory
+2. Report:
+   - Currently in-progress tickets
+   - Blocked tickets (and what's blocking them)
+   - Next unblocked P0/P1 tickets ready to work
+   - Recently completed tickets (for context)
+
+### Phase 3: Session Handoff
+
+When starting a new session, check for continuity:
+
+1. Read the previous session's context from the session store
+2. Check ticket statuses — any that were `in-progress` last session?
+3. Present: "Last session you were working on T-004 (Add rate limiting). Continue from there, or start on T-007 (API docs) which is next in the P1 queue?"
+
+### Phase 4: Ticket Lifecycle
+
+When working on a ticket:
+
+- Mark it `in-progress` when you start
+- Mark it `review` when implementation is done
+- Mark it `done` after verification (tests pass, typecheck clean)
+- If you discover new dependencies, add them to `blocks`/`depends_on`
+
+---
+
+## Dependency Graph
+
+For tickets with complex dependencies, generate a visual summary:
+
+```
+T-001 (Auth) ──blocks──→ T-003 (Dashboard)
+    │                        │
+    └──blocks──→ T-002 (API) ─┘
+                     │
+                     └──soft-dep──→ T-004 (Rate Limiting)
+
+Ready to work: T-001 (no dependencies)
+Blocked: T-002 (waiting on T-001), T-003 (waiting on T-001, T-002)
+```
+
+---
+
+## Integration With Mipham Code
+
+- **Session Store**: Ticket status persists across sessions via `.mipham/tickets/`
+- **Memory System**: Active tickets are loaded as project memory for context
+- **grill-with-docs**: The output of a grill session feeds directly into ticket decomposition
+- **Background Agents**: Long-running work on a ticket can be spawned as a background agent
+- **Critical Thinking Layer**: When decomposing, ask "what's the smallest thing that delivers value?" — don't over-decompose

package/src/core/instructions.ts

@@ -71,6 +71,46 @@ export class InstructionsLoader {
       parts.push(this.skillsReminder)
     }
 
+    // Inject critical thinking self-check layer (for analysis/comparison tasks)
+    parts.push(`## Critical Thinking Self-Check
+
+Before delivering any analysis, comparison, evaluation, or "X vs Y"
+report, run this checklist internally:
+
+### 1. Evidence Standard
+- Every factual claim MUST cite a specific source (file path, URL, line number)
+- If you cannot cite a source, label the claim as [推断] (inference) or [待验证] (unverified)
+- Numbers (counts, percentages, download stats) require cross-validation from a second source
+
+### 2. Equivalence Verification
+- When you claim "A is equivalent to B" or "X has been merged from Y",
+  compare their ACTUAL implementation, not just their names or descriptions
+- If you haven't read both implementations, say "appears similar at the
+  description level; implementation equivalence not verified"
+
+### 3. Counter-Example Search
+- For each major conclusion, find at least 1 counter-example or edge case
+- If you cannot find one, state that explicitly: "No counter-example found
+  within the examined scope"
+- When comparing two systems, ask: "What does X do that Y CANNOT do?"
+  (and vice versa) — don't just list overlaps
+
+### 4. Confidence Calibration
+- Label each conclusion with confidence: [高] [中] [低]
+- [高] = verified from source code or primary documentation
+- [中] = inferred from description but not implementation-verified
+- [低] = speculative, based on naming convention or surface similarity
+
+### 5. Depth Check
+- If your analysis is based ONLY on file names and description fields,
+  you are doing surface analysis — state this limitation upfront
+- To reach depth: read at least one implementation file per comparison target
+- Ask: "What would a domain expert notice that I'm missing?"
+
+These checks are not optional for analysis tasks. Apply them before
+presenting conclusions, and surface any [低] confidence findings
+explicitly rather than burying them.`)
+
     // Inject workflow auto-generation guidance
     parts.push(`## Workflow Auto-Generation
 

package/src/core/permission.ts

@@ -9,6 +9,53 @@ import type { PermissionRuleEntry } from '../shared/index.ts'
 import { matchBashRule, compileRule } from './permission-rules'
 import { loadPermissionConfig, nextMode, clampMode, MODE_CYCLE } from './permission-config'
 
+/**
+ * Check if a Bash command is a "verification-only" command that should be
+ * auto-approved in acceptEdits mode. These are non-destructive read/check
+ * operations that form the core of the vibe coding edit→test→fix loop.
+ */
+function isVerificationCommand(input: Record<string, unknown>): boolean {
+  const cmd = (input.command as string) || ''
+  // Patterns for verification-only commands (no side effects on codebase)
+  const verifyPatterns = [
+    /\bpnpm\s+test\b/, // test runner
+    /\bpnpm\s+t\b/, // shorthand test
+    /\bpnpm\s+typecheck\b/, // type checking
+    /\bpnpm\s+lint\b/, // linting
+    /\bpnpm\s+format:check\b/, // format check
+    /\bnpm\s+test\b/, // npm test
+    /\bnpm\s+run\s+test\b/, // npm run test
+    /\bvitest\b/, // vitest runner
+    /\bjest\b/, // jest runner
+    /\btsc\s+(?!init)/, // TypeScript compiler (not tsc init)
+    /\btsc\s+--noEmit\b/, // type check only
+    /\beslint\b/, // eslint
+    /\bprettier\s+--check\b/, // prettier check
+    /\bpytest\b/, // python test runner
+    /\bruff\s+check\b/, // python linter
+    /\bcargo\s+test\b/, // rust test
+    /\bcargo\s+check\b/, // rust check
+    /\bgo\s+test\b/, // go test
+    /\bgo\s+vet\b/, // go vet
+    /\bmake\s+test\b/, // make test
+    /\bgit\s+status\b/, // git status (read-only)
+    /\bgit\s+diff\b/, // git diff (read-only)
+    /\bgit\s+log\b/, // git log (read-only)
+    /\bgit\s+branch\b/, // git branch (read-only)
+    /\bls\b/, // list files
+    /\bcat\b/, // read file
+    /\bhead\b/, // read file start
+    /\btail\b/, // read file end
+    /\bwhich\b/, // find binary
+    /\becho\b/, // print text
+    /\bnode\s+-v\b/, // node version
+    /\bpython\s+--version\b/, // python version
+    /\bwhoami\b/, // current user
+    /\bpwd\b/, // current directory
+  ]
+  return verifyPatterns.some((p) => p.test(cmd))
+}
+
 const VALID_MODES: Set<string> = new Set<string>(MODE_CYCLE)
 
 export class PermissionSystem {
@@ -276,7 +323,7 @@ export class PermissionSystem {
     }
 
     // 5. Mode baseline
-    const baseline = this.modeBaseline(tool)
+    const baseline = this.modeBaseline(tool, input)
     if (baseline !== 'mode-baseline') {
       this.checkCache.set(cacheKey, baseline)
       return baseline
@@ -323,21 +370,29 @@ export class PermissionSystem {
     return rule.pattern === tool.name || rule.compiled.test(tool.name)
   }
 
-  private modeBaseline(tool: ToolDefinition): PermissionLevel | 'mode-baseline' {
+  private modeBaseline(
+    tool: ToolDefinition,
+    input?: Record<string, unknown>,
+  ): PermissionLevel | 'mode-baseline' {
     switch (this.mode) {
       case 'default':
         // Delegate to tool.permission (backward compat)
         return 'mode-baseline'
 
       case 'acceptEdits':
-        // Reads + file edits free; Bash requires approval
-        return tool.category === 'file'
-          ? ['Bash'].includes(tool.name)
-            ? 'ask'
-            : 'bypass'
-          : tool.name === 'Bash'
-            ? 'ask'
-            : 'ask'
+        // Reads + file edits free; Bash auto-approved for verification commands
+        if (tool.category === 'file' && tool.name !== 'Bash') {
+          return 'bypass'
+        }
+        if (tool.name === 'Bash') {
+          // Vibe coding fix: auto-approve verification commands
+          // so the edit→test→fix loop isn't interrupted by permission prompts
+          if (input && isVerificationCommand(input)) {
+            return 'bypass'
+          }
+          return 'ask'
+        }
+        return 'ask'
 
       case 'plan':
         // Only reads, no writes or executes

package/src/tools/agent/enter-plan.ts

@@ -80,12 +80,12 @@ export const enterPlanModeTool: ToolDefinition = {
         '  ⚠️  All other tools — require confirmation',
         '',
         'Design your approach, explore the codebase, then:',
-        '  • Use ExitPlanMode to submit your plan for approval',
-        '  • The user will review and approve before code changes begin',
+        '  • Use ExitPlanMode to submit your plan for user review',
+        '  • Present your plan and ask for explicit approval',
+        '  • The user must say "approved" before you switch to acceptEdits mode',
         '',
-        'ExitPlanMode parameters:',
-        '  approved: true → switch to acceptEdits mode (code changes allowed)',
-        '  approved: false → revert to default mode',
+        '⚠️  You CANNOT self-approve your plan. The user must explicitly confirm.',
+        '    After ExitPlanMode, wait for user approval before making code changes.',
       ].join('\n'),
     }
   },

package/src/tools/agent/exit-plan.ts

@@ -1,53 +1,62 @@
+import { readFileSync } from 'node:fs'
+import { join } from 'node:path'
 import type { ToolDefinition } from '../../shared/index.ts'
 
 export const exitPlanModeTool: ToolDefinition = {
   name: 'ExitPlanMode',
   description:
-    'Exit plan mode and submit your plan for approval. ' +
-    'Set approved: true to switch to acceptEdits mode (code changes allowed). ' +
-    'Set approved: false to revert to default mode. ' +
-    'Use this after you have finished designing your approach in plan mode.',
+    'Exit plan mode and present your plan for user approval. ' +
+    'This tool does NOT switch to implementation mode — the user must explicitly approve first. ' +
+    'After calling this, present your plan and ask the user to confirm. ' +
+    'The user can approve by saying "approved" or "/approve", or by cycling to acceptEdits mode with Shift+Tab.',
   category: 'agent',
   permission: 'auto',
   parameters: {
     type: 'object',
     properties: {
-      approved: {
-        type: 'boolean',
+      planFile: {
+        type: 'string',
         description:
-          'Whether the user approved the plan. true → switch to acceptEdits mode. false → revert to default.',
+          'Path to the plan file you wrote (e.g., .mipham/plans/plan-2026-08-10T12-00-00.md). If omitted, the most recent plan file is used.',
       },
     },
-    required: ['approved'],
+    required: [],
   },
-  async execute(params, _ctx) {
-    const approved = params.approved === true
+  async execute(params, ctx) {
+    const planDir = join(ctx.cwd, '.mipham', 'plans')
+    const planFile = (params.planFile as string) || ''
 
-    if (approved) {
-      return {
-        success: true,
-        content: [
-          '── Plan Approved ──',
-          '',
-          '✓ Exiting plan mode.',
-          '✓ Switching to acceptEdits mode — reads and file edits are auto-approved.',
-          '',
-          'You can now implement the plan. The plan file is in .mipham/plans/.',
-          '',
-          'Use Shift+Tab to cycle permission modes if you need to change.',
-        ].join('\n'),
+    // Try to read the plan to confirm it exists
+    let planContent = ''
+    try {
+      const planPath = planFile || ''
+      if (planPath) {
+        planContent = readFileSync(planPath, 'utf-8')
       }
+    } catch {
+      // Plan file not found — still exit plan mode
     }
 
     return {
       success: true,
       content: [
-        '── Plan Mode Exited ──',
+        '── Plan Ready for Review ──',
         '',
-        '✓ Returning to default permission mode.',
+        '✓ Exiting plan mode.',
+        '✓ Plan file saved. Present your plan to the user now.',
         '',
-        'No code changes were made. The plan file is preserved in .mipham/plans/.',
-        'Use EnterPlanMode again when ready to resume planning.',
+        '⚠️  IMPORTANT: You are still in limited permission mode.',
+        '    The user must explicitly approve before you can make changes.',
+        '',
+        'Next steps:',
+        '  1. Present your plan to the user (summarize key decisions)',
+        '  2. Ask: "Does this plan look good? Reply approved to begin."',
+        '  3. Wait for the user to explicitly say "approved" or "/approve"',
+        '  4. Only then switch to acceptEdits mode (Shift+Tab or user action)',
+        '',
+        'DO NOT start implementing until the user explicitly approves.',
+        'DO NOT call ExitPlanMode with approved:true — that parameter no longer exists.',
+        planContent ? `\n── Plan Content (for reference) ──\n\n${planContent.slice(0, 3000)}` : '',
       ].join('\n'),
     }
   },

package/src/tools/exec/bash.ts

@@ -185,6 +185,105 @@ export function detectViolations(stderr: string): string[] {
   return violations
 }
 
+/**
+ * Vibe coding: Parse stderr output for error locations (file path + line + column).
+ * Supports common tool formats: TypeScript, ESLint, pytest, Rust, Go, Prettier, etc.
+ * Returns up to 10 unique locations sorted by file then line.
+ */
+interface ErrorLocation {
+  file: string
+  line: number
+  col?: number
+  message?: string
+}
+
+function parseErrorLocations(stderr: string): ErrorLocation[] {
+  const locations: ErrorLocation[] = []
+
+  // TypeScript / ESLint / Prettier: path(line,col): message
+  // e.g., src/foo.ts(42,10): error TS2304: Cannot find name 'foo'
+  const tsPattern = /([^\s(]+)\((\d+),(\d+)\):\s*(.+)/g
+  let match: RegExpExecArray | null
+  let m: RegExpExecArray | null
+  while ((m = tsPattern.exec(stderr)) !== null) {
+    locations.push({
+      file: m[1]!,
+      line: parseInt(m[2]!),
+      col: parseInt(m[3]!),
+      message: (m[4] || '').slice(0, 120),
+    })
+  }
+
+  // pytest / Python: path:line: message
+  // e.g., tests/test_foo.py:42: AssertionError: ...
+  const pyPattern = /([^\s:]+\.py):(\d+):\s*(.+)/g
+  while ((match = pyPattern.exec(stderr)) !== null) {
+    const pm = match
+    locations.push({
+      file: pm[1]!,
+      line: parseInt(pm[2]!),
+      message: (pm[3] || '').slice(0, 120),
+    })
+  }
+
+  // Rust: --> path:line:col
+  // e.g., --> src/main.rs:42:10
+  const rustPattern = /-->\s*([^\s:]+):(\d+):(\d+)/g
+  while ((match = rustPattern.exec(stderr)) !== null) {
+    const rm = match
+    locations.push({
+      file: rm[1]!,
+      line: parseInt(rm[2]!),
+      col: parseInt(rm[3]!),
+    })
+  }
+
+  // Go: path:line:col: message
+  // e.g., ./main.go:42:10: undefined: foo
+  const goPattern = /([^\s:]+\.go):(\d+):(\d+):\s*(.+)/g
+  while ((match = goPattern.exec(stderr)) !== null) {
+    const gm2 = match
+    locations.push({
+      file: gm2[1]!,
+      line: parseInt(gm2[2]!),
+      col: parseInt(gm2[3]!),
+      message: (gm2[4] || '').slice(0, 120),
+    })
+  }
+
+  // Generic: path:line (any file extension)
+  // e.g., src/foo.ts:42
+  const genericPattern = /([^\s:]+\.[a-zA-Z]{1,6}):(\d+)\b/g
+  while ((match = genericPattern.exec(stderr)) !== null) {
+    const gm = match
+    const file = gm[1]!
+    // Skip if we already have this exact location from a more specific pattern
+    const alreadyHave = locations.some((l) => l.file === file && l.line === parseInt(gm[2]!))
+    if (!alreadyHave) {
+      locations.push({ file, line: parseInt(match[2]!) })
+    }
+  }
+
+  // Deduplicate and sort: same file+line → keep first
+  const seen = new Set<string>()
+  const unique: ErrorLocation[] = []
+  for (const loc of locations) {
+    const key = `${loc.file}:${loc.line}`
+    if (!seen.has(key)) {
+      seen.add(key)
+      unique.push(loc)
+    }
+  }
+
+  // Sort by file path then line number
+  unique.sort((a, b) => {
+    const fileCmp = a.file.localeCompare(b.file)
+    return fileCmp !== 0 ? fileCmp : a.line - b.line
+  })
+
+  return unique.slice(0, 10)
+}
+
 export const bashTool: ToolDefinition = {
   name: 'Bash',
   description:
@@ -283,6 +382,20 @@ export const bashTool: ToolDefinition = {
         if (violations.length > 0) {
           errorContent += '\n\n── Sandbox Violations ──\n' + violations.join('\n')
         }
+        // Vibe coding fix: auto-parse error locations from stderr
+        const errorLocations = parseErrorLocations(rawStderr)
+        if (errorLocations.length > 0) {
+          errorContent +=
+            '\n\n── Error Locations (for quick fix) ──\n' +
+            errorLocations
+              .map(
+                (l) =>
+                  `  ${l.file}:${l.line}` +
+                  (l.col ? `:${l.col}` : '') +
+                  (l.message ? ` — ${l.message}` : ''),
+              )
+              .join('\n')
+        }
         return {
           success: false,
           content: errorContent,