@minhduydev/mdpi 0.3.0

package/dist/template/.pi/skills/verification-before-completion/SKILL.md

@@ -0,0 +1,348 @@
+---
+name: verification-before-completion
+description: Use when about to claim work is complete, fixed, or passing, before committing or creating PRs - requires running verification commands and confirming output before making any success claims; evidence before assertions always
+---
+
+# Verification Before Completion
+
+## When to Use
+
+- Before claiming tests/lint/build pass or a bug is fixed
+- Before committing, opening PRs, or stating completion in a status update
+
+## When NOT to Use
+
+- While still actively coding without a completion claim
+- When you cannot run verification commands yet (e.g., missing dependencies) — resolve first
+
+## Overview
+
+Claiming work is complete without verification is dishonesty, not efficiency.
+
+**Core principle:** Evidence before claims, always.
+
+**Violating the letter of this rule is violating the spirit of this rule.**
+
+## The Iron Law
+
+```
+NO COMPLETION CLAIMS WITHOUT FRESH VERIFICATION EVIDENCE
+```
+
+If you haven't run the verification command in this message, you cannot claim it passes.
+
+## The Gate Function
+
+```
+BEFORE claiming any status or expressing satisfaction:
+
+1. IDENTIFY: What command proves this claim?
+2. RUN: Execute the FULL command (fresh, complete)
+3. READ: Full output, check exit code, count failures
+4. VERIFY: Does output confirm the claim?
+   - If NO: State actual status with evidence
+   - If YES: State claim WITH evidence
+5. ONLY THEN: Make the claim
+
+Skip any step = lying, not verifying
+```
+
+## Verification Checklist
+
+- [ ] Identify the exact command that proves the claim
+- [ ] Run the full command (fresh)
+- [ ] Read the full output and exit code
+- [ ] Confirm the output matches the claim
+- [ ] Only then state the completion claim with evidence
+
+## Common Failures
+
+| Claim                 | Requires                        | Not Sufficient                 |
+| --------------------- | ------------------------------- | ------------------------------ |
+| Tests pass            | Test command output: 0 failures | Previous run, "should pass"    |
+| Linter clean          | Linter output: 0 errors         | Partial check, extrapolation   |
+| Build succeeds        | Build command: exit 0           | Linter passing, logs look good |
+| Bug fixed             | Test original symptom: passes   | Code changed, assumed fixed    |
+| Regression test works | Red-green cycle verified        | Test passes once               |
+| Agent completed       | VCS diff shows changes          | Agent reports "success"        |
+| Requirements met      | Line-by-line checklist          | Tests passing                  |
+
+## Red Flags - STOP
+
+- Using "should", "probably", "seems to"
+- Expressing satisfaction before verification ("Great!", "Perfect!", "Done!", etc.)
+- About to commit/push/PR without verification
+- Trusting agent success reports
+- Relying on partial verification
+- Thinking "just this once"
+- Tired and wanting work over
+- **ANY wording implying success without having run verification**
+
+## Rationalization Prevention
+
+| Excuse                                  | Reality                |
+| --------------------------------------- | ---------------------- |
+| "Should work now"                       | RUN the verification   |
+| "I'm confident"                         | Confidence ≠ evidence  |
+| "Just this once"                        | No exceptions          |
+| "Linter passed"                         | Linter ≠ compiler      |
+| "Agent said success"                    | Verify independently   |
+| "I'm tired"                             | Exhaustion ≠ excuse    |
+| "Partial check is enough"               | Partial proves nothing |
+| "Different words so rule doesn't apply" | Spirit over letter     |
+
+## Diagnostic Failure Phrases
+
+These phrases are **automatic re-verification triggers**. If you catch yourself writing any of these (or semantic equivalents), STOP and run the actual verification command before continuing.
+
+### Completion Claims Without Evidence
+
+- "This should fix it"
+- "That should resolve the issue"
+- "The problem should be gone now"
+- "This will work"
+- "It's fixed"
+- "Everything looks good"
+- "We're all set"
+
+### Confidence Substitution
+
+- "I'm fairly certain this is correct"
+- "Based on my understanding, this works"
+- "This is straightforward enough"
+- "The logic is sound"
+- "This follows the pattern so it should be fine"
+
+### Deflection / Minimization
+
+- "It's just a minor change"
+- "Nothing else should be affected"
+- "The rest of the code is unchanged"
+- "This is a safe change"
+- "No side effects expected"
+
+### Post-Hoc Rationalization
+
+- "The error was probably just [X]"
+- "That failure was likely a fluke"
+- "It probably works in production"
+- "The test environment might be the issue"
+
+### False Completion
+
+- "All done!" / "Done!" / "Complete!"
+- "That takes care of everything"
+- "Ready for review" (without verification output)
+- "Committing now" (without verification output)
+
+**Rule:** If any of these phrases appear in your draft response, delete them and replace with actual verification command output. The phrase IS the signal that you're about to lie.
+
+## Key Patterns
+
+**Tests:**
+
+```
+[x] [Run test command] [See: 34/34 pass] "All tests pass"
+[ ] "Should pass now" / "Looks correct"
+```
+
+**Regression tests (TDD Red-Green):**
+
+```
+[x] Write → Run (pass) → Revert fix → Run (MUST FAIL) → Restore → Run (pass)
+[ ] "I've written a regression test" (without red-green verification)
+```
+
+**Build:**
+
+```
+[x] [Run build] [See: exit 0] "Build passes"
+[ ] "Linter passed" (linter doesn't check compilation)
+```
+
+**Requirements:**
+
+```
+[x] Re-read plan → Create checklist → Verify each → Report gaps or completion
+[ ] "Tests pass, phase complete"
+```
+
+**Agent delegation:**
+
+```
+[x] Agent reports success → Check VCS diff → Verify changes → Report actual state
+[ ] Trust agent report
+```
+
+## Smart Verification
+
+The Iron Law demands evidence, but evidence should be gathered efficiently.
+
+### Incremental by Default
+
+Unless shipping or `--full` is passed, verify only what changed:
+
+- **Lint**: lint changed files instead of linting the entire codebase
+- **Test**: run changed test files instead of running all tests
+- **Typecheck**: always full (type errors propagate across files)
+
+### Parallel Execution
+
+Run independent gates simultaneously to reduce wall-clock time:
+
+```
+Parallel: typecheck + lint → both must pass
+Sequential: test → build (ship only)
+```
+
+Total time = max(typecheck, lint) + test, not typecheck + lint + test.
+
+### Verification Cache
+
+If you just verified and nothing changed, don't re-verify:
+
+1. After gates pass, record a stamp in `.pi/artifacts/verify.log`
+2. Before running gates, compare current state to last stamp
+3. If match → report cached PASS, skip redundant work
+4. Cache is always bypassed for `--full` and ship/release
+
+## Enforcement Gates
+
+Prompt-level rules get ignored under pressure. These gates are **hard blocks**.
+
+### Gate 1: Completion Claims Require verify.log
+
+Before ANY completion claim (close plan, PR creation, `/ship`, task completion):
+
+1. Check `.pi/artifacts/verify.log` exists and contains a recent `PASS` stamp
+2. If verify.log is missing or stale → **BLOCK** — run verification first
+3. If verify.log shows `FAIL` → **BLOCK** — do not proceed
+
+```
+[x] verify.log exists, PASS within last edit window → proceed
+[ ] verify.log missing → STOP: "Run verification first"
+[ ] verify.log shows FAIL → STOP: "Verification failed, fix before claiming complete"
+[ ] verify.log stale (files changed since last PASS) → STOP: "Re-run verification"
+```
+
+### Gate 2: Agent Delegation Requires Post-Verification
+
+After ANY `subagent` returns with "success", follow the **Worker Distrust Protocol** — read changed files, run verification, check acceptance criteria.
+
+### Enforcement Principle
+
+> **Prompt rules fail under pressure. Gates fail safe.**
+>
+> When a constraint matters enough to be an iron law, enforce it at the action level:
+> check a file, verify a condition, reject if unmet. Don't rely on the agent
+> "remembering" to follow the rule.
+
+## Phantom Completion Detection
+
+Tasks can "pass" verification while containing stub implementations. This gate catches completions that are technically correct but substantively empty.
+
+### When to Run
+
+- After all PRD tasks are marked complete (during `/ship` Phase 4-5)
+- Before closing any task
+- When `--full` verification is requested
+
+### Stub Patterns to Detect
+
+Scan all files modified in the current task for these phantom indicators:
+
+```bash
+git diff --name-only origin/main | grep -E '\.(ts|tsx|js|jsx|py|rs|go|swift|kt|java)$' | xargs grep -nE \
+  'return null|return undefined|return \{\}|return \[\]|onClick=\{?\(\) => \{\}\}?|TODO|FIXME|placeholder|stub|not.?implemented|throw new Error\(.Not implemented' \
+  2>/dev/null
+```
+
+| Pattern                                                  | What It Indicates         | Severity |
+| -------------------------------------------------------- | ------------------------- | -------- |
+| `return null` / `return undefined`                       | Empty implementation      | HIGH     |
+| `return {}` / `return []`                                | Hollow data               | HIGH     |
+| `onClick={() => {}}`                                     | No-op handler             | HIGH     |
+| `<div>Component</div>` / `<div>{/* TODO */}</div>`       | Placeholder UI            | HIGH     |
+| `TODO` / `FIXME` / `HACK`                                | Acknowledged incomplete   | MEDIUM   |
+| `placeholder` / `stub` / `not implemented`               | Self-documenting stubs    | HIGH     |
+| `throw new Error("Not implemented")`                     | Explicit stub             | HIGH     |
+| `fetch('/api/...')` without `await` or error handling    | Disconnected call         | MEDIUM   |
+| `Response.json({ok: true})` or static hardcoded response | Fake API response         | HIGH     |
+| `console.log` as only function body                      | Debug-only implementation | MEDIUM   |
+
+### Three-Level Artifact Verification
+
+For each file listed in PRD `Affected Files`:
+
+| Level              | Check                  | How                                                                                          |
+| ------------------ | ---------------------- | -------------------------------------------------------------------------------------------- |
+| **1: Exists**      | File is present        | `ls path/to/file.ts`                                                                         |
+| **2: Substantive** | Not a stub/placeholder | `semantic_grep "TODO\|FIXME\|return null\|placeholder" --glob path/to/file.ts` — verify real logic exists |
+| **3: Wired**       | Connected and used     | `semantic_grep "import.*ExportName" --glob "src/**"` — verify other files import/use it       |
+
+### Key Link Verification
+
+Check that components are actually connected (not just existing side-by-side):
+
+| Connection Type | Check Command                                                  |
+| --------------- | -------------------------------------------------------------- |
+| Component → API | `grep -E "fetch.*api/\|axios\|useSWR\|useQuery" Component.tsx` |
+| API → Database  | `grep -E "prisma\.\|db\.\|sql\|query" route.ts`                |
+| Form → Handler  | `grep "onSubmit\|handleSubmit" Component.tsx`                  |
+| State → Render  | `grep "{stateVar}" Component.tsx`                              |
+| Route → Page    | Check router config references the page component              |
+
+### Phantom Score
+
+After running all checks, report a phantom score:
+
+```
+Phantom Completion Check:
+- Files scanned: [N]
+- Stubs found: [N] (HIGH: [n], MEDIUM: [n])
+- Artifact levels: [N] exist, [M] substantive, [K] wired
+- Key links verified: [N]/[M]
+- Score: [CLEAN | SUSPECT | PHANTOM]
+```
+
+| Score       | Criteria                                       | Action                            |
+| ----------- | ---------------------------------------------- | --------------------------------- |
+| **CLEAN**   | 0 HIGH stubs, all artifacts Level 3            | Proceed                           |
+| **SUSPECT** | 1-2 MEDIUM stubs OR 1 artifact not Level 3     | Report, ask user                  |
+| **PHANTOM** | Any HIGH stubs OR >2 artifacts not substantive | **BLOCK** — fix before completion |
+
+## Why This Matters
+
+From 24 failure memories:
+
+- your human partner said "I don't believe you" - trust broken
+- Undefined functions shipped - would crash
+- Missing requirements shipped - incomplete features
+- Time wasted on false completion → redirect → rework
+- Violates: "Honesty is a core value. If you lie, you'll be replaced."
+
+## When To Apply
+
+**ALWAYS before:**
+
+- ANY variation of success/completion claims
+- ANY expression of satisfaction
+- ANY positive statement about work state
+- Committing, PR creation, task completion
+- Moving to next task
+- Delegating to agents
+
+**Rule applies to:**
+
+- Exact phrases
+- Paraphrases and synonyms
+- Implications of success
+- ANY communication suggesting completion/correctness
+
+## The Bottom Line
+
+**No shortcuts for verification.**
+
+Run the command. Read the output. THEN claim the result.
+
+This is non-negotiable.

