DevCrew

English | 简体中文

DevCrew is a local workflow service for Codex and Claude Code. It gives coding agents a gated professional delivery process:

Requester -> Product Manager -> Architect -> Implementer -> Tester -> Acceptance.

The first release is intentionally local-first. DevCrew stores workflow state and artifacts in the repository, exposes MCP tools for agent-host interaction, and generates Codex and Claude Code plugin bundles.

Features

• Gated phases for requirements, architecture, implementation planning, and test reporting.
• Two workflow modes: feature for existing repositories and greenfield for new products.
• Safe execution modes: plan is the default; apply must be explicit. Apply defaults to interactive-host, which pauses for the host-native agent in a DevCrew-owned Git worktree; explicit headless policies use separately declared SDK permissions.
• Host-preferred backend selection: Codex runs default to Codex, Claude Code runs default to Claude.
• Orchestrated role execution: devcrew_start runs the PM role, and devcrew_continue runs the next phase role before opening the gate.
• Implementation review artifact: isolated execution records changed files, a binary-capable diff, lint evidence, and architecture compliance notes; testing refreshes the reviewed diff before promotion.
• Structured architecture review: execution must receive an architect decision of approved or changes_required; required changes block testing.
• Repository artifacts in .devcrew/runs/<run-id>/state.json and docs/devcrew/<run-id>/.
• Standards discovery from .devcrew/standards.md, AGENTS.md, CLAUDE.md, README, and common project manifests.
• MCP tools: devcrew_start, devcrew_status, devcrew_answer, devcrew_approve, devcrew_reject, devcrew_continue, devcrew_complete_execution, devcrew_waive_verification, and devcrew_artifact.
• Codex and Claude Code plugin scaffolds generated by devcrew init.

Install As A Codex Plugin

Add the DevCrew marketplace:

codex plugin marketplace add lishen802/devcrew

Restart Codex, open the plugin directory, choose the DevCrew marketplace, and install the DevCrew plugin.

The plugin starts the DevCrew MCP server with:

npm exec --silent --yes --package=@shenlee/devcrew@0.1.5 -- node -e "<DevCrew CLI wrapper>" -- serve --stdio

The plugin locks the MCP server to the published npm package version, so users do not need to clone the source or build TypeScript at install time. You only need Node.js and network access the first time Codex starts the MCP server.

Install From npm

npm install -g @shenlee/devcrew
devcrew doctor /path/to/repo

The npm package is published as @shenlee/devcrew, while the installed CLI command remains devcrew. It declares the Codex and Claude Agent SDKs as optional dependencies. npm installs optional dependencies by default; if your environment omits them, reinstall with npm install -g @shenlee/devcrew --include=optional. devcrew doctor reports whether @openai/codex-sdk and @anthropic-ai/claude-agent-sdk are resolvable for real host-backed apply workflows.

Install From Source

npm install
npm run validate
npm link

Then initialize a project:

devcrew init /path/to/repo
devcrew doctor /path/to/repo

Use In An Agent

Start the MCP server through the generated plugin configuration:

devcrew serve --stdio

In Codex or Claude Code, invoke the generated DevCrew skill and ask for a workflow:

Use DevCrew to plan and implement audit logging for the billing API.

The agent should call devcrew_start, show the PM-generated requirements artifact, then wait for approval before moving to architecture. After each approval, devcrew_continue runs the next role and writes its Markdown artifact before opening the next gate.

Plugins set DEVCREW_HOST for host detection, so devcrew_start can omit host unless you want to override it. DevCrew records the latest run as the repository's active run, so follow-up MCP calls can omit runId.

By default DevCrew runs in plan mode. To allow isolated execution to modify files and isolated testing to run configured verification commands, explicitly request apply mode:

Use DevCrew in apply mode to implement audit logging for the billing API.

Apply mode follows this sequence:

requirements approval
-> architecture approval
-> implementation plan approval
-> isolated execution
-> architecture review approval
-> isolated testing
-> testing approval
-> patch promotion to requester repository

Apply requires a Git repository and a clean requester worktree when isolated execution starts and when the patch is promoted. The default interactive-host policy does not start a nested SDK: after each devcrew_continue, it waits at awaiting_execution for the host-native agent to work in the indicated isolated worktree. Call devcrew_complete_execution after implementation, and again after testing with command, exit-code, and output evidence. Explicit headless-restricted and headless-unattended policies instead use DevCrew-managed SDK permissions; they do not inherit the current host approval session. The requester repository is unchanged until the testing gate is approved. Failed verification moves the run to awaiting_input and cannot be promoted unless devcrew_waive_verification records an explicit risk reason. Rejecting testing and answering the feedback returns the same isolated workspace to execution without changing the requester repository.

DevCrew auto-discovers verification commands from common project manifests. The current rules prefer package.json scripts (validate, then test, then typecheck/lint), then fall back to go test ./..., cargo test, or python -m pytest when matching manifests are present.

You can override discovery with explicit commands in .devcrew/config.json:

{
  "version": 1,
  "defaultBackend": "host-preferred",
  "executionMode": "plan",
  "verifyCommands": ["npm run validate"],
  "workflow": {
    "gates": ["requirements", "architecture", "implementation", "implementation-review", "testing"],
    "artifactDirectory": "docs/devcrew"
  }
}

workflow.gates controls only whether the requester must manually approve the requirements, architecture, and implementation artifacts. Omitting one of those names still runs its role and writes its artifact, then advances to the next phase automatically. implementation-review and testing are mandatory safety gates and are always enabled, even when omitted from the configuration.

Development

npm test
npm run build
npm run validate
npm pack --dry-run

The SDK adapters use deterministic local fallback output when Codex or Claude SDK packages are not installed. This keeps local tests reliable while preserving the adapter boundary for real host integration. Nested SDK apply runs use the recorded DevCrew headless policy; they never inherit the current host sandbox or approval session.

For published installs, the host SDK packages are pinned optional dependencies so the version-locked npm exec --package=@shenlee/devcrew@<version> wrapper can resolve them from the DevCrew package itself. Plan mode can still fall back to deterministic artifacts, but apply mode fails with a clear SDK resolution error if the selected host SDK is unavailable.

Public npm publishing is handled by the npm publish GitHub Actions workflow. It runs validation, checks the package with npm pack --dry-run, and publishes with npm provenance when a GitHub Release is published or the workflow is manually dispatched with NPM_TOKEN configured.

After publishing the version locked by the plugin, run the real marketplace smoke test. This is a post-publication check because the plugin is version-locked to the npm package:

npm run smoke:codex-plugin

It installs DevCrew from the Codex marketplace into an isolated CODEX_HOME, starts the installed MCP server, and runs a full plan-mode workflow.

Documentation

• Quickstart
• Codex setup
• Claude Code setup
• Workflow model
• Role customization
• Examples

License

Apache-2.0