@shenlee/devcrew 0.1.0

package/CONTRIBUTING.md

@@ -0,0 +1,21 @@
+# Contributing
+
+## Development
+
+```bash
+npm install
+npm test
+npm run build
+npm run validate
+```
+
+## Pull Requests
+
+Keep changes scoped and include tests for behavior changes. For workflow behavior, update both tests and documentation.
+
+## Project Standards
+
+- Use TypeScript strict mode.
+- Prefer small modules with explicit inputs and outputs.
+- Keep host-specific behavior behind adapters.
+- Do not bypass Codex or Claude Code permission models.

package/LICENSE

@@ -0,0 +1,186 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        https://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work.
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on or derived from the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      patent license to make, have made, use, offer to sell, sell, import,
+      and otherwise transfer the Work, where such license applies only to
+      those patent claims licensable by such Contributor that are necessarily
+      infringed by their Contribution alone or by combination of their
+      Contribution with the Work to which such Contribution was submitted.
+      If You institute patent litigation against any entity alleging that
+      the Work or a Contribution incorporated within the Work constitutes
+      direct or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate as of
+      the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work on an "AS IS"
+      BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express
+      or implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   Copyright 2026 DevCrew Contributors
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       https://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -0,0 +1,142 @@
+# DevCrew
+
+English | [简体中文](README.zh-CN.md)
+
+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 explicitly requested before implementer/tester roles can write files or run validation commands.
+- 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: implementation gates include changed files, captured diff, and architecture compliance review notes.
+- 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`, and `devcrew_artifact`.
+- Codex and Claude Code plugin scaffolds generated by `devcrew init`.
+
+## Install As A Codex Plugin
+
+Add the DevCrew marketplace:
+
+```bash
+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:
+
+```bash
+npx -y @shenlee/devcrew@0.1.0 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
+
+```bash
+npm install -g @shenlee/devcrew
+devcrew --version
+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
+
+```bash
+npm install
+npm run validate
+npm link
+```
+
+Then initialize a project:
+
+```bash
+devcrew init /path/to/repo
+devcrew doctor /path/to/repo
+```
+
+## Use In An Agent
+
+Start the MCP server through the generated plugin configuration:
+
+```bash
+devcrew serve --stdio
+```
+
+In Codex or Claude Code, invoke the generated DevCrew skill and ask for a workflow:
+
+```text
+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 the implementer/tester phases to make repository changes and run configured verification commands, explicitly request apply mode:
+
+```text
+Use DevCrew in apply mode to implement audit logging for the billing API.
+```
+
+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`:
+
+```json
+{
+  "version": 1,
+  "defaultBackend": "host-preferred",
+  "executionMode": "plan",
+  "verifyCommands": ["npm run validate"],
+  "workflow": {
+    "gates": ["requirements", "architecture", "implementation", "testing"],
+    "artifactDirectory": "docs/devcrew"
+  }
+}
+```
+
+## Development
+
+```bash
+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. In `apply` mode, DevCrew still inherits the host sandbox and approval boundaries.
+
+For published installs, the host SDK packages are pinned optional dependencies so `npx -y @shenlee/devcrew@<version>` 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 npm version referenced by the Codex plugin, run the real marketplace smoke test:
+
+```bash
+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](docs/quickstart.md)
+- [Codex setup](docs/codex.md)
+- [Claude Code setup](docs/claude-code.md)
+- [Workflow model](docs/workflow.md)
+- [Role customization](docs/roles.md)
+- [Examples](examples/README.md)
+
+## License
+
+Apache-2.0

package/README.zh-CN.md

