@miphamai/cli 0.24.16 → 0.26.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@miphamai/cli",
-  "version": "0.24.16",
+  "version": "0.26.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