droid-mode 0.0.1 → 0.0.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "droid-mode",
-  "version": "0.0.1",
+  "version": "0.0.2",
   "description": "Progressive Code-Mode MCP integration for Factory.ai Droid - access MCP tools without context bloat",
   "type": "module",
   "main": "dist/cli.js",

package/templates/skills/droid-mode/README.md

@@ -0,0 +1,166 @@
+# Droid Mode
+
+Progressive Code-Mode MCP integration for Factory Droid. Access MCP tools without loading them into context.
+
+## Installation
+
+### Option A — Project skill (recommended for teams)
+
+Copy this directory to `<repo>/.factory/skills/droid-mode/`
+
+```bash
+./.factory/skills/droid-mode/bin/dm --help
+```
+
+### Option B — User skill (personal)
+
+Copy to `~/.factory/skills/droid-mode/`
+
+```bash
+~/.factory/skills/droid-mode/bin/dm --help
+```
+
+### Option C — npx (scaffolding)
+
+```bash
+npx droid-mode init
+```
+
+---
+
+## MCP Server Configuration
+
+This skill connects to MCP servers configured in:
+
+- Project: `.factory/mcp.json`
+- User: `~/.factory/mcp.json` (overrides project)
+
+### Recommended Setup
+
+Keep MCP servers `disabled: true` so they don't bloat Droid's context:
+
+```json
+{
+  "mcpServers": {
+    "context-repo": {
+      "type": "stdio",
+      "command": "npx",
+      "args": ["-y", "context-repo-mcp"],
+      "disabled": true
+    }
+  }
+}
+```
+
+This is the **entire point** of droid-mode: access MCP servers without context bloat.
+
+### CLI Overrides
+
+For CI or quick experiments:
+
+- `--http-url <url>` with optional `--headers-json '{"Authorization":"Bearer ..."}'`
+- `--stdio-command <cmd>` with optional `--stdio-args "a,b,c"` and `--env-json '{"KEY":"VALUE"}'`
+
+---
+
+## Progressive Disclosure Model
+
+| Level | Command | Purpose |
+|-------|---------|---------|
+| 1 | `dm servers` | Discover available MCP servers |
+| 2 | `dm index --server X` | List tools on a server |
+| 3 | `dm hydrate tool1 tool2 --server X` | Get full schemas |
+| 4 | `dm run --server X ...` | Execute workflow |
+
+---
+
+## Commands
+
+### `dm servers` — List available MCP servers
+
+```bash
+dm servers
+```
+
+Shows all servers from `mcp.json`. Servers with `disabled: true` show as "disabled (good!)".
+
+### `dm doctor` — Sanity check
+
+```bash
+dm doctor --server contextrepo
+```
+
+Checks: finds `mcp.json`, resolves server, attempts `initialize` + `tools/list`.
+
+### `dm index` — List tools (compact)
+
+```bash
+dm index --server contextrepo
+dm index --server contextrepo --json
+```
+
+Outputs a compact table (name + description + required params).
+
+### `dm search` — Find tools by keyword
+
+```bash
+dm search "semantic search over docs" --limit 8 --server contextrepo
+```
+
+Searches the cached index.
+
+### `dm hydrate` — Get full schemas
+
+```bash
+dm hydrate search_documents get_document --server contextrepo
+```
+
+Writes to `.factory/droid-mode/hydrated/<server>/<timestamp>/`:
+- `tools.json` — full tool definitions
+- `types.d.ts` — TypeScript types
+- `toolmap.json` — safe JS identifiers → tool names
+
+### `dm run` — Execute workflow
+
+```bash
+dm run --server contextrepo --tools search_documents,get_document --workflow workflow.js
+```
+
+Example workflow:
+
+```js
+workflow = async () => {
+  const docs = await t.searchDocuments({ query: "Droid Mode PRD", limit: 5 })
+  const full = await Promise.all(docs.results.map(d => t.getDocument({ id: d.id })))
+  return { count: full.length, ids: full.map(x => x.id) }
+}
+```
+
+---
+
+## Output & Audit Artifacts
+
+All artifacts written to `.factory/droid-mode/`:
+
+| Path | Contents |
+|------|----------|
+| `cache/<server>/tools.json` | Cached tool inventory |
+| `hydrated/<server>/<ts>/` | Schema bundles |
+| `runs/<server>/<ts>/run.json` | Workflow result + trace |
+
+---
+
+## Security Posture
+
+- Credentials remain in `mcp.json` env/headers, not in prompts
+- Workflow sandbox blocks `require`, `import`, `process`, `fetch`
+- Network access mediated through MCP server only
+- Every tool call traced (name, args hash, duration, error flag)
+
+Optional: Add a **PreToolUse hook** to block direct `mcp__*` calls. See `examples/hooks/`.
+
+---
+
+## Design Philosophy
+
+Treat MCP as infrastructure. Treat Skills as capability boundaries. Treat code as a reasoning amplifier — not as authority.