package/dist/template/.pi/skills/webclaw/SKILL.md

@@ -0,0 +1,188 @@
+---
+name: webclaw
+description: MUST load when webfetch returns 403 or bot protection errors, when crawling documentation sites, batch-extracting pages, or extracting brand identity. Primary web scraping tool — prefer over webfetch for all non-trivial scraping.
+---
+
+# Webclaw Skill
+
+Fast, local-first web content extraction for LLMs. Rust-based scraper with TLS fingerprinting, 67% token reduction, and native MCP integration.
+
+## Prerequisites
+
+- `webclaw-mcp` binary installed at `~/.webclaw/webclaw-mcp`
+- Install: `brew tap 0xMassi/webclaw && brew install webclaw`
+- Or: download from https://github.com/0xMassi/webclaw/releases
+- MCP server must be enabled in `.pi/settings.json` or the global pi config
+
+## When to Use
+
+| Scenario               | Tool                   | Why                                        |
+| ---------------------- | ---------------------- | ------------------------------------------ |
+| `webfetch` got 403     | `scrape`               | TLS fingerprinting bypasses bot protection |
+| Research a doc site    | `crawl`                | BFS recursive extraction, same-origin      |
+| Extract multiple URLs  | `batch`                | Parallel multi-URL, faster than sequential |
+| Discover sitemap URLs  | `map`                  | Find all pages without crawling            |
+| Track doc changes      | `diff`                 | Snapshot + compare workflow                |
+| Extract brand identity | `brand`                | Colors, fonts, logos from any site         |
+| LLM-optimized output   | `scrape` with `-f llm` | 67% fewer tokens than raw HTML             |
+
+## When NOT to Use
+
+- One-off fetch of a single simple page with no bot protection — `webfetch` is lighter
+- You need to follow JS-rendered SPAs requiring a real browser — use `playwright` / `chrome-devtools` instead
+- The site is behind authentication you don't have credentials for — webclaw can't bypass login walls
+- You only need the page's raw HTML for a quick grep — `web_fetch` or `curl` suffice
+
+## MCP Tools (8 local, no API key needed)
+
+### scrape
+
+Extract clean content from a URL. Returns markdown, text, JSON, or LLM-optimized format.
+
+```
+scrape(url: "https://example.com", format: "llm")
+```
+
+Options: `format` (markdown|text|json|llm|html), `include` (CSS selectors), `exclude` (CSS selectors), `only_main_content` (boolean)
+
+### crawl
+
+Recursive BFS crawl of a site. Same-origin only.
+
+```
+crawl(url: "https://docs.example.com", depth: 2, max_pages: 50)
+```
+
+Options: `depth` (1-10), `max_pages`, `sitemap` (seed from sitemap.xml)
+
+### map
+
+Discover URLs from a site's sitemap without fetching content.
+
+```
+map(url: "https://docs.example.com")
+```
+
+### batch
+
+Parallel extraction from multiple URLs.
+
+```
+batch(urls: ["https://a.com", "https://b.com"], format: "llm")
+```
+
+### diff
+
+Compare current page content against a previous snapshot.
+
+```
+diff(url: "https://example.com", snapshot: previous_json)
+```
+
+### brand
+
+Extract visual identity: colors, fonts, logos, OG image.
+
+```
+brand(url: "https://stripe.com")
+```
+
+Returns: `{ name, colors: [{hex, usage}], fonts: [], logos: [{url, kind}] }`
+
+### extract (needs Ollama)
+
+LLM-powered structured extraction. Requires local Ollama instance.
+
+### summarize (needs Ollama)
+
+Page summarization via local LLM.
+
+## Workflow Patterns
+
+### Fallback when webfetch fails
+
+1. Try `webfetch` first (built-in, no setup)
+2. If 403 or empty → use `scrape` via webclaw MCP
+3. If JS-rendered SPA → note limitation (webclaw doesn't execute JS without cloud API)
+
+### Research a documentation site
+
+1. `map(url)` to discover all pages
+2. `crawl(url, depth: 2, max_pages: 50)` to extract content
+3. Feed results to analysis agent
+
+### Brand/design audit
+
+1. `brand(url)` to extract colors, fonts, logos
+2. Pass to vision agent for design system analysis
+
+### Track changes over time
+
+1. `scrape(url, format: "json")` → save as snapshot
+2. Later: `diff(url, snapshot: saved)` → see what changed
+
+## Installation
+
+```bash
+# Homebrew (recommended)
+brew tap 0xMassi/webclaw
+brew install webclaw
+
+# Prebuilt binary
+# Download from https://github.com/0xMassi/webclaw/releases
+# Place webclaw-mcp in ~/.webclaw/
+
+# Verify
+webclaw-mcp --version
+```
+
+## Configuration
+
+After install, enable in `.pi/settings.json` or global pi config:
+
+```json
+{
+  "mcpServers": {
+    "webclaw": {
+      "enabled": true
+    }
+  }
+}
+```
+
+Optional env vars:
+
+- `WEBCLAW_API_KEY` — cloud API for bot-protected sites (optional)
+- `OLLAMA_HOST` — for extract/summarize tools (default: `http://localhost:11434`)
+
+## Limitations
+
+- **No JS rendering** (local mode) — SPAs that render entirely client-side won't extract fully. Use `--cloud` with API key, or use `playwright` skill instead.
+- **Same-origin crawl only** — won't follow external links during crawl.
+- **Early version** — v0.3.2, MIT license. Report issues to https://github.com/0xMassi/webclaw/issues
+
+## Common Rationalizations
+
+| Rationalization | Reality |
+|---|---|
+| "webfetch works fine for this site" | Bot protection is the rule, not the exception. Always have webclaw as fallback. |
+| "I'll scrape all pages at once" | Aggressive scraping triggers rate limits. Use polite crawling with delays. |
+| "The page structure won't change" | Websites change without notice. Your scraper will break. Validate selectors regularly. |
+
+## Red Flags
+
+- Scraping without checking robots.txt
+- No rate limiting between requests
+- Selectors that break on minor DOM changes
+- Content extraction without format validation
+- Batch scrape of 100+ URLs without incremental testing
+
+## Verification
+
+After web scraping:
+
+- [ ] robots.txt was checked before scraping
+- [ ] Rate limiting is implemented between requests
+- [ ] Selectors are validated against current page structure
+- [ ] Extracted content format is validated (not empty, not garbled)
+- [ ] Error handling covers: 403, 429, 500, timeout, bot detection