@shenlee/devcrew 0.1.0

package/dist/packages/service/src/tools.js

@@ -0,0 +1,177 @@
+import { approveWorkflow, getArtifact, getActiveRunId, getWorkflowStatus, setActiveRun, } from "../../core/src/index.js";
+import { answerOrchestratedWorkflow, continueOrchestratedWorkflow, rejectOrchestratedWorkflow, startOrchestratedWorkflow, } from "../../orchestrator/src/index.js";
+const cwdProperty = { type: "string", description: "Repository working directory." };
+const runIdProperty = { type: "string", description: "DevCrew run id." };
+const hostValues = ["codex", "claude"];
+function inferHost(env = process.env) {
+    const host = env.DEVCREW_HOST;
+    return host === "claude" || host === "codex" ? host : "codex";
+}
+async function withActiveRun(args) {
+    if (typeof args.runId === "string" && args.runId.trim()) {
+        return args;
+    }
+    if (typeof args.cwd !== "string" || !args.cwd.trim()) {
+        return args;
+    }
+    return { ...args, runId: await getActiveRunId(args.cwd) };
+}
+function withInferredHost(args) {
+    if (typeof args.host === "string" && hostValues.includes(args.host)) {
+        return args;
+    }
+    return { ...args, host: inferHost() };
+}
+export function listDevCrewTools() {
+    return [
+        {
+            name: "devcrew_start",
+            description: "Create a new gated DevCrew workflow run.",
+            inputSchema: {
+                type: "object",
+                required: ["cwd", "mode", "request"],
+                properties: {
+                    cwd: cwdProperty,
+                    host: { type: "string", enum: ["codex", "claude"], description: "Optional host override. Defaults to DEVCREW_HOST or codex." },
+                    mode: { type: "string", enum: ["feature", "greenfield"] },
+                    executionMode: {
+                        type: "string",
+                        enum: ["plan", "apply"],
+                        description: "Execution mode. Defaults to plan; apply must be explicit.",
+                    },
+                    request: { type: "string" },
+                    backend: { type: "string", enum: ["codex", "claude", "local"] },
+                },
+            },
+        },
+        {
+            name: "devcrew_status",
+            description: "Read the status of a DevCrew workflow run.",
+            inputSchema: {
+                type: "object",
+                required: ["cwd"],
+                properties: { cwd: cwdProperty, runId: runIdProperty },
+            },
+        },
+        {
+            name: "devcrew_answer",
+            description: "Record requester clarification input for the current gate.",
+            inputSchema: {
+                type: "object",
+                required: ["cwd", "answer"],
+                properties: { cwd: cwdProperty, runId: runIdProperty, answer: { type: "string" } },
+            },
+        },
+        {
+            name: "devcrew_approve",
+            description: "Approve the current workflow gate and advance to the next phase.",
+            inputSchema: {
+                type: "object",
+                required: ["cwd", "gate"],
+                properties: {
+                    cwd: cwdProperty,
+                    runId: runIdProperty,
+                    gate: { type: "string", enum: ["requirements", "architecture", "implementation", "testing"] },
+                    note: { type: "string" },
+                },
+            },
+        },
+        {
+            name: "devcrew_reject",
+            description: "Reject the current workflow gate and record feedback.",
+            inputSchema: {
+                type: "object",
+                required: ["cwd", "gate", "feedback"],
+                properties: {
+                    cwd: cwdProperty,
+                    runId: runIdProperty,
+                    gate: { type: "string", enum: ["requirements", "architecture", "implementation", "testing"] },
+                    feedback: { type: "string" },
+                },
+            },
+        },
+        {
+            name: "devcrew_continue",
+            description: "Continue a run after the previous gate was approved.",
+            inputSchema: {
+                type: "object",
+                required: ["cwd"],
+                properties: { cwd: cwdProperty, runId: runIdProperty },
+            },
+        },
+        {
+            name: "devcrew_artifact",
+            description: "Read a generated workflow artifact.",
+            inputSchema: {
+                type: "object",
+                required: ["cwd", "name"],
+                properties: {
+                    cwd: cwdProperty,
+                    runId: runIdProperty,
+                    name: {
+                        type: "string",
+                        enum: ["requirements", "architecture", "implementation-plan", "implementation-review", "test-report", "acceptance"],
+                    },
+                },
+            },
+        },
+    ];
+}
+function summarizeState(state) {
+    const pendingGate = Object.entries(state.gates).find(([, status]) => status === "pending")?.[0] ?? "none";
+    const role = state.roles.at(-1);
+    const roleFallback = role?.usedFallback === true ? (role.backend === "local" ? "local" : "sdk") : role ? "none" : "none";
+    return `Run ${state.runId}: phase=${state.phase}, status=${state.status}, execution_mode=${state.executionMode}, pending_gate=${pendingGate}, role_fallback=${roleFallback}`;
+}
+function success(text, structuredContent) {
+    return {
+        isError: false,
+        content: [{ type: "text", text }],
+        structuredContent,
+    };
+}
+function failure(error) {
+    const message = error instanceof Error ? error.message : String(error);
+    return {
+        isError: true,
+        content: [{ type: "text", text: message }],
+        structuredContent: { error: message },
+    };
+}
+export async function callDevCrewTool(name, args) {
+    try {
+        if (name === "devcrew_start") {
+            const state = await startOrchestratedWorkflow(withInferredHost(args));
+            await setActiveRun(state.cwd, state.runId);
+            return success(`${summarizeState(state)}. Review ${state.artifacts.requirements}`, { state });
+        }
+        if (name === "devcrew_status") {
+            const state = await getWorkflowStatus((await withActiveRun(args)));
+            return success(summarizeState(state), { state });
+        }
+        if (name === "devcrew_answer") {
+            const state = await answerOrchestratedWorkflow((await withActiveRun(args)));
+            return success(`${summarizeState(state)}. Answer recorded.`, { state });
+        }
+        if (name === "devcrew_approve") {
+            const state = await approveWorkflow((await withActiveRun(args)));
+            return success(`${summarizeState(state)}. Gate approved.`, { state });
+        }
+        if (name === "devcrew_reject") {
+            const state = await rejectOrchestratedWorkflow((await withActiveRun(args)));
+            return success(`${summarizeState(state)}. Gate rejected.`, { state });
+        }
+        if (name === "devcrew_continue") {
+            const state = await continueOrchestratedWorkflow((await withActiveRun(args)));
+            return success(`${summarizeState(state)}.`, { state });
+        }
+        if (name === "devcrew_artifact") {
+            const artifact = await getArtifact((await withActiveRun(args)));
+            return success(artifact.content, { artifact });
+        }
+        throw new Error(`Unknown DevCrew tool: ${name}`);
+    }
+    catch (error) {
+        return failure(error);
+    }
+}

