@miphamai/cli 0.2.4 → 0.4.0

package/skills/standard/superpower.SKILL.md

@@ -1,19 +1,57 @@
 ---
 name: superpower
-description: Use when starting any conversation — establishes how to find and use skills
-version: 1.0.0
+description: Skill discovery and invocation system — find and use skills before any response or action
+version: 2.0.0
 ---
 
-# Superpowers Skill
+# Superpowers — Using Skills
 
-## Instruction Priority
+## The Rule
 
-User's explicit instructions always take precedence.
+**Invoke relevant or requested skills BEFORE any response or action.** Even a 1% chance a skill might apply means you should invoke it to check.
 
 ## How to Access Skills
 
-Use the Skill tool to invoke skills. When you invoke a skill, its content is loaded and presented to you — follow it directly.
+Use the `Skill` tool to invoke skills by name. When you invoke a skill, its content is loaded — follow it directly.
 
-## The Rule
+## Skill Discovery
+
+### Check Available Skills
+
+Skills are listed in `<system-reminder>` messages. Scan this list when receiving a task.
+
+### Matching Algorithm
+
+1. Parse the user's request for intent keywords
+2. Scan skill names and descriptions for matches
+3. If ANY skill matches at ≥1% probability → invoke it
+4. Multiple matches → invoke all that may apply
+5. Invoked skill doesn't fit → that's fine, don't use it
+
+### Priority Order
+
+1. **Process skills first** — brainstorming, systematic-debugging, tdd. These determine HOW to approach
+2. **Implementation skills second** — frontend-design, mcp-builder. These guide execution
+
+## Red Flags
+
+These thoughts mean STOP — you're rationalizing:
+
+| Thought                             | Reality                                        |
+| ----------------------------------- | ---------------------------------------------- |
+| "This is just a simple question"    | Questions are tasks. Check skills.             |
+| "I need more context first"         | Skill check comes BEFORE clarifying questions. |
+| "Let me explore the codebase first" | Skills tell you HOW to explore.                |
+| "I remember this skill"             | Skills evolve. Read current version.           |
+| "The skill is overkill"             | Simple things become complex. Use it.          |
+
+## Skill Types
+
+- **Rigid** (TDD, systematic-debugging): Follow exactly. Don't adapt away discipline.
+- **Flexible** (patterns): Adapt principles to context.
+
+The skill itself tells you which type it is.
+
+## User Instructions
 
-Invoke relevant or requested skills BEFORE any response or action. Even a 1% chance a skill might apply means that you should invoke the skill to check.
+Instructions say WHAT, not HOW. "Add X" or "Fix Y" doesn't mean skip workflows.

package/skills/standard/tdd.SKILL.md

@@ -1,20 +1,93 @@
 ---
 name: tdd
-description: Test-Driven Development workflow — red, green, refactor
-version: 1.0.0
+description: Test-Driven Development — red-green-refactor cycle with language-specific guidance and test design rules
+version: 2.0.0
 ---
 
-# TDD Skill
+# Test-Driven Development (TDD)
 
-## Workflow
+## The Cycle
 
-1. **Red**: Write a failing test that defines the expected behavior
-2. **Green**: Write the minimum code to make the test pass
-3. **Refactor**: Clean up the code while tests remain green
+```
+RED → GREEN → REFACTOR → repeat
+```
 
-## Rules
+### 1. RED — Write a Failing Test
 
