cx-init

cx-init — initialize a pure CX 3.1 project environment

Overview

cx:init is the only reconfiguration wizard in the future pure cx 3.1 .

It is responsible for:

Individually confirm for each project developer_id
Initialize project-level 开发文档/CX工作流 and .cx
Establish in-project 配置.json and 状态.json
Install plugin-level hooks wiring
Check GitHub remote
If there is no remote, by default suggest creating a GitHub repository and binding it
Fill in the minimal project rules section

After initialization is complete, the project should be able to directly enter /cx:cx-prd or /cx:cx-fix。

Execution principles

This is the only centralized configuration interaction
Subsequent commands should interrupt the user as little as possible
Runtime truth is stored at the project level 开发文档/CX工作流 and .cx
hooks are provided by the plugin layer and are no longer copied into the project directory
The Claude Code plugin is only the runner cc adapter and does not directly own project truth

Execution flow

Step 1: Detect the project root directory and Git status

GIT_ROOT=$(git rev-parse --show-toplevel 2>/dev/null || pwd)

If the current directory is not a Git repository:

First suggest initializing Git
Continue after initialization

If an existing older version is detected .claude/cx but there is not yet a shared core/：

Do not directly enter dual-runner mode
First suggest running bash ${CLAUDE_PLUGIN_ROOT}/scripts/cx-core-migrate.sh
After migration is complete, continue /cx:cx-init or subsequent commands

Step 2: Collect key project configuration in one pass

Use checkbox-style Q&A, confirming in the following order:

developer_id
- Individually confirm developer_id for each project
- This is the project display name and is no longer used for feature directory naming
Whether to enable GitHub integration
Whether a GitHub remote already exists
- If there is no remote, by default suggest creating a GitHub repository and binding it
github_sync
- off
- local
- collab
- full
agent_teams
code_review
worktree_isolation
auto_memory

Step 3: Create the project-level cx directory

Create in the project:

开发文档/CX工作流/
├── 配置.json
├── 状态.json
├── 功能/
└── 修复/

At the same time ensure .worktrees/ directory exists and is ignored by .gitignore :

mkdir -p "$PROJECT_ROOT/.worktrees"
if ! grep -qxF '.worktrees' "$PROJECT_ROOT/.gitignore" 2>/dev/null; then
  echo '.worktrees' >> "$PROJECT_ROOT/.gitignore"
fi

Constraints:

Directory and document naming may use Chinese
JSON fields remain in English
Feature runtime state will later be placed in 功能/<中文标题>/状态.json
current_feature always stores a stable slug

Step 4: Generate project-level config.json

Generate 开发文档/CX工作流/配置.json, containing at least:

{
  "version": "3.0",
  "developer_id": "承玄",
  "github_sync": "local",
  "current_feature": "",
  "agent_teams": true,
  "code_review": true,
  "auto_memory": true,
  "worktree_isolation": true,
  "auto_format": {
    "enabled": true,
    "formatter": "auto"
  },
  "hooks": {
    "session_start": true,
    "pre_compact": true,
    "post_edit_format": true,
    "notification": true
  }
}

Step 5: Generate project-level state.json

Generate 开发文档/CX工作流/状态.json, only as a project index summary:

{
  "initialized_at": "2026-03-19T16:00:00Z",
  "last_updated": "2026-03-19T16:00:00Z",
  "current_feature": null,
  "features": {},
  "fixes": {}
}

Step 6: Dashboard auto keep-alive and project registration

After initialization is complete, ensure the dashboard service is available and register the current project:

PROJECT_ROOT=$(git rev-parse --show-toplevel)
bash ${CLAUDE_PLUGIN_ROOT}/scripts/cx-dashboard-ensure.sh
bridge_output=$(bash ${CLAUDE_PLUGIN_ROOT}/scripts/cx-dashboard-bridge.sh \
  --project-root "$PROJECT_ROOT" \
  --display-name "$(basename "$PROJECT_ROOT")")

Behavior rules (sharing the same semantics as cx-prd):

prompt_state=accepted：

Automatically restart a hung service, automatically register the current project
Inform of the dashboard address

prompt_state=pending：

Use AskUserQuestion to ask whether to enable
Do not block the init flow

prompt_state=declined：

More than 24h since the last check → ask again once
< 24h → silently skip
If prompt_state=accepted but service_running=false
- state that the bridge failed to start the panel or is still not ready
- you must truthfully tell the user "the integration has been recorded, but the panel has not yet started successfully"
- do not take only frontend_url or old runtime records and falsely report it as "already started"

Step 7: Verify plugin hooks dependency conditions

Project initialization no longer writes hooks to .claude/settings.json .

Key points:

Plugin hooks are automatically provided by the plugin itself via hooks/hooks.json Automatically provided
no longer copy hooks to the project runtime directory
Runtime hooks only read project-level 配置.json and feature-level 状态.json
cx:init only responsible for informing that the current project already has the runtime truth readable by plugin hooks
If the project uses an old layout, first migrate to the shared cx core, then enable the dual runner

Step 8: Check and suggest GitHub integration

If origin does not exist:

Tell the user there is currently no GitHub remote
By default, suggest creating a GitHub repository and binding it
Repository integration is completed by subsequent commands or companion scripts

Step 9: Update the minimal rules in CLAUDE.md / AGENTS.md

Only add minimal rules; do not stuff in full process implementation details.

Suggest keeping:

Currently enabled cx workflow
Key project specifications
Necessary testing or running instructions

Success result

cx-init After completion, the following should be satisfied:

Project-level 开发文档/CX工作流/配置.json has been created
Project-level 开发文档/CX工作流/状态.json has been created
开发文档/CX工作流/功能/ and 开发文档/CX工作流/修复/ already exist
GitHub integration status is clear
The project can proceed directly to the next step

Next-step prompt

After initialization is complete, by default prompt:

If it is a new feature → /cx:cx-prd
If it is a bug fix → /cx:cx-fix