package/docs/claude-code.md

@@ -0,0 +1,37 @@
+# Claude Code Setup
+
+Run:
+
+```bash
+devcrew init /path/to/repo
+devcrew doctor /path/to/repo
+```
+
+The Claude Code plugin is generated at:
+
+```text
+plugins/devcrew-claude/
+```
+
+It contains:
+
+- `.claude-plugin/plugin.json`
+- `skills/devcrew/SKILL.md`
+- `agents/*.md`
+- `.mcp.json`
+
+For local plugin testing:
+
+```bash
+claude --plugin-dir plugins/devcrew-claude
+```
+
+Then ask Claude Code to use DevCrew for a feature or product workflow. The generated `.mcp.json` starts the version-locked npm package with `npx -y @shenlee/devcrew@0.1.0 serve --stdio`.
+
+Claude Code permissions, hooks, and approval settings remain authoritative. DevCrew inherits the host boundary.
+
+For apply mode, `@anthropic-ai/claude-agent-sdk` must be resolvable from the installed DevCrew package. Published DevCrew packages declare it as an optional dependency, which npm installs by default. If `devcrew doctor` reports it as missing, reinstall DevCrew with optional dependencies enabled:
+
+```bash
+npm install -g @shenlee/devcrew --include=optional
+```

package/docs/codex.md

