@thoughtflow/core 0.2.0 → 0.3.0

package/skills/thoughtflow-mcp/SKILL.md

@@ -0,0 +1,294 @@
+---
+name: thoughtflow-mcp
+description: "Use when thoughtflow MCP tools (mcp__thoughtflow__*) are available. 100+ coding tools: file ops, git, search, code analysis, refactoring, testing, planning, vision browser. Use tool_search first to discover the right tool and its parameters — never call an unfamiliar tool without checking its schema. The tool list is compressed; call tool_search with a natural language query to get full parameter details."
+version: 0.1.0
+author: thoughtflow
+license: MIT
+metadata:
+  hermes:
+    tags: [thoughtflow, mcp, tools, coding, autonomous]
+    related_skills: []
+---
+
+# thoughtflow MCP — 100+ Coding Tools
+
+## Overview
+
+thoughtflow exposes 100+ battle-tested coding tools through MCP. Every tool is
+prefixed `mcp__thoughtflow__`. The tool list is **compressed by default** —
+you see names + one-liners, not full schemas. Use `tool_search` to discover
+tools and their parameters on demand.
+
+## When to Use
+
+This skill activates automatically when `mcp__thoughtflow__tool_search` is in
+your tool list. It guides you to use thoughtflow tools efficiently.
+
+**Use thoughtflow tools when you need:**
+- File operations — prefer Hermes built-in tools (`read_file`, `write_file`, `patch`, `search_files`) for speed and session integration. Use MCP workspace tools only for workspace-relative paths or bulk operations.
+- Git operations (status, diff, commit, branch, log)
+- Codebase analysis (search, dependency graphs, impact, cross-references)
+- Code review & quality (neural review, complexity, duplication, security scan)
+- Refactoring (rename, extract, move, split, organize imports)
+- Testing (generate unit/integration tests, fix failures, find gaps)
+- Documentation (generate README, API docs, ADR, diagrams)
+- Planning (problem decomposition, task breakdown, estimation)
+- Terminal commands (shell execution with workspace awareness)
+- Visual page analysis (screenshot + vision model inspection)
+
+**Don't use thoughtflow tools for:**
+- Simple one-liner questions that don't need code access
+- Tasks that Hermes's built-in tools handle better (memory, session_search, etc.)
+
+## Core Workflow: tool_search → execute
+
+**NEVER call a thoughtflow tool without knowing its parameters.** The compressed
+tool list hides input schemas. Always discover first:
+
+```
+1. tool_search("read and write text files")     → find the right tool
+2. read the parameter schemas in the response   → learn what params it needs
+3. mcp__thoughtflow__readFile({path: "..."})    → call with correct params
+```
+
+### tool_search query patterns
+
+| Describe what you want | Example query |
+|---|---|
+| By domain | `"workspace tools"`, `"testing tools"`, `"codebase tools"` |
+| By action | `"search for code"`, `"create a migration"`, `"review code quality"` |
+| By file type | `"generate TypeScript tests"`, `"refactor imports"` |
+
+### If tool_search returns "no tools found"
+
+Broaden the query or search by domain. Every tool belongs to one of these
+domains: workspace, codebase, neural, planning, refactor, testing, quality,
+docs, devops, database, memory.
+
+## Domain Quick Reference
+
+| Domain | What it provides | Key tools |
+|---|---|---|
+| **workspace** | File I/O, terminal, git, browser, HTTP, search | `readFile`, `writeFile`, `grep`, `terminalRun`, `git`, `patchFile` |
+| **codebase** | Repository intelligence | `codebaseSearch`, `codebaseIndex`, `codebaseImpact`, `codebaseFlow` |
+| **neural** | LLM-powered analysis | `neuralReview`, `neuralExplain`, `neuralDebug`, `neuralSecurity` |
+| **planning** | Task decomposition | `solveComplex`, `pmBreakdown`, `pmEstimate`, `problemTree` |
+| **refactor** | Code transformation | `refactorRename`, `refactorExtract`, `refactorImports` |
+| **testing** | Test automation | `testGenUnit`, `testFix`, `testGap`, `testFuzz` |
+| **quality** | Code metrics | `qualityComplexity`, `qualityCoverage`, `qualityDuplication` |
+| **docs** | Documentation | `docGenReadme`, `docGenApi`, `docGenDiagrams` |
+| **devops** | CI/CD & infra | `ciWorkflow`, `deployCheck`, `dockerOptimize` |
+| **database** | DB operations | `dbMigration`, `dbDiagram` |
+| **vision** | Visual analysis | `visionBrowser` — screenshot + vision LLM |
+
+## Efficient Usage Patterns
+
+These patterns mirror real thoughtflow development workflows. Follow them exactly.
+
+### Before ANY code change (mandatory)
+```
+1. grep or codebaseSearch to understand current state
+2. codebaseImpact({files: ["src/target.ts"]}) to check blast radius
+3. Make changes
+4. neuralReview({paths: ["src/"]}) to catch issues
+5. runTsc or terminalRun("bun run build && bun run test") to verify
+```
+
+### Investigating a bug
+```
+1. neuralDebug({error: "...", files: ["src/"]}) → AI-powered root cause
+2. grep({pattern: "offending_symbol"}) → find all occurrences
+3. codebaseFlow({entryFile: "src/app.ts", function: "brokenFn"}) → trace call path
+4. Fix
+5. testGenUnit({target: "src/fixed.ts"}) → add regression test
+```
+
+### Refactoring (rename/extract/move)
+```
+1. refactorRename({oldName: "oldFn", newName: "newFn", paths: ["src/"]})
+2. refactorImports({paths: ["src/"]}) → clean up
+3. qualityComplexity({paths: ["src/"]}) → verify improvement
+4. bun run build && bun run test
+```
+
+### Adding a new feature
+```
+1. solveComplex({problem: "Add pagination to the user list endpoint"})
+   → returns task tree with dependencies
+2. Implement in dependency order (problemTree for progress tracking)
+3. testGenIntegration({target: "src/new-feature.ts"})
+4. neuralReview + build + test
+```
+
+### Visual testing a web page
+```
+1. browser({action:"open"}) → save sessionId
+2. browser({action:"navigate", sessionId, url:"http://localhost:3000"})
+3. browser({action:"snapshot", sessionId}) → find [ref=eN] elements
+4. browser({action:"click", sessionId, selector:"e4"})
+5. browser({action:"vision", sessionId, prompt:"Does the login form look correct?"})
+6. browser({action:"console", sessionId}) → check for JS errors
+7. browser({action:"network", sessionId}) → check for failed API calls
+8. browser({action:"close", sessionId}) when done
+```
+
+### Pre-commit quality gate
+```
+1. qualityComplexity → no function > 10 complexity
+2. qualityDuplication → no new duplications
+3. qualityTypes → no new `any` types
+4. testGap → no uncovered paths
+5. neuralSecurity → no hardcoded secrets
+6. bun run build && bun run test → green
+
+
+## Vision Browser
+
+`visionBrowser` takes a URL or HTML and a prompt, renders it with headless
+Chromium, and analyzes the screenshot with a vision model:
+
+```
+visionBrowser({
+  url: "https://example.com",
+  prompt: "Is the login button visible? What color is the header?",
+  captureConsole: true,
+  captureNetwork: true,
+})
+```
+
+Console logs and network activity (with full request/response headers and body)
+can be captured by adding `captureConsole: true` and `captureNetwork: true`.
+
+Works with any OpenAI-compatible vision model. Requires Playwright
+(`npm install playwright`).
+
+## Interactive Browser (Stateful)
+
+The `browser` tool maintains state across calls via `sessionId`. Each session
+is an isolated Chromium process. **ALWAYS follow this flow — never improvise:**
+
+```
+// 1. Open a session
+browser({action: "open"})
+→ {"sessionId": "br_abc123"}
+
+// 2. Navigate
+browser({action: "navigate", sessionId: "br_abc123", url: "https://example.com"})
+→ {"title": "Page Title", "url": "https://example.com"}
+
+// 3. Inspect the DOM (accessibility tree, compact, with [ref=eN] markers)
+browser({action: "snapshot", sessionId: "br_abc123"})
+→ - link "Home" [ref=e1]
+  - button "Get Started" [ref=e2]
+  - textbox "Search..." [ref=e3]
+
+// 4. Interact using [ref=eN] from snapshot
+browser({action: "click", sessionId: "br_abc123", selector: "e2"})
+browser({action: "type", sessionId: "br_abc123", selector: "e3", text: "hello"})
+
+// 5. Check console for JS errors
+browser({action: "console", sessionId: "br_abc123"})
+→ [error] TypeError: ... — app.js:42
+
+// 6. Check network for failed API calls
+browser({action: "network", sessionId: "br_abc123"})
+→ ✗ POST /api/auth → 401 (567ms)
+
+// 7. Visual check
+browser({action: "screenshot", sessionId: "br_abc123"})
+→ screenshot:base64:iVBOR...
+
+// 8. Close when done
+browser({action: "close", sessionId: "br_abc123"})
+```
+
+**Key rules:**
+- Save `sessionId` from `open` — use it for ALL subsequent calls
+- Use `snapshot` not `get_dom` — the accessibility tree is compact and has `[ref=eN]`
+- `console` and `network` auto-accumulate from session start
+- Sessions auto-expire after 5 min — don't leave them open
+- Use `list` to see all active sessions
+
+## Safety Rules
+
+### Never do these without user approval:
+- `git checkout <file>` or `git reset --hard` that discards uncommitted changes
+- `git push --force`
+- `rm -rf`, recursive deletion, wiping directories
+- `DROP TABLE`, `TRUNCATE`, `DELETE FROM` without WHERE
+
+### Before any destructive operation:
+1. Backup first: `cp file.ts file.ts.bak` or `git stash`
+2. Check impact: `codebaseImpact` on the target
+3. Ask: "Can I undo this in 30 seconds?"
+4. If no → STOP and ask the user
+
+## Planning + TODO workflow
+
+Always decompose complex tasks into a Hermes TODO list:
+
+```
+1. mcp__thoughtflow__solveComplex({problem: "..."}) → dependency tree
+2. Translate into Hermes `todo` items in dependency order
+3. Mark complete as you go — the TODO is your source of truth
+4. Report progress from the TODO list, not from memory
+```
+
+## Common Pitfalls
+
+1. **Calling tools without tool_search first.** The compressed list doesn't show
+   parameters. You'll get schema errors. Always `tool_search("what you want")` first.
+
+2. **Using Hermes built-in tools when thoughtflow has better ones.** The built-in
+   `read_file` is for reading into context; `mcp__thoughtflow__readFile` works on
+   the workspace project. Use thoughtflow tools for project operations.
+
+3. **Forgetting the `mcp__thoughtflow__` prefix.** All thoughtflow tools are
+   prefixed. `readFile` ≠ `mcp__thoughtflow__readFile`.
+
+4. **Not checking allowedPaths.** If a file operation fails, the path might be
+   outside the configured workspace sandbox. Check `thoughtflow.config.json`.
+
+5. **Calling `open` multiple times for the same task.** Each `open` creates a
+   new session. Save the `sessionId` and reuse it for all browser actions.
+
+6. **Using `get_dom` instead of `snapshot`.** `get_dom` returns raw HTML
+   (potentially huge). `snapshot` returns a compact accessibility tree with
+   `[ref=eN]` markers that `click` and `type` understand directly.
+
+7. **Not checking console/network after interactions.** JS errors and failed
+   API calls are auto-captured. Check `console` and `network` after
+   clicks/navigation — they often reveal the root cause of UI issues.
+
+## Installation & Updates
+
+### One-command install
+
+```bash
+npx @thoughtflow/mcp-server install-skill
+```
+
+Copies the skill to `~/.hermes/skills/thoughtflow-mcp/SKILL.md`.
+Use `--target` for custom locations:
+
+```bash
+npx @thoughtflow/mcp-server install-skill --target ~/.agents/skills/
+```
+
+### Manual install
+
+```bash
+cp skills/thoughtflow-mcp/SKILL.md ~/.hermes/skills/thoughtflow-mcp/
+```
+
+### Updating
+
+Re-run `install-skill` after pulling the latest thoughtflow — it overwrites the old skill file. Start a new Hermes session to pick up changes.
+
+## Verification Checklist
+
+- [ ] `hermes mcp test thoughtflow` returns "Connected" with tools listed
+- [ ] `tool_search("workspace tools")` returns file/git/terminal tools with schemas
+- [ ] `mcp__thoughtflow__readFile({path: "README.md"})` reads a file successfully
+- [ ] In chat, LLM calls `tool_search` before calling unfamiliar tools
+- [ ] Vision browser works when configured: `visionBrowser({url: "...", prompt: "..."})`