-- Never write production code without a failing test
-- Write only enough test to fail
-- Write only enough code to pass
-- Tests must be deterministic and isolated
+Write the smallest test that captures the behavior you want:
+
+- Name the test descriptively: `it('should return 0 for empty string')`
+- Use the AAA pattern: **A**rrange → **A**ct → **A**ssert
+- Run to confirm it **fails** (not errors — fails)
+- If it passes before implementation, your test is wrong
+
+### 2. GREEN — Make It Pass
+
+Write the **minimum** code to make the test pass:
+
+- Don't optimize, don't generalize, don't add features
+- A hardcoded return is fine if it passes the test
+- Run all tests — the new one should pass, old ones should still pass
+
+### 3. REFACTOR — Clean Up
+
+Improve the code while tests stay green:
+
+- Remove duplication (test code and production code)
+- Improve names, extract helpers
+- Simplify logic
+- Run tests after each change
+
+## Test Design Rules
+
+- **Deterministic**: No `Date.now()`, `Math.random()`, or network calls in test bodies
+- **Isolated**: Each test sets up its own state; no test-order dependency
+- **Fast**: Unit tests should run in milliseconds, not seconds
+- **Readable**: Test output should explain what broke without reading source
+
+## Language-Specific Guidance
+
+### TypeScript / JavaScript (Vitest)
+
+```ts
+import { describe, it, expect } from 'vitest'
+
+describe('sum', () => {
+  it('should add two positive numbers', () => {
+    expect(sum(2, 3)).toBe(5)
+  })
+  it('should handle zero', () => {
+    expect(sum(0, 5)).toBe(5)
+  })
+})
+```
+
+File naming: `src/foo.ts` → `test/foo.test.ts`
+
+### Python (pytest)
+
+```python
+def test_sum_positive():
+    assert sum(2, 3) == 5
+
+def test_sum_zero():
+    assert sum(0, 5) == 5
+```
+
+### Go (testing package)
+
+```go
+func TestSumPositive(t *testing.T) {
+    got := Sum(2, 3)
+    want := 5
+    if got != want {
+        t.Errorf("Sum(2,3) = %d; want %d", got, want)
+    }
+}
+```
+
+## When NOT to TDD
+
+- Exploratory spikes (throw away after learning)
+- Configuration files and types (compile-time enforced)
+- Generated code

package/skills/standard/web-search.SKILL.md

@@ -1,23 +1,75 @@
 ---
 name: web-search
-description: Search the web for current information, documentation, and news
-version: 1.0.0
+description: Search the web for current information — documentation, news, technical references, and troubleshooting
+version: 2.0.0
 ---
 
-# Web Search Skill
+# Web Search
 
-Use WebSearch tool to find current information.
+Use `WebSearch` tool to find current, accurate information from the web.
 
 ## When to Use
 
-- Up-to-date documentation for libraries and frameworks
-- Current events and news
-- Technical troubleshooting with recent solutions
-- API reference and version-specific features
+- **Library/framework docs**: API references, migration guides, version-specific features
+- **Current events**: News, releases, incidents (anything after training cutoff)
+- **Troubleshooting**: Error messages, stack traces, known issues
+- **Comparisons**: Technology trade-offs, benchmark data
+- **Code examples**: Real-world usage patterns, configuration snippets
 
-## Best Practices
+## Query Best Practices
 
-- Be specific with search queries
-- Use allowed_domains to focus results
-- Verify information from multiple sources
-- Cite sources in responses
+### Be Specific
+
+```
+❌ "React"                              → too broad
+❌ "React problems"                     → ambiguous
+✅ "React 19 useEffect double mount fix" → specific, versioned
+✅ "Next.js 14 App Router caching behavior 2026" → targeted
+```
+
+### Use Technical Terms
+
+```
+❌ "how to make website fast"
+✅ "Core Web Vitals LCP optimization Next.js 14"
+```
+
+### Include Version Numbers
+
+```
+❌ "prisma query"
+✅ "Prisma 5.0 findMany with nested include filter"
+```
+
+### Domain Filtering
+
+Use `allowed_domains` for authoritative sources:
+
+- `docs.github.com` — GitHub documentation
+- `nextjs.org` — Next.js official docs
+- `developer.mozilla.org` — MDN Web Docs
+- `nodejs.org` — Node.js official
+
+## Verification
+
+- **Cross-reference**: Verify claims across 2+ independent sources
+- **Recency**: Prefer results from the current year; note article dates
+- **Authority**: Official docs > well-known blogs > Stack Overflow > random forums
+- **Cite sources**: Always include source URLs in responses
+
+## Source Attribution
+
+After answering from search results, end with:
+
+```markdown
+Sources:
+
+- [Title](URL) — brief note
+- [Title](URL) — brief note
+```
+
+## When NOT to Search
+
+- Pure logic or algorithmic questions (reasoning, not research)
+- Questions answerable from code already in context
+- Opinions and subjective recommendations (search for data, not consensus)