package/templates/skills/droid-mode/SKILL.md

@@ -1,237 +1,97 @@
 ---
 name: droid-mode
-description: Progressive Code‑Mode MCP integration for Factory Droid. Discover tools incrementally, hydrate schemas on demand, and run procedural workflows that call MCP tools outside the LLM loop.
+description: Progressive Code-Mode MCP integration for Factory Droid. Discover tools incrementally, hydrate schemas on demand, and run procedural workflows that call MCP tools outside the LLM loop.
 ---
 
-# Droid Mode (Progressive Code‑Mode MCP Skill)
+# Droid Mode
 
-This skill implements the **PRD “Droid Mode”** pattern: treat MCP as backend infrastructure and use **local scripts** to perform **progressive tool discovery + schema hydration + procedural orchestration**.
+Access MCP tools **without loading them into context**. Progressive discovery → schema hydration → procedural execution.
 
-Instead of injecting a full MCP tool inventory into the model context, Droid uses these scripts to:
+## When to Use
 
-1. **Index** tools (compact list)
-2. **Search** tools (narrow candidates)
-3. **Hydrate** schemas (only for selected tools)
-4. **Run** a procedural workflow that calls MCP tools **outside** the LLM loop
-
-Everything is **auditable**: caches, hydrated schemas, and workflow traces are written to `.factory/droid-mode/` (project) or `~/.factory/droid-mode/` (fallback).
-
----
-
-## When to use this skill
-
-Use this skill when you want any of the following:
-
-- MCP servers with **many tools**, or rapidly changing inventories
-- **Token efficiency** (avoid dumping schemas into prompt context)
-- **Procedural** workflows (filter/join/iterate locally between tool calls)
+- MCP servers with **many tools** (avoid context bloat)
+- **Token efficiency** (don't dump schemas into prompts)
+- **Procedural workflows** (filter/join/iterate between tool calls)
 - **Auditability** (explicit scripts + saved artifacts)
 
----
-
-## Installation
-
-### Option A — Project skill (recommended for teams)
-
-Copy this directory to:
-
-- `<repo>/.factory/skills/droid-mode/`
-
-Then call it from the repo root:
-
-```bash
-./.factory/skills/droid-mode/bin/dm --help
-```
-
-### Option B — User skill (personal)
-
-Copy to:
-
-- `~/.factory/skills/droid-mode/`
-
-Then call it via absolute path:
-
-```bash
-~/.factory/skills/droid-mode/bin/dm --help
-```
-
----
-
-## MCP server configuration
-
-This skill can connect to an MCP server in two ways:
-
-1. **Auto-detect from Droid’s `mcp.json`** (preferred)
-   - Project: `.factory/mcp.json`
-   - User: `~/.factory/mcp.json` (overrides project server entries)
-
-2. **Explicit CLI flags** (useful in CI or quick experiments)
-
-   Supported overrides:
-   - `--http-url <url>` with optional `--headers-json '{"Authorization":"Bearer ..."}'`
-   - `--stdio-command <cmd>` with optional `--stdio-args "a,b,c"` and `--env-json '{"KEY":"VALUE"}'`
-
-### Recommended: configure ContextRepo as a stdio MCP server
-
-If you use ContextRepo, the common approach is to run its MCP server locally (stdio) and let it talk to ContextRepo’s API using an API key.
-
-Example (user-level config is preferred for secrets):
-
-```bash
-droid mcp add contextrepo "npx -y context-repo-mcp" --env CONTEXTREPO_API_KEY=YOUR_KEY
-```
-
-Notes:
-- This skill intentionally **does not print** env values.
-- It will also recognize `CONTEXT_REPO_API_KEY` and `CONTEXTREPO_TOKEN` if present.
-
----
-
-## Progressive Disclosure Model
-
-Droid-mode implements a four-level progressive disclosure model:
+## Commands
 
 | Level | Command | Purpose |
 |-------|---------|---------|
 | 1 | `dm servers` | Discover available MCP servers |
-| 2 | `dm index --server X` | List tools on a server |
-| 3 | `dm hydrate tool1 tool2 --server X` | Get full schemas |
-| 4 | `dm run --server X ...` | Execute workflow |
-
-### Working with "Disabled" Servers
+| 2 | `dm index --server X` | List tools (name, description, required params) |
+| 3 | `dm hydrate tool1 tool2 --server X` | Get full schemas + TypeScript types |
+| 4 | `dm run --workflow file.js --tools a,b --server X` | Execute procedural workflow |
 
-Servers marked `disabled: true` in `mcp.json` are **fully available** to droid-mode. In fact, this is the recommended configuration:
+All commands accept `--server <name>`. If only one server exists, it's auto-selected.
 
-- `disabled: true` tells Droid: "Don't load this server's tools into context"
-- droid-mode connects directly, bypassing context injection
-- Result: Token-efficient, on-demand MCP access
-
-```json
-// ~/.factory/mcp.json - Recommended setup
-{
-  "mcpServers": {
-    "context-repo": {
-      "type": "stdio",
-      "command": "npx",
-      "args": ["-y", "context-repo-mcp"],
-      "disabled": true
-    }
-  }
-}
-```
-
-This is the **entire point** of droid-mode: access MCP servers without bloating the context window.
-
----
-
-## Commands
-
-> All commands accept `--server <name>` to pick an MCP server from `mcp.json`.
-> If only one server is configured, it's auto-selected. Otherwise, use `dm servers` to discover available servers.
-
-### 0) List servers (discover available MCP servers)
-
-```bash
-./.factory/skills/droid-mode/bin/dm servers
-```
-
-Lists all MCP servers configured in `mcp.json` (both project and user level).
-Servers with `disabled: true` are shown as "disabled (good!)" since they won't bloat Droid's context.
-
-### 1) Doctor (sanity check)
-
-```bash
-./.factory/skills/droid-mode/bin/dm doctor --server contextrepo
-```
-
-Checks:
-- Finds `mcp.json`
-- Resolves the server entry (user overrides project)
-- Attempts `initialize` + `tools/list` (unless `--no-connect`)
-
-### 2) Index tools (compact list)
-
-```bash
-./.factory/skills/droid-mode/bin/dm index --server contextrepo
-```
-
-Outputs a compact table (name + short description).  
-Use `--json` to return structured output.
+## Key Insight
 
-### 3) Search tools (narrow candidate set)
-
-```bash
-./.factory/skills/droid-mode/bin/dm search "semantic search over docs" --limit 8 --server contextrepo
-```
-
-This searches the cached index, refreshing if missing or stale.
-
-### 4) Hydrate tool schemas (small subset)
-
-```bash
-./.factory/skills/droid-mode/bin/dm hydrate search_documents get_document --server contextrepo
-```
+Servers with `disabled: true` in `mcp.json` are **fully available** to droid-mode:
 
-Writes an “hydration bundle” to:
-
-- `.factory/droid-mode/hydrated/<server>/<timestamp>/`
-
-Contents:
-- `tools.json` (full tool definitions for the subset)
-- `types.d.ts` (best-effort TS types for inputs/outputs)
-- `toolmap.json` (safe JS identifiers → tool names)
-
-### 5) Run a procedural workflow (“code-mode”)
+- `disabled: true` = "don't inject tools into Droid's context"
+- droid-mode connects directly, bypassing context injection
+- Result: token-efficient, on-demand MCP access
 
-Create a workflow file that defines `workflow = async () => { ... }`.
+This is the entire point of the skill.
 
-Example:
+## Workflow Example
 
 ```js
 // workflow.js
 workflow = async () => {
-  const docs = await t.searchDocuments({ query: "Droid Mode PRD", limit: 5 })
-  const full = await Promise.all(docs.results.map(d => t.getDocument({ id: d.id })))
-  return { count: full.length, ids: full.map(x => x.id) }
+  const docs = await t.searchDocuments({ query: "PRD", limit: 5 })
+  return docs.results.map(d => d.id)
 }
 ```
 
-Run it:
-
 ```bash
-./.factory/skills/droid-mode/bin/dm run --server contextrepo --tools search_documents,get_document --workflow workflow.js
+dm run --server contextrepo --tools search_documents --workflow workflow.js
 ```
 
-The runner:
-- Hydrates only the requested tools
-- Executes your workflow in a restricted JS sandbox (no imports/require/fetch)
-- Emits a JSON result + an execution trace
+## Verification
 
----
+After using droid-mode, verify:
 
-## Output & audit artifacts
+- [ ] `dm doctor --server X` passes (connection works)
+- [ ] Artifacts exist in `.factory/droid-mode/` (cache, hydrated, runs)
+- [ ] Workflow trace shows no errors (`runs/<server>/<ts>/run.json`)
 
-Artifacts are written under `.factory/droid-mode/` (project) when possible:
+## Success Criteria
 
-- `cache/<server>/tools.json` — cached tool inventory
-- `hydrated/<server>/<timestamp>/...` — schema bundles
-- `runs/<server>/<timestamp>/run.json` — workflow result + trace
+The skill completes successfully when:
 
----
+- Tool discovery returned results (`dm index` shows tools)
+- Hydrated schemas are valid (`types.d.ts` generated)
+- Workflow executed without sandbox errors (trace shows `error: false`)
 
-## Security posture (practical guardrails)
+## Fallbacks
 
-This skill is designed so that:
+| Issue | Resolution |
+|-------|------------|
+| Server not found | Run `dm servers` to list available servers |
+| Connection timeout | Check `mcp.json` config, run `dm doctor` |
+| Tool not found | Run `dm index --server X` to refresh cache |
+| Workflow sandbox error | Check for disallowed `require`/`import`/`fetch` |
 
-- Credentials remain in `mcp.json` env/headers (or your OS keyring), not in prompts.
-- The workflow sandbox does **not** expose `require`, `import`, `process`, or `fetch`.
-- Network access for workflows is mediated through the MCP server only.
-- Every tool call is traced (tool name, args hash, duration, and error flag).
+## Never Do
 
-Optional: You can add a **PreToolUse hook** to block direct `mcp__*` tool calls and force use of this skill. See `examples/hooks/`.
+- Don't hardcode credentials in workflows (use `mcp.json` env)
+- Don't skip `--server` flag when multiple servers exist
+- Don't use `fetch`/`require`/`import` in workflow files (sandbox blocks them)
 
----
+## Artifacts
+
+All outputs written to `.factory/droid-mode/`:
+
+- `cache/<server>/tools.json` — tool inventory
+- `hydrated/<server>/<ts>/` — schemas + types
+- `runs/<server>/<ts>/run.json` — execution trace
 
-## Design philosophy (north star)
+## Supporting Files
 
-Treat MCP as infrastructure. Treat Skills as capability boundaries. Treat code as a reasoning amplifier — not as authority.
+- `bin/dm` — CLI entry point
+- `lib/` — implementation modules
+- `examples/workflows/` — sample workflow files
+- `examples/hooks/` — PreToolUse hook examples
+- `README.md` — full documentation