---

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.

Droid Mode

Access MCP tools without loading them into context. Progressive discovery → schema hydration → procedural execution.

When to Use

• 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)

Requirements

Commands

IMPORTANT: The dm script must be called with full path. Try workspace first:

1. Workspace (try first): ./.factory/skills/droid-mode/bin/dm
2. Personal (fallback): ~/.factory/skills/droid-mode/bin/dm

If workspace path fails with "not found", use personal path.

All commands accept --server <name>. If only one server exists, it's auto-selected.

Use dm call for single tool calls. Use dm run only for multi-tool workflows.

Key Insight

Servers with disabled: true in mcp.json are fully available to droid-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

This is the entire point of the skill.

Idempotency

All droid-mode commands are safe to rerun:

• dm servers / dm index: read-only discovery
• dm hydrate: overwrites previous hydration (timestamped)
• dm run: each run creates a new timestamped trace

No cleanup required between invocations.

Tool Execution

Primary: Direct Call (dm call)

For single tool calls (most common use case):

Copy# Hydrate once (caches schema)
dm hydrate list_collections --server context-repo

# Call directly - no workflow file needed
dm call list_collections --server context-repo
dm call list_collections --server context-repo --args '{"limit": 5}'

Results returned directly as JSON. This is the preferred method for interactive use.

Advanced: Workflows (dm run)

For multi-tool orchestration with loops, conditionals, or pre-programmed patterns:

Copydm run --server context-repo --tools a,b,c --workflow script.js

Use workflows for complex automation, not everyday single-tool calls.

Naming Convention

Tool names use snake_case in CLI flags but camelCase in workflow code:

Conversion rule: Remove underscores, capitalize each word after first.

• list_collections → listCollections
• search_documents → searchDocuments
• get_file_content → getFileContent

Workflow Example

Copy// workflow.js
// Note: Tool name converts from snake_case to camelCase
// search_documents → t.searchDocuments()
workflow = async () => {
  const docs = await t.searchDocuments({ query: "PRD", limit: 5 })
  return docs.results.map(d => d.id)
}

Copy# Workspace skill
./.factory/skills/droid-mode/bin/dm run --server contextrepo --tools search_documents --workflow workflow.js

# Personal skill
~/.factory/skills/droid-mode/bin/dm run --server contextrepo --tools search_documents --workflow workflow.js

Verification

After using droid-mode, verify (using full path to dm for your installation):

Copy# Workspace skill
./.factory/skills/droid-mode/bin/dm doctor --server X

# Personal skill
~/.factory/skills/droid-mode/bin/dm doctor --server X

• 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)

Proof Artifacts

After completing a workflow, produce evidence:

• Discovery proof: Screenshot or paste of dm index --server X output
• Hydration proof: Confirm types.d.ts exists and compiles (tsc --noEmit)
• Execution proof: Link to run.json trace showing error: false
• For PRs: Include trace file or summary in PR description

Success Criteria

The skill completes successfully when these artifacts exist:

Verify with the appropriate full path for your installation:

• Workspace: ./.factory/skills/droid-mode/bin/dm doctor --server X
• Personal: ~/.factory/skills/droid-mode/bin/dm doctor --server X

Command should exit 0.

Fallbacks

Never Do

• 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

All JSON artifacts are machine-parseable for downstream skill chaining. Workflows can read tools.json or run.json to inform subsequent steps.

Supporting Files

• bin/dm: CLI entry point
• lib/: implementation modules
• examples/workflows/: sample workflow files
• examples/hooks/: PreToolUse hook examples
• README.md: full documentation

Quick Reference

Find dm: Always at ./.factory/skills/droid-mode/bin/dm (workspace) or ~/.factory/skills/droid-mode/bin/dm (personal)

Minimal workflow (using workspace path):

Copy# 1. Discover tools (snake_case names)
./.factory/skills/droid-mode/bin/dm index --server X

# 2. Hydrate (use snake_case)
./.factory/skills/droid-mode/bin/dm hydrate tool_name --server X

# 3. Execute (use camelCase in workflow)
echo 'workflow = async () => await t.toolName({})' > /tmp/wf.js
./.factory/skills/droid-mode/bin/dm run --server X --tools tool_name --workflow /tmp/wf.js

For personal skill, replace ./.factory/ with ~/.factory/.

Common mistake: Using t.tool_name() instead of t.toolName() in workflows.

References

For project-specific conventions, see:

• AGENTS.md: project-wide agent guidance (if present)
• mcp.json: MCP server configuration
• .factory/skills/*/SKILL.md: related skills that may chain with droid-mode

For droid-mode internals:

• README.md: full CLI documentation
• examples/: sample workflows and hooks