package/src/agent/sub-agent.ts

@@ -1,6 +1,5 @@
 import { ContextManager } from '../core/context'
 import type { ProviderRegistry } from '../providers/registry'
-import type { Message } from '../shared/types'
 
 export type SubAgentType = 'general' | 'explore' | 'plan' | 'code-review'
 

package/src/artifacts/manifest.ts

@@ -0,0 +1,101 @@
+import {
+  readFileSync,
+  writeFileSync,
+  existsSync,
+  mkdirSync,
+  renameSync,
+  copyFileSync,
+  unlinkSync,
+} from 'node:fs'
+import { join } from 'node:path'
+import type { ArtifactManifest, ArtifactEntry } from '../shared/types'
+
+/**
+ * Read the artifact manifest from disk, or return an empty one if it doesn't exist.
+ */
+export function readManifest(dir: string): ArtifactManifest {
+  const path = join(dir, 'index.json')
+  if (!existsSync(path)) {
+    return { version: 1, artifacts: [] }
+  }
+  try {
+    return JSON.parse(readFileSync(path, 'utf-8'))
+  } catch {
+    return { version: 1, artifacts: [] }
+  }
+}
+
+/**
+ * Write the manifest to disk, creating parent directories as needed.
+ */
+export function writeManifest(dir: string, manifest: ArtifactManifest): void {
+  mkdirSync(dir, { recursive: true })
+  writeFileSync(join(dir, 'index.json'), JSON.stringify(manifest, null, 2), 'utf-8')
+}
+
+/**
+ * Add an entry to the manifest and persist it.
+ * If an entry with the same name already exists, it is replaced.
+ */
+export function addToManifest(dir: string, entry: ArtifactEntry, port?: number): ArtifactManifest {
+  const manifest = readManifest(dir)
+  if (port !== undefined) manifest.port = port
+
+  const idx = manifest.artifacts.findIndex((a) => a.name === entry.name)
+  if (idx >= 0) {
+    manifest.artifacts[idx] = entry
+  } else {
+    manifest.artifacts.push(entry)
+  }
+
+  writeManifest(dir, manifest)
+  return manifest
+}
+
+/**
+ * Get all artifacts for a specific session.
+ */
+export function getSessionArtifacts(dir: string, sessionId: string): ArtifactEntry[] {
+  const manifest = readManifest(dir)
+  return manifest.artifacts.filter((a) => a.sessionId === sessionId)
+}
+
+/**
+ * Archive an existing artifact file by renaming it with a version tag.
+ * e.g. dashboard.html → dashboard.v1.html, dashboard.v1.html → dashboard.v2.html.
+ *
+ * Returns the version tag assigned to the archived file.
+ */
+export function archiveVersion(dir: string, entry: ArtifactEntry): string {
+  const manifest = readManifest(dir)
+  const versionCount = (entry.versionCount || 1) + 1
+  const ext = entry.type === 'svg' ? '.svg' : '.html'
+  const versionTag = `v${versionCount}`
+
+  // Rename the current file to a versioned copy
+  const baseName = entry.name
+  const currentPath = join(dir, entry.sessionId, `${baseName}${ext}`)
+  const archivedPath = join(dir, entry.sessionId, `${baseName}.${versionTag}${ext}`)
+
+  if (existsSync(currentPath)) {
+    try {
+      renameSync(currentPath, archivedPath)
+    } catch {
+      // If rename fails (e.g. cross-device), copy instead
+      copyFileSync(currentPath, archivedPath)
+      unlinkSync(currentPath)
+    }
+  }
+
+  // Update manifest entry
+  const artifact = manifest.artifacts.find((a) => a.name === entry.name)
+  if (artifact) {
+    const versions = artifact.versions || ['v1']
+    versions.push(versionTag)
+    artifact.versions = versions
+    artifact.versionCount = versionCount
+  }
+
+  writeManifest(dir, manifest)
+  return versionTag
+}