@@ -0,0 +1,156 @@
+# DevCrew
+
+[English](README.md) | 简体中文
+
+DevCrew 是一个面向 Codex、Claude Code 等编程 Agent 的本地工作流服务。它把一次功能或产品开发拆成带门禁的专业流程：
+
+需求提出者 -> 产品经理 -> 架构师 -> 实现工程师 -> 测试验收 -> 交付确认。
+
+项目目标是让 Agent 不只是“直接写代码”，而是像一个小型开发团队一样，先澄清需求、确认边界，再设计方案、实施、测试并产出可审查的文档。
+
+## 核心能力
+
+- 内置阶段门禁：需求确认、架构确认、实现计划确认、测试报告确认。
+- 支持两种工作流：`feature` 用于已有项目功能开发，`greenfield` 用于从零开始的新产品。
+- 支持安全执行模式：默认是 `plan`，只有显式请求 `apply` 时，implementer/tester 阶段才允许写文件或运行验证命令。
+- 默认按当前宿主选择后端：在 Codex 中优先使用 Codex，在 Claude Code 中优先使用 Claude。
+- 已接入角色编排：`devcrew_start` 会先运行 PM 角色，`devcrew_continue` 会运行下一阶段角色，然后再打开阶段门禁。
+- 实现评审产物：implementation gate 会附带 changed files、捕获的 diff 和架构符合性审查说明。
+- 运行状态写入 `.devcrew/runs/<run-id>/state.json`，评审产物写入 `docs/devcrew/<run-id>/`。
+- 自动发现项目规范：`.devcrew/standards.md`、`AGENTS.md`、`CLAUDE.md`、README 以及常见项目配置文件。
+- 提供 MCP 工具：`devcrew_start`、`devcrew_status`、`devcrew_answer`、`devcrew_approve`、`devcrew_reject`、`devcrew_continue`、`devcrew_artifact`。
+- 可通过 `devcrew init` 生成 Codex 和 Claude Code 插件骨架。
+
+## 作为 Codex 插件安装
+
+添加 DevCrew marketplace：
+
+```bash
+codex plugin marketplace add lishen802/devcrew
+```
+
+重启 Codex，打开插件目录，选择 DevCrew marketplace，然后安装 DevCrew 插件。
+
+插件会用下面的命令启动 DevCrew MCP 服务：
+
+```bash
+npx -y @shenlee/devcrew@0.1.0 serve --stdio
+```
+
+插件会锁定到已发布的 npm 包版本，因此用户不需要克隆源码，也不需要在安装时编译 TypeScript；只需要本机有 Node.js，并且 Codex 第一次启动 MCP 服务时可以访问网络。
+
+## 通过 npm 安装
+
+```bash
+npm install -g @shenlee/devcrew
+devcrew --version
+devcrew doctor /path/to/repo
+```
+
+npm 包发布名是 `@shenlee/devcrew`，安装后的 CLI 命令仍然是 `devcrew`。它会把 Codex SDK 和 Claude Agent SDK 声明为 optional dependencies。npm 默认会安装 optional dependencies；如果你的环境跳过了它们，可以用 `npm install -g @shenlee/devcrew --include=optional` 重新安装。`devcrew doctor` 会检查 `@openai/codex-sdk` 和 `@anthropic-ai/claude-agent-sdk` 是否可解析，用于确认真实宿主后端的 `apply` 流程是否可用。
+
+## 从源码安装
+
+```bash
+npm install
+npm run validate
+npm link
+```
+
+初始化一个项目：
+
+```bash
+devcrew init /path/to/repo
+devcrew doctor /path/to/repo
+```
+
+初始化后会生成：
+
+- `.devcrew/config.json`
+- `.devcrew/standards.md`
+- `docs/devcrew/`
+- `plugins/devcrew-codex/`
+- `plugins/devcrew-claude/`
+
+## 在 Agent 中使用
+
+通过生成的插件配置启动 MCP 服务：
+
+```bash
+devcrew serve --stdio
+```
+
+然后在 Codex 或 Claude Code 中调用 DevCrew，例如：
+
+```text
+使用 DevCrew 帮我规划并实现 billing API 的审计日志功能。
+```
+
+典型流程：
+
+1. Agent 调用 `devcrew_start` 创建工作流。
+2. DevCrew 运行 PM 角色生成需求文档并等待你确认。
+3. 你通过 `devcrew_approve` 或 `devcrew_reject` 推进或驳回阶段。
+4. 需求确认后，`devcrew_continue` 会运行架构师角色，再依次进入实现计划和测试验收。
+5. 所有产物都会保存在 `docs/devcrew/<run-id>/`，方便审查和版本管理。
+
+插件会设置 `DEVCREW_HOST` 用于宿主识别，因此 `devcrew_start` 可以省略 `host`，除非你需要显式覆盖。DevCrew 会把最新 run 记录为当前仓库的 active run，后续 MCP 调用可以省略 `runId`。
+
+默认情况下 DevCrew 使用安全的 `plan` 模式。如果你希望 implementer/tester 阶段真正修改仓库并运行配置好的验证命令，需要明确要求 apply 模式：
+
+```text
+使用 DevCrew apply 模式帮我实现 billing API 的审计日志功能。
+```
+
+DevCrew 会自动从常见项目清单中发现验证命令。当前规则会优先读取 `package.json` scripts（`validate`，然后是 `test`，再到 `typecheck`/`lint`），再按项目清单回退到 `go test ./...`、`cargo test` 或 `python -m pytest`。
+
+你也可以在 `.devcrew/config.json` 中显式覆盖：
+
+```json
+{
+  "version": 1,
+  "defaultBackend": "host-preferred",
+  "executionMode": "plan",
+  "verifyCommands": ["npm run validate"],
+  "workflow": {
+    "gates": ["requirements", "architecture", "implementation", "testing"],
+    "artifactDirectory": "docs/devcrew"
+  }
+}
+```
+
+## 开发命令
+
+```bash
+npm test
+npm run build
+npm run validate
+npm pack --dry-run
+```
+
+当前适配器在未安装 Codex SDK 或 Claude SDK 时会使用确定性的本地 fallback 输出。这样可以保证测试和演示稳定，同时保留接入真实宿主 SDK 的边界。即使在 `apply` 模式下，DevCrew 仍然继承宿主的 sandbox、审批和工具权限。
+
+对于发布安装，宿主 SDK 包会作为精确锁定的 optional dependencies 随 DevCrew 一起安装，因此 `npx -y @shenlee/devcrew@<version>` 可以从 DevCrew 包自身解析这些 SDK。plan 模式仍允许 deterministic fallback；但 apply 模式在选定宿主 SDK 不可用时会直接失败，并给出明确的 SDK 解析错误。
+
+公开 npm 发布由 `npm publish` GitHub Actions 工作流处理。发布 GitHub Release 或手动触发 workflow 时，它会先运行验证，再执行 `npm pack --dry-run` 检查包内容，最后在配置 `NPM_TOKEN` 后使用 npm provenance 发布公开包。
+
+当 Codex 插件引用的 npm 版本发布完成后，运行真实 marketplace smoke test：
+
+```bash
+npm run smoke:codex-plugin
+```
+
+它会在隔离的 `CODEX_HOME` 中从 Codex marketplace 安装 DevCrew，启动安装后的 MCP 服务，并跑完整的 plan 模式工作流。
+
+## 文档
+
+- [快速开始](docs/quickstart.md)
+- [Codex 接入](docs/codex.md)
+- [Claude Code 接入](docs/claude-code.md)
+- [工作流模型](docs/workflow.md)
+- [角色定制](docs/roles.md)
+- [示例](examples/README.md)
+
+## 许可证
+
+Apache-2.0

package/SECURITY.md

@@ -0,0 +1,19 @@
+# Security
+
+DevCrew is a local workflow service. It does not grant additional permissions beyond the host agent runtime.
+
+## Permission Model
+
+- Codex sandbox and approval settings remain authoritative in Codex.
+- Claude Code permissions and approval settings remain authoritative in Claude Code.
+- DevCrew records state and writes artifacts inside the target repository.
+
+## Reporting Issues
+
+For a public repository, open a private security advisory when available. Otherwise contact the maintainers before publishing exploit details.
+
+## Design Rules
+
+- Do not store secrets in `.devcrew/runs`.
+- Do not add network access to adapters without explicit configuration.
+- Do not execute destructive commands from the service layer.