@@ -0,0 +1,80 @@
+# Codex Setup
+
+## Plugin marketplace install
+
+Add the DevCrew marketplace:
+
+```bash
+codex plugin marketplace add lishen802/devcrew
+```
+
+Restart Codex, open the plugin directory, select the DevCrew marketplace, and install the DevCrew plugin.
+
+The plugin launches the MCP server with:
+
+```bash
+npx -y @shenlee/devcrew@0.1.0 serve --stdio
+```
+
+Use this path when you want to use DevCrew without cloning the repository first. The version is locked to the published npm package that matches the plugin manifest.
+
+## Local development install
+
+Run:
+
+```bash
+devcrew init /path/to/repo
+devcrew doctor /path/to/repo
+```
+
+The Codex plugin is generated at:
+
+```text
+plugins/devcrew-codex/
+```
+
+It contains:
+
+- `.codex-plugin/plugin.json`
+- `skills/devcrew/SKILL.md`
+- `.mcp.json`
+- role agent TOML templates under `agents/`
+
+For local development, point a Codex marketplace entry at the generated plugin folder, or copy the plugin into your existing local marketplace workflow.
+
+The DevCrew skill tells Codex to use these MCP tools:
+
+- `devcrew_start`
+- `devcrew_status`
+- `devcrew_answer`
+- `devcrew_approve`
+- `devcrew_reject`
+- `devcrew_continue`
+- `devcrew_artifact`
+
+Codex sandbox and approval settings remain authoritative. DevCrew does not bypass them.
+
+For apply mode, `@openai/codex-sdk` must be resolvable from the installed DevCrew package. Published DevCrew packages declare it as an optional dependency, which npm installs by default. If `devcrew doctor` reports it as missing, reinstall DevCrew with optional dependencies enabled:
+
+```bash
+npm install -g @shenlee/devcrew --include=optional
+```
+
+## Marketplace smoke test
+
+After publishing the npm package version referenced by the plugin, run the real marketplace smoke test:
+
+```bash
+npm run smoke:codex-plugin
+```
+
+The smoke test creates an isolated `CODEX_HOME`, adds the `lishen802/devcrew` marketplace, installs `devcrew@devcrew`, starts the installed plugin's MCP server from `.mcp.json`, and runs a complete plan-mode workflow through JSON-RPC.
+
+Useful options:
+
+```bash
+node scripts/smoke-codex-plugin.mjs --keep-temp
+node scripts/smoke-codex-plugin.mjs --source lishen802/devcrew --ref main
+```
+
+The default path is intentionally production-like: it uses the GitHub marketplace and the version-locked npm package from the installed plugin. It requires network access, Codex CLI, Node.js, and a published `@shenlee/devcrew` npm version matching the plugin manifest.

package/docs/quickstart.md

@@ -0,0 +1,64 @@
+# Quickstart
+
+## 1. Install
+
+From npm:
+
+```bash
+npm install -g @shenlee/devcrew
+```
+
+For local development:
+
+```bash
+npm install
+npm run validate
+npm link
+```
+
+## 2. Initialize A Repository
+
+```bash
+devcrew init /path/to/repo
+```
+
+This creates:
+
+- `.devcrew/config.json`
+- `.devcrew/standards.md`
+- `docs/devcrew/`
+- `plugins/devcrew-codex/`
+- `plugins/devcrew-claude/`
+
+## 3. Start The MCP Service
+
+```bash
+devcrew serve --stdio
+```
+
+Normally the generated plugin starts this command for the host agent.
+Codex and Claude plugin bundles use `npx -y @shenlee/devcrew@0.1.0 serve --stdio` so the MCP service is locked to the published package version.
+
+## 4. Run A Workflow
+
+Ask the host agent:
+
+```text
+Use DevCrew for this request: add release notes generation to this repository.
+```
+
+Expected flow:
+
+1. Agent calls `devcrew_start`.
+2. Agent reads `requirements.md`.
+3. You approve or reject requirements.
+4. Agent calls `devcrew_continue`.
+5. Repeat for architecture, implementation plan, and test report.
+
+## 5. Review Artifacts
+
+Artifacts are written under:
+
+```text
+docs/devcrew/<run-id>/
+```

package/docs/roles.md

@@ -0,0 +1,43 @@
+# Role Customization
+
+DevCrew ships with five roles.
+
+## conductor
+
+Owns workflow progression, gate discipline, and artifact routing.
+
+## pm
+
+Clarifies product goals, users, boundaries, success criteria, and requester approvals.
+
+## architect
+
+Designs technical architecture, interfaces, deployment considerations, and review criteria.
+
+## implementer
+
+Builds according to approved requirements and architecture while following discovered project standards.
+
+## tester
+
+Verifies behavior, runs or specifies validation commands, and prepares acceptance evidence.
+
+## Project Standards
+
+Put explicit standards in:
+
+```text
+.devcrew/standards.md
+```
+
+DevCrew also discovers:
+
+- `AGENTS.md`
+- `CLAUDE.md`
+- README files
+- `package.json`
+- `pyproject.toml`
+- `go.mod`
+- `Cargo.toml`
+
+Explicit DevCrew standards are included first.

package/docs/workflow.md

