cxg-workflow 0.1.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 fengshao1227
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,266 @@
+# CXG - Codex Single-Model Structured Workflow
+
+<div align="center">
+
+English | [简体中文](./README.zh-CN.md)
+
+</div>
+
+CXG is a Codex-first workflow package for Codex CLI. It installs a structured set of slash commands, skills, role prompts, and a `codeagent-wrapper` binary so Codex can handle research, planning, execution, optimization, and review in a consistent single-model workflow.
+
+> Note: CXG is a Codex-only simplified derivative of [`ccg-workflow`](https://github.com/fengshao1227/ccg-workflow). It keeps the structured workflow and wrapper-based orchestration ideas from the original project, while narrowing the scope to a leaner single-model experience built around Codex.
+
+## Why CXG?
+
+- **Derived from `ccg-workflow`**: preserves the original workflow philosophy while simplifying it into a Codex-only package.
+- **Single-model by design**: no routing between different models, only Codex orchestration plus Codex subprocess roles.
+- **Structured delivery**: the main workflow follows `research -> plan -> execute -> optimize -> review`.
+- **Reusable expert roles**: built-in `analyzer`, `architect`, and `reviewer` role prompts drive subprocess work.
+- **Optional code retrieval**: supports `ace-tool`, can be prepared for `contextweaver`, and falls back to `Glob + Grep` when MCP is skipped.
+- **Ready-to-use slash commands**: installs 12 commands directly into `~/.codex/prompts/`.
+
+## Architecture
+
+```text
+Codex CLI
+   |
+   +-- /cxg-* custom prompts
+   |
+   +-- skills/cxg/*
+   |
+   +-- codeagent-wrapper
+          |
+          +-- Codex subprocess (analyzer / architect / reviewer)
+```
+
+The main Codex session orchestrates the workflow. Subprocesses are used for focused analysis, planning, and review, then their output is fed back into the main session.
+
+## Quick Start
+
+### Prerequisites
+
+| Dependency | Required | Notes |
+|------------|----------|-------|
+| Node.js | Yes | Node.js 18+ recommended for modern ESM and built-in `fetch` |
+| Codex CLI | Yes | CXG installs commands into `~/.codex/` for Codex CLI to use |
+| GitHub Releases access | Yes | `init` downloads `codeagent-wrapper` during installation |
+| ace-tool | No | Optional MCP retrieval provider |
+| ContextWeaver | No | Optional MCP retrieval provider, requires manual setup |
+
+### Installation
+
+```bash
+npx cxg-workflow init
+```
+
+Useful variants:
+
+```bash
+# overwrite existing CXG files
+npx cxg-workflow init --force
+
+# install without WebUI-related wrapper behavior
+npx cxg-workflow init --lite
+
+# configure ace-tool in ~/.codex/config.toml
+npx cxg-workflow init --mcp ace-tool
+
+# skip MCP and use filesystem search fallback
+npx cxg-workflow init --skip-mcp
+```
+
+After installation, open Codex CLI and invoke commands as slash commands such as:
+
+```bash
+/cxg-workflow implement user authentication
+/cxg-plan refactor payment service
+/cxg-review
+```
+
+### Verify Installation
+
+```bash
+npx cxg-workflow doctor
+```
+
+### Uninstall
+
+```bash
+npx cxg-workflow uninstall
+```
+
+## Commands
+
+### Core Workflow
+
+| Command | Description |
+|---------|-------------|
+| `/cxg-workflow` | Full 5-phase structured workflow |
+| `/cxg-plan` | Generate an implementation plan |
+| `/cxg-execute` | Execute an approved plan file |
+
+### Development
+
+| Command | Description |
+|---------|-------------|
+| `/cxg-feat` | Smart feature development |
+| `/cxg-analyze` | Technical analysis without code changes |
+| `/cxg-debug` | Diagnose and fix problems |
+| `/cxg-optimize` | Performance and resource optimization |
+
+### Quality
+
+| Command | Description |
+|---------|-------------|
+| `/cxg-test` | Test design and generation |
+| `/cxg-review` | Quality and security review |
+| `/cxg-enhance` | Turn vague requests into structured tasks |
+
+### Delivery And Bootstrap
+
+| Command | Description |
+|---------|-------------|
+| `/cxg-commit` | Generate Conventional Commit messages |
+| `/cxg-init` | Generate project `AGENTS.md` context docs |
+
+## Workflow Guides
+
+### Planning And Execution Separation
+
+```bash
+# 1. Generate the plan
+/cxg-plan implement user authentication
+
+# 2. Review and adjust the generated plan
+# plan file is saved under .codex/plan/
+
+# 3. Execute the approved plan
+/cxg-execute .codex/plan/user-auth.md
+```
+
+### Full Workflow For Larger Tasks
+
+```bash
+/cxg-workflow implement invoice export with audit logging
+```
+
+Use the full workflow when the task spans multiple modules, needs tradeoff analysis, or should go through an explicit optimization and review phase.
+
+### Initialize Project Context
+
+```bash
+/cxg-init build a modular AGENTS.md for this repository
+```
+
+This command generates root-level and module-level `AGENTS.md` files using a "concise at root, detailed by module" strategy.
+
+## Configuration
+
+### Installed Layout
+
+```text
+~/.codex/
+├── prompts/
+│   ├── cxg-workflow.md
+│   ├── cxg-plan.md
+│   └── ...
+├── skills/
+│   └── cxg/
+│       ├── workflow/SKILL.md
+│       ├── plan/SKILL.md
+│       └── ...
+├── bin/
+│   └── codeagent-wrapper
+├── config.toml              # Codex MCP config when ace-tool is enabled
+└── .cxg/
+    ├── config.toml
+    └── roles/
+        └── codex/
+            ├── analyzer.md
+            ├── architect.md
+            └── reviewer.md
+```
+
+### CXG Config
+
+CXG stores its own state in `~/.codex/.cxg/config.toml`, including:
+
+- installed command list
+- wrapper path
+- role prompt paths
+- selected MCP provider
+- whether `--lite` mode was used
+
+### MCP Options
+
+**`ace-tool`**
+
+- Install with `npx cxg-workflow init --mcp ace-tool`
+- CXG writes the MCP server entry into `~/.codex/config.toml`
+- Prompt templates use `mcp__ace-tool__search_context`
+
+**`contextweaver`**
+
+- Select with `npx cxg-workflow init --mcp contextweaver`
+- CXG records the provider and prints manual setup guidance
+- You still need to install `contextweaver` yourself and configure `~/.contextweaver/.env`
+
+**`skip`**
+
+- Default behavior
+- Prompt templates fall back to filesystem search via `Glob + Grep`
+
+## Supported Platforms
+
+`codeagent-wrapper` binaries are resolved per platform and architecture:
+
+- macOS `arm64` / `amd64`
+- Linux `arm64` / `amd64`
+- Windows `arm64` / `amd64`
+
+## GitHub CI/CD
+
+CXG can use GitHub Actions for both CI and npm release automation:
+
+- `CI`: runs on every push and pull request to `main`, executing `pnpm lint`, `pnpm typecheck`, `pnpm test`, and `pnpm build` on Node.js 20 and 22.
+- `Publish to npm`: runs when a Git tag matching `v*.*.*` is pushed. The workflow verifies that the tag matches `package.json`, reruns validation, and publishes the package to npm as `public` with provenance enabled.
+
+Required repository secret:
+
+- `NPM_TOKEN`: npm automation token with publish access to the `cxg-workflow` package
+
+Recommended release flow:
+
+```bash
+pnpm lint
+pnpm typecheck
+pnpm test
+pnpm build
+git commit -am "chore: release v0.1.1"
+git tag v0.1.1
+git push origin main --tags
+```
+
+`codeagent-wrapper` is still downloaded from the shared GitHub Release maintained by `fengshao1227/ccg-workflow` under the `preset` tag. CXG's GitHub workflow added here covers the npm package itself, not binary compilation.
+
+## FAQ
+
+### The slash commands do not appear in Codex CLI
+
+Run `npx cxg-workflow init`, then restart Codex CLI. CXG installs prompt files into `~/.codex/prompts/`, which Codex loads as slash commands.
+
+### Installation failed while downloading `codeagent-wrapper`
+
+`init` fetches the binary from GitHub Releases. Check network access first, then rerun:
+
+```bash
+npx cxg-workflow init --force
+```
+
+### I selected `contextweaver`, but retrieval still does not work
+
+That option does not fully provision ContextWeaver for you. Install the `contextweaver` executable and configure `~/.contextweaver/.env`, or switch to `ace-tool`.
+
+## License
+
+MIT

package/README.zh-CN.md

@@ -0,0 +1,266 @@
+# CXG - Codex 单模型结构化工作流
+
+<div align="center">
+
+[English](./README.md) | 简体中文
+
+</div>
+
+CXG 是一个面向 Codex CLI 的单模型工作流包。它会安装一组结构化 Slash Commands、Skills、角色提示词和 `codeagent-wrapper` 二进制，使 Codex 能以统一方式完成研究、规划、执行、优化和评审。
+
+> 说明：CXG 基于 [`ccg-workflow`](https://github.com/fengshao1227/ccg-workflow) 项目衍生而来，可视为面向 Codex 的单模型简化版。它保留了原项目的结构化工作流与 wrapper 编排思路，但将范围收敛为更精简的 Codex-only 使用体验。
+
+## 为什么选择 CXG？
+
+- **基于 `ccg-workflow` 衍生**：延续原项目的工作流设计思路，同时简化为仅面向 Codex 的轻量版本。
+- **单模型协作**：不做多模型路由，只使用 Codex 主会话加 Codex 子进程角色分工。
+- **结构化交付**：主工作流固定为 `研究 -> 计划 -> 执行 -> 优化 -> 评审`。
+- **内置专家角色**：提供 `analyzer`、`architect`、`reviewer` 三类角色提示词。
+- **可选代码检索**：支持 `ace-tool`，可预留 `contextweaver`，不配置 MCP 时自动退回 `Glob + Grep`。
+- **直接可用的 Slash Commands**：安装后会把 12 个命令写入 `~/.codex/prompts/`。
+
+## 架构
+
+```text
+Codex CLI
+   |
+   +-- /cxg-* 自定义命令
+   |
+   +-- skills/cxg/*
+   |
+   +-- codeagent-wrapper
+          |
+          +-- Codex 子进程（analyzer / architect / reviewer）
+```
+
+主 Codex 会话负责整体编排，子进程负责聚焦分析、规划和审查，再把结果回传给主会话继续推进。
+
+## 快速开始
+
+### 前置条件
+
+| 依赖 | 必需 | 说明 |
+|------|------|------|
+| Node.js | 是 | 建议 Node.js 18+，便于兼容 ESM 和内置 `fetch` |
+| Codex CLI | 是 | CXG 会把命令安装到 `~/.codex/` 供 Codex CLI 使用 |
+| GitHub Releases 访问能力 | 是 | `init` 时会下载 `codeagent-wrapper` |
+| ace-tool | 否 | 可选的 MCP 代码检索提供者 |
+| ContextWeaver | 否 | 可选的 MCP 检索提供者，需要手动配置 |
+
+### 安装
+
+```bash
+npx cxg-workflow init
+```
+
+常用变体：
+
+```bash
+# 强制覆盖已有 CXG 文件
+npx cxg-workflow init --force
+
+# 精简模式安装
+npx cxg-workflow init --lite
+
+# 在 ~/.codex/config.toml 中配置 ace-tool
+npx cxg-workflow init --mcp ace-tool
+
+# 跳过 MCP，使用文件系统检索兜底
+npx cxg-workflow init --skip-mcp
+```
+
+安装完成后，在 Codex CLI 中以 Slash Command 方式调用：
+
+```bash
+/cxg-workflow 实现用户认证
+/cxg-plan 重构支付服务
+/cxg-review
+```
+
+### 验证安装
+
+```bash
+npx cxg-workflow doctor
+```
+
+### 卸载
+
+```bash
+npx cxg-workflow uninstall
+```
+
+## 命令
+
+### 核心工作流
+
+| 命令 | 说明 |
+|------|------|
+| `/cxg-workflow` | 完整 5 阶段结构化工作流 |
+| `/cxg-plan` | 生成实施计划 |
+| `/cxg-execute` | 按已批准的计划文件执行 |
+
+### 开发类
+
+| 命令 | 说明 |
+|------|------|
+| `/cxg-feat` | 智能功能开发 |
+| `/cxg-analyze` | 只分析，不改代码 |
+| `/cxg-debug` | 问题诊断与修复 |
+| `/cxg-optimize` | 性能与资源优化 |
+
+### 质量类
+
+| 命令 | 说明 |
+|------|------|
+| `/cxg-test` | 测试设计与生成 |
+| `/cxg-review` | 质量与安全审查 |
+| `/cxg-enhance` | 将模糊需求整理成结构化任务 |
+
+### 交付与初始化
+
+| 命令 | 说明 |
+|------|------|
+| `/cxg-commit` | 生成 Conventional Commit 提交信息 |
+| `/cxg-init` | 生成项目 `AGENTS.md` 上下文文档 |
+
+## 工作流指南
+
+### 计划与执行分离
+
+```bash
+# 1. 生成计划
+/cxg-plan 实现用户认证
+
+# 2. 审查并调整生成的计划
+# 计划文件保存在 .codex/plan/ 下
+
+# 3. 执行已批准的计划
+/cxg-execute .codex/plan/user-auth.md
+```
+
+### 复杂任务使用完整工作流
+
+```bash
+/cxg-workflow 实现发票导出与审计日志
+```
+
+当任务跨多个模块、需要方案权衡、或者希望显式经过优化与评审阶段时，优先使用完整工作流。
+
+### 初始化项目上下文
+
+```bash
+/cxg-init 为当前仓库生成模块化 AGENTS.md
+```
+
+该命令会按“根级简明、模块级详尽”的策略生成根目录和模块目录下的 `AGENTS.md`。
+
+## 配置
+
+### 安装后的目录结构
+
+```text
+~/.codex/
+├── prompts/
+│   ├── cxg-workflow.md
+│   ├── cxg-plan.md
+│   └── ...
+├── skills/
+│   └── cxg/
+│       ├── workflow/SKILL.md
+│       ├── plan/SKILL.md
+│       └── ...
+├── bin/
+│   └── codeagent-wrapper
+├── config.toml              # 启用 ace-tool 时写入 Codex MCP 配置
+└── .cxg/
+    ├── config.toml
+    └── roles/
+        └── codex/
+            ├── analyzer.md
+            ├── architect.md
+            └── reviewer.md
+```
+
+### CXG 配置文件
+
+CXG 自身状态保存在 `~/.codex/.cxg/config.toml`，包含：
+
+- 已安装命令列表
+- wrapper 路径
+- 角色提示词路径
+- 当前 MCP provider
+- 是否启用 `--lite`
+
+### MCP 配置
+
+**`ace-tool`**
+
+- 使用 `npx cxg-workflow init --mcp ace-tool`
+- CXG 会把 MCP 服务写入 `~/.codex/config.toml`
+- 命令模板内部调用 `mcp__ace-tool__search_context`
+
+**`contextweaver`**
+
+- 使用 `npx cxg-workflow init --mcp contextweaver`
+- CXG 只会记录 provider 并提示你继续手动配置
+- 你仍需自行安装 `contextweaver` 可执行文件并配置 `~/.contextweaver/.env`
+
+**`skip`**
+
+- 默认模式
+- 命令模板自动退回 `Glob + Grep` 文件系统检索
+
+## 支持平台
+
+`codeagent-wrapper` 会按平台和架构自动选择二进制：
+
+- macOS `arm64` / `amd64`
+- Linux `arm64` / `amd64`
+- Windows `arm64` / `amd64`
+
+## GitHub CI/CD
+
+CXG 可以通过 GitHub Actions 完成 CI 和 npm 自动发布：
+
+- `CI`：在每次向 `main` 分支 push 或发起 PR 时运行，执行 `pnpm lint`、`pnpm typecheck`、`pnpm test`、`pnpm build`，并覆盖 Node.js 20、22。
+- `Publish to npm`：在推送匹配 `v*.*.*` 的 Git tag 时触发。工作流会先校验 tag 与 `package.json` 版本一致，再重新执行校验，并以 `public` 访问级别发布到 npm，同时开启 provenance。
+
+需要配置的仓库 Secret：
+
+- `NPM_TOKEN`：具备 `cxg-workflow` 发布权限的 npm automation token
+
+推荐发版流程：
+
+```bash
+pnpm lint
+pnpm typecheck
+pnpm test
+pnpm build
+git commit -am "chore: release v0.1.1"
+git tag v0.1.1
+git push origin main --tags
+```
+
+当前 `codeagent-wrapper` 仍然从 `fengshao1227/ccg-workflow` 仓库的 GitHub Release `preset` tag 下载。这里新增的 GitHub 工作流只负责 `cxg-workflow` npm 包本身，不负责编译二进制。
+
+## 常见问题
+
+### Codex CLI 里看不到 Slash Commands
+
+先执行 `npx cxg-workflow init`，然后重启 Codex CLI。CXG 的命令本质上是写入 `~/.codex/prompts/` 的 prompt 文件，需由 Codex 重新加载。
+
+### 安装时 `codeagent-wrapper` 下载失败
+
+`init` 会从 GitHub Releases 拉取二进制。先检查网络，再重试：
+
+```bash
+npx cxg-workflow init --force
+```
+
+### 选择了 `contextweaver`，但代码检索仍然不可用
+
+这个选项不会自动把 ContextWeaver 完整装好。你需要自己安装 `contextweaver` 命令并配置 `~/.contextweaver/.env`；如果不想手动处理，直接改用 `ace-tool`。
+
+## License
+
+MIT

package/bin/cxg.mjs

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+import '../dist/cli.mjs'

package/dist/cli.d.mts

@@ -0,0 +1 @@
+

package/dist/cli.d.ts

@@ -0,0 +1 @@
+

package/dist/cli.mjs

@@ -0,0 +1,47 @@
+#!/usr/bin/env node
+import cac from 'cac';
+import { i as init, u as uninstall, d as doctor, v as version } from './shared/cxg-workflow.BdjkxkKP.mjs';
+import 'fs-extra';
+import 'node:os';
+import 'pathe';
+import 'node:url';
+import 'smol-toml';
+
+const VALID_MCP_PROVIDERS = ["skip", "ace-tool", "contextweaver"];
+function setupCommands(cli) {
+  cli.command("", "CXG Workflow - Codex \u5355\u6A21\u578B\u534F\u4F5C\u5DE5\u4F5C\u6D41").action(() => {
+    cli.outputHelp();
+  });
+  cli.command("init", "\u5B89\u88C5 CXG \u5DE5\u4F5C\u6D41\u5230 ~/.codex/").alias("i").option("--force, -f", "\u5F3A\u5236\u8986\u76D6\u5DF2\u6709\u6587\u4EF6").option("--lite", "\u7CBE\u7B80\u6A21\u5F0F\uFF08\u7981\u7528 WebUI\uFF09").option("--mcp <provider>", "MCP \u4EE3\u7801\u68C0\u7D22\u63D0\u4F9B\u8005 (ace-tool|contextweaver|skip)", { default: "skip" }).option("--skip-mcp", "\u8DF3\u8FC7 MCP \u914D\u7F6E").action(async (options) => {
+    const provider = options.skipMcp ? "skip" : options.mcp || "skip";
+    if (!VALID_MCP_PROVIDERS.includes(provider)) {
+      console.error(`  \u2717 \u65E0\u6548\u7684 MCP provider: ${provider}`);
+      console.error(`    \u6709\u6548\u503C: ${VALID_MCP_PROVIDERS.join(", ")}`);
+      process.exitCode = 1;
+      return;
+    }
+    await init({
+      force: options.force,
+      liteMode: options.lite,
+      mcpProvider: provider
+    });
+  });
+  cli.command("uninstall", "\u5378\u8F7D CXG \u5DE5\u4F5C\u6D41").alias("rm").action(async () => {
+    await uninstall();
+  });
+  cli.command("doctor", "\u8BCA\u65AD CXG \u5B89\u88C5\u5B8C\u6574\u6027").action(async () => {
+    await doctor();
+  });
+  cli.help();
+  cli.version(version);
+}
+
+async function main() {
+  const cli = cac("cxg");
+  setupCommands(cli);
+  cli.parse();
+}
+main().catch((error) => {
+  console.error(error);
+  process.exitCode = 1;
+});