DeepWork

Synced from deepwork/README.md. The repository is the source of truth.

deepwork is the native Pi package for DeepWork workflows, DeepWork Reviews, and DeepSchema.

The Pi extension is intentionally native: it does not require .mcp.json, does not start a DeepWork MCP server, and does not route Pi tools through MCP. That is a property of the Pi path (PI-REQ-001), not of the repository — Claude Code and Codex have no equivalent extension API, so they are served by a separate bundled MCP entry point that the Pi path never loads. Runtime implementation work reuses existing DeepWork behavior through native TypeScript implementations and a narrow compatibility bridge where behavior has not yet been ported.

Install from GitHub

From a Pi project, install the package with:

pi install git:github.com/ai-outfitter/deepwork

Then reload Pi resources if Pi is already running:

/reload

The published package is @ai-outfitter/deepwork; it provides the native DeepWork extension and packaged skills/prompts for Pi, and the plugin surfaces for Claude Code and Codex.

Use with Claude Code

claude plugin marketplace add ai-outfitter/deepwork
claude plugin install deepwork@ai-outfitter

For a checkout, npm ci && npm run build, then claude --plugin-dir /path/to/deepwork.

See docs/claude-code.md for setup options, the capability mapping, and known gaps.

Use with Codex

npm install -g @ai-outfitter/deepwork
codex plugin marketplace add ai-outfitter/deepwork
codex plugin add deepwork@ai-outfitter

Codex passes a plugin MCP server almost no environment, so DEEPWORK_* settings must be declared in the plugin’s own config rather than exported in your shell. See docs/codex.md.

Pi usage is unchanged and remains MCP-free on both counts.

Local development

Clone this repository and install dependencies:

git clone https://github.com/ai-outfitter/deepwork.git
cd deepwork
npm ci

From a Pi project, install the local checkout with:

pi install /path/to/deepwork -l

Run available checks from the package checkout:

npm run check:package
npm run typecheck
npm test

Releases

DeepWork releases are managed with release-please. Use Conventional Commit messages (feat:, fix:, docs:, chore:) on merged PRs. After changes land on main, the Release Please workflow opens or updates a release PR. Merging that release PR updates package.json, package-lock.json, CHANGELOG.md, creates the GitHub release, and tags the version.

Pi users who install from GitHub should reference the canonical repository:

pi install git:github.com/ai-outfitter/deepwork

If Pi is already running, restart Pi or reload resources after the profile or installed package source changes so the new native tools are available in the current session.

Native Pi resources

The package manifest declares:

{
  "pi": {
    "extensions": ["./src/index.ts"],
    "skills": ["./skills"],
    "prompts": ["./prompts"]
  }
}

The extension entry point registers /review, /deepwork_review, /configure-reviews, /record, the native deepwork_* tools listed below, session context restoration, commit review reminders, and DeepSchema write feedback hooks. /deepwork itself is provided as a prompt/skill-style resource at prompts/deepwork.md; it tells the agent to call deepwork_get_workflows, infer the appropriate workflow, and start it with native tools.

Required native tool surface

The implementation requirements define these Pi-native tools:

• deepwork_get_workflows
• deepwork_register_session_job
• deepwork_get_session_job
• deepwork_start_workflow
• deepwork_finished_step
• deepwork_abort_workflow
• deepwork_go_to_step
• deepwork_get_review_instructions
• deepwork_get_configured_reviews
• deepwork_mark_review_as_passed
• deepwork_get_named_schemas

These tools are registered with pi.registerTool() and do not call MCP tools or require an MCP server. Workflow discovery, workflow runtime, and session-job registration use native TypeScript implementation paths and include bundled standard jobs from standard_jobs/ unless DEEPWORK_STANDARD_JOBS_DIR overrides the source.

Package resources

• src/ contains the native Pi extension entry point, bridge, tools, workflow runtime helpers, review helpers, and DeepSchema helpers.
• extensions/ contains Pi command/tool/lifecycle registration.
• skills/ contains packaged Pi skills for DeepWork, reviews, DeepSchema, DeepPlan, record, and onboarding flows.
• prompts/ contains the /deepwork prompt resource.
• standard_jobs/ and standard_schemas/ contain bundled DeepWork jobs and DeepSchema definitions used by the extension.
• docs/ contains user-facing review and bridge documentation.
• doc/specs/deepwork-pi/ contains native Pi requirements retained from the implementation source.

Package status

Implemented so far:

• package.json with standalone Pi package metadata for ai-outfitter/deepwork
• src/index.ts Pi extension entry point
• extensions/index.ts native Pi tool, command, and lifecycle registration
• src/bridge.ts centralized compatibility bridge for operations not yet ported to TypeScript
• src/workflows/discovery.ts native TypeScript workflow discovery and parsing for deepwork_get_workflows
• src/workflows/session-jobs.ts native TypeScript session-job registration and retrieval for DeepPlan-generated jobs
• tsconfig.json TypeScript project config
• doc/specs/deepwork-pi/ native Pi requirements
• skills/ native Pi skill set
• standard_jobs/ bundled DeepWork standard jobs, including deepwork_jobs/new_job, deepwork_jobs/learn, deepwork_jobs/repair, deepwork_jobs/shared_jobs, deepwork_reviews/*, and deepplan/create_deep_plan
• docs/ native Pi review/bridge reference docs

Requirements

Primary requirements are in:

• doc/specs/deepwork-pi/PI-REQ-001-native-pi-extension.md
• doc/specs/deepwork-pi/PI-REQ-002-native-pi-tools.md
• doc/specs/deepwork-pi/PI-REQ-003-native-pi-reviews.md

Reuse guidance

The native Pi package should preserve existing DeepWork workflow, review, DeepSchema, and state-management semantics instead of forking behavior.