@@ -0,0 +1,70 @@
+# Workflow Model
+
+DevCrew uses a gated state machine plus an orchestrator layer.
+
+The core state machine persists run state and gate transitions. The orchestrator
+executes the role for the current phase, writes that role's Markdown artifact,
+records the role result in state, and then opens the phase gate for requester
+approval.
+
+## Modes
+
+- `feature`: existing repository work. The workflow emphasizes current conventions, code review, and regression tests.
+- `greenfield`: new product work. The workflow emphasizes product boundary, minimal architecture, and a shippable first slice.
+
+## Phases
+
+1. `requirements`: product manager clarifies scope, users, success criteria, and non-goals.
+2. `architecture`: architect defines technical approach, interfaces, deployment notes, and review criteria.
+3. `implementation`: implementer creates the implementation plan and coding checklist. DevCrew also writes `implementation-review.md` with changed files, captured diff, and architecture compliance review prompts before opening the implementation gate.
+4. `testing`: tester records validation strategy and acceptance evidence.
+5. `acceptance`: generated after the testing gate is approved.
+
+`devcrew_start` runs the PM role for `requirements`. After the requester approves
+a gate, `devcrew_continue` runs the role for the next phase before setting that
+phase's gate to `pending`.
+
+`devcrew_start` records the created run as the active run for the repository.
+Subsequent MCP calls can omit `runId`; DevCrew resolves it from
+`.devcrew/active-run.json`. Plugin MCP configs set `DEVCREW_HOST`, so `host`
+can also be omitted unless the caller needs an explicit override.
+
+## Gates
+
+Each main phase has a gate:
+
+- `requirements`
+- `architecture`
+- `implementation`
+- `testing`
+
+The requester approves or rejects each gate. Rejection records feedback and returns the workflow to `awaiting_input`.
+
+## State And Artifacts
+
+Runtime state is stored in:
+
+```text
+.devcrew/runs/<run-id>/state.json
+```
+
+The active run pointer is stored in:
+
+```text
+.devcrew/active-run.json
+```
+
+Reviewable artifacts are stored in:
+
+```text
+docs/devcrew/<run-id>/
+```
+
+The standard artifact set is:
+
+- `requirements.md`
+- `architecture.md`
+- `implementation-plan.md`
+- `implementation-review.md`
+- `test-report.md`
+- `acceptance.md`

package/examples/README.md

@@ -0,0 +1,11 @@
+# Examples
+
+## Existing Project Feature
+
+See [feature-request.md](feature-request.md).
+
+## Greenfield Product
+
+See [greenfield-request.md](greenfield-request.md).
+
+Both examples are meant to be submitted to Codex or Claude Code after installing the generated DevCrew plugin.

package/examples/feature-request.md

@@ -0,0 +1,13 @@
+# Feature Workflow Example
+
+```text
+Use DevCrew in feature mode.
+
+Request:
+Add project-level release notes generation. The tool should scan merged pull request titles and produce a Markdown changelog section.
+
+Constraints:
+- Follow existing package scripts.
+- Do not add a database.
+- Include tests for empty input and grouped changes.
+```

package/examples/greenfield-request.md

@@ -0,0 +1,14 @@
+# Greenfield Workflow Example
+
+```text
+Use DevCrew in greenfield mode.
+
+Request:
+Build a tiny issue tracker for a small engineering team.
+
+Constraints:
+- Local-first MVP.
+- Users can create, list, close, and reopen issues.
+- Store data in a JSON file for v1.
+- Include a CLI and tests.
+```

package/package.json

@@ -0,0 +1,60 @@
+{
+  "name": "@shenlee/devcrew",
+  "version": "0.1.0",
+  "description": "Multi-host agent workflow service for Codex and Claude Code.",
+  "type": "module",
+  "license": "Apache-2.0",
+  "homepage": "https://github.com/lishen802/devcrew#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/lishen802/devcrew.git"
+  },
+  "bugs": {
+    "url": "https://github.com/lishen802/devcrew/issues"
+  },
+  "keywords": [
+    "codex",
+    "claude-code",
+    "mcp",
+    "agents",
+    "workflow",
+    "plugin"
+  ],
+  "bin": {
+    "devcrew": "dist/packages/cli/src/index.js"
+  },
+  "files": [
+    "dist/packages",
+    "packages",
+    "plugins/devcrew-codex",
+    "scripts",
+    "docs",
+    "examples",
+    "README.md",
+    "LICENSE",
+    "CONTRIBUTING.md",
+    "SECURITY.md"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "test": "node --import tsx --test tests/*.test.ts",
+    "validate": "npm run build && npm test",
+    "smoke:codex-plugin": "node scripts/smoke-codex-plugin.mjs",
+    "prepack": "npm run build"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "devDependencies": {
+    "@types/node": "^20.19.0",
+    "tsx": "^4.20.0",
+    "typescript": "^5.8.0"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "optionalDependencies": {
+    "@anthropic-ai/claude-agent-sdk": "0.3.163",
+    "@openai/codex-sdk": "0.137.0"
+  }
+}