ccg-workflow 2.1.16 → 3.0.1

package/README.md

@@ -29,313 +29,188 @@
 
 ---
 
-A multi-model collaboration development system where Claude Code orchestrates Codex + Gemini. Frontend tasks route to Gemini, backend tasks route to Codex, and Claude handles orchestration and code review.
+CCG is a workflow engine for Claude Code that orchestrates multiple AI models (Codex, Gemini, Claude) with hook-based state tracking, automatic strategy selection, and Agent Teams parallel execution.
 
-## Why CCG?
+## What's new in v3.0
 
-- **Zero-config model routing** — Frontend tasks automatically go to Gemini, backend tasks to Codex. No manual switching.
-- **Security by design** — External models have no write access. They return patches; Claude reviews before applying.
-- **29+ slash commands** — From planning to execution, git workflow to code review, all accessible via `/ccg:*`.
-- **Spec-driven development** — Integrates [OPSX](https://github.com/fission-ai/opsx) to turn vague requirements into verifiable constraints, eliminating AI improvisation.
+v3.0 is a ground-up rewrite. One command replaces 29.
 
-## Architecture
-
-```
-Claude Code (Orchestrator)
-       │
-   ┌───┴───┐
-   ↓       ↓
-Codex   Gemini
-(Backend) (Frontend)
-   │       │
-   └───┬───┘
-       ↓
-  Unified Patch
-```
-
-External models have no write access — they only return patches, which Claude reviews before applying.
-
-> **🎬 [See CCG in action →](https://x.com/CCG_Workflow/status/2038923720610463876)** — Real multi-model collaboration demo on X
+- `/ccg:go` — Describe what you want in plain language. The engine analyzes your intent, picks the right strategy, and executes it.
+- **Hook engine** — Per-turn state injection keeps Claude on track even after context compaction. Session-start hooks inject full project context on every new session.
+- **Task persistence** — Medium+ complexity tasks create `.ccg/tasks/` with persistent state. Phase gates enforce HARD STOP checkpoints.
+- **Agent Teams** — Large tasks spawn parallel Builder teammates via TeamCreate. Each Builder gets isolated file ownership.
+- **Quality gates** — `verify-security`, `verify-quality`, `verify-change` run as Skill invocations inside strategy verification phases.
+- **Domain knowledge hooks** — When your message mentions security, caching, RAG, etc., the relevant knowledge file is auto-injected into context.
 
 ## Quick Start
 
-### Prerequisites
-
-| Dependency | Required | Notes |
-|------------|----------|-------|
-| **Node.js 20+** | Yes | `ora@9.x` requires Node >= 20. Node 18 causes `SyntaxError` |
-| **Claude Code CLI** | Yes | [Install guide](#install-claude-code) |
-| **jq** | Yes | Used for auto-authorization hook ([install](#install-jq)) |
-| **Codex CLI** | No | Enables backend routing |
-| **Gemini CLI** | No | Enables frontend routing |
-
-### Installation
-
 ```bash
 npx ccg-workflow
 ```
 
-On first run, CCG prompts you to select a language (English / Chinese). This preference is saved for all future sessions.
+Requires Node.js 20+ and Claude Code CLI. Codex CLI and Gemini CLI are optional (enable multi-model features).
 
-### Install jq
+The installer walks through 4 steps: API config, model routing, MCP tools, performance mode. New users get a streamlined 2-step flow with sensible defaults.
 
-```bash
-# macOS
-brew install jq
-
-# Linux (Debian/Ubuntu)
-sudo apt install jq
+## How it works
 
-# Linux (RHEL/CentOS)
-sudo yum install jq
-
-# Windows
-choco install jq   # or: scoop install jq
 ```
-
-### Install Claude Code
-
-```bash
-npx ccg-workflow menu  # Select "Install Claude Code"
+You: /ccg:go add JWT authentication to this API
+
+CCG Engine:
+  1. Reads project context (git status, tech stack, file structure)
+  2. Classifies: feature / L complexity / backend / high risk
+  3. Selects strategy: full-collaborate
+  4. Creates .ccg/tasks/add-jwt-auth/task.json
+  5. Launches dual-model analysis (Codex + Gemini in parallel)
+  6. Produces plan → HARD STOP for your approval
+  7. Spawns Agent Teams Builders for parallel implementation
+  8. Runs quality gates + dual-model cross-review
+  9. Reports results
+
+Every turn, a hook injects:
+  <ccg-state>
+  Task: add-jwt-auth (in_progress)
+  Strategy: full-collaborate
+  Phase: 4-implementation
+  Next: Layer 1 Builders executing
+  </ccg-state>
 ```
 
-Supports: npm, homebrew, curl, powershell, cmd.
-
-## Commands
+## Strategies
 
-### Development Workflow
+The engine picks a strategy based on task type and complexity:
 
-| Command | Description | Model |
-|---------|-------------|-------|
-| `/ccg:workflow` | Full 6-phase development workflow | Codex + Gemini |
-| `/ccg:plan` | Multi-model collaborative planning (Phase 1-2) | Codex + Gemini |
-| `/ccg:execute` | Multi-model collaborative execution (Phase 3-5) | Codex + Gemini + Claude |
-| `/ccg:codex-exec` | Codex full execution (plan → code → review) | Codex + multi-model review |
-| `/ccg:feat` | Smart feature development | Auto-routed |
-| `/ccg:frontend` | Frontend tasks (fast mode) | Gemini |
-| `/ccg:backend` | Backend tasks (fast mode) | Codex |
+| Strategy | When | External models | Teams |
+|----------|------|-----------------|-------|
+| direct-fix | Simple bug, single file | No | No |
+| quick-implement | Small feature, clear scope | No | No |
+| guided-develop | Medium feature, needs planning | Single model | No |
+| full-collaborate | Complex feature, multi-module | Dual model parallel | Yes |
+| debug-investigate | Complex bug, unknown cause | Dual model diagnosis | No |
+| refactor-safely | Code restructuring | Dual model review | No |
+| deep-research | Technical research, comparison | Dual model exploration | No |
+| optimize-measure | Performance optimization | Optional | No |
+| review-audit | Code review | Dual model cross-review | No |
+| git-action | commit, rollback, branches | No | No |
 
-### Analysis & Quality
+Simple tasks run fast with no overhead. Complex tasks get the full engine.
 
-| Command | Description | Model |
-|---------|-------------|-------|
-| `/ccg:analyze` | Technical analysis | Codex + Gemini |
-| `/ccg:debug` | Problem diagnosis + fix | Codex + Gemini |
-| `/ccg:optimize` | Performance optimization | Codex + Gemini |
-| `/ccg:test` | Test generation | Auto-routed |
-| `/ccg:review` | Code review (auto git diff) | Codex + Gemini |
-| `/ccg:enhance` | Prompt enhancement | Built-in |
-
-### OPSX Spec-Driven
+## Commands
 
-| Command | Description |
-|---------|-------------|
-| `/ccg:spec-init` | Initialize OPSX environment |
-| `/ccg:spec-research` | Requirements → Constraints |
-| `/ccg:spec-plan` | Constraints → Zero-decision plan |
-| `/ccg:spec-impl` | Execute plan + archive |
-| `/ccg:spec-review` | Dual-model cross-review |
+v3.0 default install: 13 commands. Legacy mode adds 18 more.
 
-### Agent Teams (v1.7.60+)
+### Core
 
 | Command | Description |
 |---------|-------------|
-| `/ccg:team-research` | Requirements → constraints (parallel exploration) |
-| `/ccg:team-plan` | Constraints → parallel implementation plan |
-| `/ccg:team-exec` | Spawn Builder teammates for parallel coding |
-| `/ccg:team-review` | Dual-model cross-review |
-
-> **Prerequisite**: Enable Agent Teams in `settings.json`: `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1`
+| `/ccg:go` | Smart entry — describe what you want, engine handles the rest |
 
-### Git Tools
+### Git
 
 | Command | Description |
 |---------|-------------|
-| `/ccg:commit` | Smart commit (conventional commit format) |
+| `/ccg:commit` | Smart conventional commit |
 | `/ccg:rollback` | Interactive rollback |
 | `/ccg:clean-branches` | Clean merged branches |
 | `/ccg:worktree` | Worktree management |
 
-### Project Setup
+### Project
 
 | Command | Description |
 |---------|-------------|
 | `/ccg:init` | Initialize project CLAUDE.md |
-| `/ccg:context` | Project context management (.context/ init, log, compress, history) |
+| `/ccg:context` | Project context management |
 
-## Workflow Guides
+### OpenSpec
 
-### Planning & Execution Separation
+| Command | Description |
+|---------|-------------|
+| `/ccg:spec-init` | Initialize OPSX environment |
+| `/ccg:spec-research` | Requirements → constraints |
+| `/ccg:spec-plan` | Constraints → zero-decision plan |
+| `/ccg:spec-impl` | Execute plan + archive |
+| `/ccg:spec-review` | Dual-model cross-review |
 
-```bash
-# 1. Generate implementation plan
-/ccg:plan implement user authentication
+## Hook Engine
 
-# 2. Review the plan (editable)
-# Plan saved to .claude/plan/user-auth.md
+CCG installs 4 hooks into `~/.claude/settings.json`:
 
-# 3a. Execute (Claude refactors) — fine-grained control
-/ccg:execute .claude/plan/user-auth.md
+| Hook | Event | Purpose |
+|------|-------|---------|
+| workflow-state.js | UserPromptSubmit | Injects task state breadcrumb every turn |
+| session-start.js | SessionStart | Injects full project context on session start/clear/compact |
+| subagent-context.js | PreToolUse (Bash/Agent) | Injects spec + task context into codeagent-wrapper calls and Team member spawns |
+| skill-router.js | UserPromptSubmit | Auto-injects domain knowledge when keywords detected |
 
-# 3b. Execute (Codex does everything) — efficient, low Claude token usage
-/ccg:codex-exec .claude/plan/user-auth.md
-```
+Hooks are JavaScript, zero dependencies, silent on failure.
 
-### OPSX Spec-Driven Workflow
+## Task System
 
-Integrates [OPSX architecture](https://github.com/fission-ai/opsx) to turn requirements into constraints, eliminating AI improvisation:
+Medium+ complexity tasks create a persistent task directory:
 
-```bash
-/ccg:spec-init                          # Initialize OPSX environment
-/ccg:spec-research implement user auth  # Research → constraints
-/ccg:spec-plan                          # Parallel analysis → zero-decision plan
-/ccg:spec-impl                          # Execute the plan
-/ccg:spec-review                        # Independent review (anytime)
+```
+.ccg/tasks/add-jwt-auth/
+├── task.json         # Status, strategy, current phase, gate
+├── requirements.md   # Enhanced requirements (full-collaborate)
+├── plan.md           # Approved implementation plan
+├── context.jsonl     # Spec files for sub-agent injection
+├── review.md         # Review results
+└── research/         # Persisted research findings
 ```
 
-> **Tip**: `/ccg:spec-*` commands internally call `/opsx:*`. You can `/clear` between phases — state is persisted in the `openspec/` directory.
+The workflow-state hook reads `task.json` every turn and injects the current state. If context gets compacted, session-start re-injects the full task context. No state is lost.
 
-### Agent Teams Parallel Workflow
+## Spec System
 
-Leverage Claude Code Agent Teams to spawn multiple Builder teammates for parallel coding:
+Project-level coding standards in `.ccg/spec/`:
 
-```bash
-/ccg:team-research implement kanban API  # 1. Requirements → constraints
-# /clear
-/ccg:team-plan kanban-api               # 2. Plan → parallel tasks
-# /clear
-/ccg:team-exec                          # 3. Builders code in parallel
-# /clear
-/ccg:team-review                        # 4. Dual-model cross-review
+```
+.ccg/spec/
+├── backend/index.md    # Backend conventions
+├── frontend/index.md   # Frontend conventions
+└── guides/index.md     # Cross-module guidelines
 ```
 
-> **vs Traditional Workflow**: Team series uses `/clear` between steps to isolate context, passing state through files. Ideal for tasks decomposable into 3+ independent modules.
+The subagent-context hook reads `context.jsonl` and injects relevant spec files into every codeagent-wrapper call and Agent Team spawn. Sub-agents follow your project's standards without being told.
 
 ## Configuration
 
-### Directory Structure
-
 ```
 ~/.claude/
-├── commands/ccg/       # 29+ slash commands
-├── agents/ccg/         # Sub-agents
-├── skills/ccg/         # Quality gates + multi-agent orchestration
-├── bin/codeagent-wrapper
-└── .ccg/
-    ├── config.toml     # CCG configuration
-    └── prompts/
-        ├── codex/      # 6 Codex expert prompts
-        └── gemini/     # 7 Gemini expert prompts
+├── commands/ccg/          # Slash commands
+├── hooks/ccg/             # Hook scripts (4 files)
+├── .ccg/
+│   ├── config.toml        # Model routing, MCP, performance
+│   ├── engine/            # Strategy files + model router
+│   └── prompts/           # Expert prompts (codex/gemini/claude)
+├── skills/ccg/            # Quality gates + domain knowledge
+└── bin/codeagent-wrapper  # Multi-model execution bridge
 ```
 
 ### Environment Variables
 
-Configure in `~/.claude/settings.json` under `"env"`:
-
-| Variable | Description | Default | When to change |
-|----------|-------------|---------|----------------|
-| `CODEAGENT_POST_MESSAGE_DELAY` | Wait after Codex completion (sec) | `5` | Set to `1` if Codex process hangs |
-| `CODEX_TIMEOUT` | Wrapper execution timeout (sec) | `7200` | Increase for very long tasks |
-| `BASH_DEFAULT_TIMEOUT_MS` | Claude Code Bash timeout (ms) | `120000` | Increase if commands time out |
-| `BASH_MAX_TIMEOUT_MS` | Claude Code Bash max timeout (ms) | `600000` | Increase for long builds |
-
-<details>
-<summary>Example settings.json</summary>
-
-```json
-{
-  "env": {
-    "CODEAGENT_POST_MESSAGE_DELAY": "1",
-    "CODEX_TIMEOUT": "7200",
-    "BASH_DEFAULT_TIMEOUT_MS": "600000",
-    "BASH_MAX_TIMEOUT_MS": "3600000"
-  }
-}
-```
-
-</details>
-
-### MCP Configuration
+Set in `~/.claude/settings.json` under `"env"`:
 
-```bash
-npx ccg-workflow menu  # Select "Configure MCP"
-```
-
-**Code retrieval** (choose one):
-- **ace-tool** (recommended) — Code search via `search_context`. [Official](https://augmentcode.com/) | [Third-party proxy](https://acemcp.heroman.wtf/)
-- **fast-context** (recommended) — Windsurf Fast Context, AI-powered search without full-repo indexing. Requires Windsurf account
-- **ContextWeaver** (alternative) — Local hybrid search, requires SiliconFlow API Key (free)
-
-**Optional tools**:
-- **Context7** — Latest library documentation (auto-installed)
-- **Playwright** — Browser automation / testing
-- **DeepWiki** — Knowledge base queries
-- **Exa** — Search engine (requires API Key)
-
-### Auto-Authorization Hook
-
-CCG automatically installs a Hook to auto-authorize `codeagent-wrapper` commands (requires [jq](#install-jq)).
-
-<details>
-<summary>Manual setup (for versions before v1.7.71)</summary>
-
-Add to `~/.claude/settings.json`:
-
-```json
-{
-  "hooks": {
-    "PreToolUse": [
-      {
-        "matcher": "Bash",
-        "hooks": [
-          {
-            "type": "command",
-            "command": "jq -r '.tool_input.command' 2>/dev/null | grep -q 'codeagent-wrapper' && echo '{\"hookSpecificOutput\": {\"hookEventName\": \"PreToolUse\", \"permissionDecision\": \"allow\", \"permissionDecisionReason\": \"codeagent-wrapper auto-approved\"}}' || true",
-            "timeout": 1
-          }
-        ]
-      }
-    ]
-  }
-}
-```
-
-</details>
-
-## Utilities
-
-```bash
-npx ccg-workflow menu  # Select "Tools"
-```
-
-- **ccusage** — Claude Code usage analytics
-- **CCometixLine** — Status bar tool (Git + usage tracking)
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `CODEX_TIMEOUT` | `7200` | Wrapper timeout (seconds) |
+| `CODEAGENT_POST_MESSAGE_DELAY` | `5` | Post-completion delay (seconds) |
+| `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS` | unset | Set to `1` to enable Agent Teams parallel execution |
 
 ## Update / Uninstall
 
 ```bash
-# Update
-npx ccg-workflow@latest            # npx users
-npm install -g ccg-workflow@latest  # npm global users
-
-# Uninstall
-npx ccg-workflow  # Select "Uninstall"
-npm uninstall -g ccg-workflow  # npm global users need this extra step
+npx ccg-workflow@latest     # Update
+npx ccg-workflow            # Select "Uninstall" from menu
 ```
 
-## FAQ
-
-### Codex CLI 0.80.0 process does not exit
-
-In `--json` mode, Codex does not automatically exit after output completion.
-
-**Fix**: Set `CODEAGENT_POST_MESSAGE_DELAY=1` in your environment variables.
-
-## Contributing
-
-We welcome contributions! See [CONTRIBUTING.md](./CONTRIBUTING.md) for guidelines.
+## Credits
 
-Looking for a place to start? Check out issues labeled [`good first issue`](https://github.com/fengshao1227/ccg-workflow/labels/good%20first%20issue).
+- [cexll/myclaude](https://github.com/cexll/myclaude) — codeagent-wrapper inspiration
+- [UfoMiao/zcf](https://github.com/UfoMiao/zcf) — Git tools reference
+- [mindfold-ai/Trellis](https://github.com/mindfold-ai/Trellis) — Hook-based workflow state patterns
+- [ace-tool](https://linux.do/t/topic/1344562) — MCP code retrieval
 
 ## Contributors
 
@@ -356,28 +231,22 @@ Looking for a place to start? Check out issues labeled [`good first issue`](http
 </table>
 <!-- readme: contributors -end -->
 
-## Credits
+## Contact
+
+- **X (Twitter)**: [@CCG_Workflow](https://x.com/CCG_Workflow)
+- **Email**: [fengshao1227@gmail.com](mailto:fengshao1227@gmail.com)
+- **Issues**: [GitHub Issues](https://github.com/fengshao1227/ccg-workflow/issues)
+- **Community**: [Linux.do](https://linux.do)
 
-- [cexll/myclaude](https://github.com/cexll/myclaude) — codeagent-wrapper
-- [UfoMiao/zcf](https://github.com/UfoMiao/zcf) — Git tools
-- [GudaStudio/skills](https://github.com/GuDaStudio/skills) — Routing design
-- [ace-tool](https://linux.do/t/topic/1344562) — MCP tool
 
 ## Star History
 
 [![Star History Chart](https://api.star-history.com/svg?repos=fengshao1227/ccg-workflow&type=timeline&legend=top-left)](https://www.star-history.com/#fengshao1227/ccg-workflow&type=timeline&legend=top-left)
 
-## Contact
-
-- **X (Twitter)**: [@CCG_Workflow](https://x.com/CCG_Workflow) — Updates, demos, and tips
-- **Email**: [fengshao1227@gmail.com](mailto:fengshao1227@gmail.com) — Sponsorship, collaboration, or development ideas
-- **Issues**: [GitHub Issues](https://github.com/fengshao1227/ccg-workflow/issues) — Bug reports and feature requests
-- **Discussions**: [GitHub Discussions](https://github.com/fengshao1227/ccg-workflow/discussions) — Questions and community chat
-
 ## License
 
 MIT
 
 ---
 
-v2.1.16 | [Issues](https://github.com/fengshao1227/ccg-workflow/issues) | [Contributing](./CONTRIBUTING.md)
+v3.0.0 | [Issues](https://github.com/fengshao1227/ccg-workflow/issues) | [Contributing](./CONTRIBUTING.md)