@colin4k1024/tsp 2.4.0

package/commands/learn-eval.md

@@ -0,0 +1,152 @@
+---
+description: "Extract reusable patterns from the session, self-evaluate quality before saving, and determine the right save location (Global vs Project)."
+---
+
+# /learn-eval - Extract, Evaluate, then Save
+
+Extends `/learn` with a quality gate, save-location decision, and knowledge-placement awareness before writing any skill file.
+
+## What to Extract
+
+Look for:
+
+1. **Error Resolution Patterns** — root cause + fix + reusability
+2. **Debugging Techniques** — non-obvious steps, tool combinations
+3. **Workarounds** — library quirks, API limitations, version-specific fixes
+4. **Project-Specific Patterns** — conventions, architecture decisions, integration patterns
+
+## Process
+
+1. Review the session for extractable patterns
+2. Identify the most valuable/reusable insight
+
+3. **Determine save location:**
+   - Ask: "Would this pattern be useful in a different project?"
+   - **Global** (`~/.claude/skills/[pattern-name]/`): Generic patterns usable across 2+ projects (bash compatibility, LLM API behavior, debugging techniques, etc.)
+   - **Project** (`.claude/skills/[pattern-name]/` in current project root): Project-specific knowledge (quirks of a particular config file, project-specific architecture decisions, etc.)
+   - When in doubt, choose Global (moving Global → Project is easier than the reverse)
+
+4. Draft the TWO skill files using this format:
+
+**File 1: `~/.claude/skills/[pattern-name]/SKILL.md`**
+
+```markdown
+---
+name: [pattern-name]
+description: >-
+  [One sentence: what this skill is about and when it applies].
+  TRIGGER when: [specific conditions that activate this skill].
+  DO NOT TRIGGER when: [conditions where this skill does NOT apply].
+origin: learned
+tags: [tag1, tag2]
+---
+
+# [Descriptive Pattern Name]
+
+[Brief overview of what this skill covers.]
+
+## When to Activate
+
+[Exact scenarios where Claude should reference this skill.
+Include context clues, error messages, or user phrases that signal relevance.]
+
+## Solution / Pattern
+
+[Core technique or pattern — include inline code examples.]
+
+## Example
+
+\`\`\`[lang]
+// Complete, runnable example
+\`\`\`
+
+## Notes
+
+[Caveats, version constraints, edge cases, or related resources.]
+```
+
+**File 2: `~/.claude/skills/[pattern-name]/.provenance.json`**
+
+```json
+{
+  "source": "claude-code-session",
+  "created_at": "[ISO 8601 timestamp]",
+  "confidence": [0.0–1.0, reflecting extraction confidence],
+  "author": "learn-eval-command"
+}
+```
+
+**Description field requirements:**
+- Must include TRIGGER / DO NOT TRIGGER conditions for auto-activation in VS Code Claude Code
+- Must be ≤ 200 characters total for the activation description line (the trigger block may extend beyond)
+- Name must be lowercase hyphenated (e.g., `jenv-path-fix`, `react-context-split`)
+
+5. **Quality gate — Checklist + Holistic verdict**
+
+   ### 5a. Required checklist (verify by actually reading files)
+
+   Execute **all** of the following before evaluating the draft:
+
+   - [ ] Grep `~/.claude/skills/` and relevant project `.claude/skills/` files by keyword to check for content overlap
+   - [ ] Check MEMORY.md (both project and global) for overlap
+   - [ ] Consider whether appending to an existing skill would suffice
+   - [ ] Confirm this is a reusable pattern, not a one-off fix
+
+   ### 5b. Holistic verdict
+
+   Synthesize the checklist results and draft quality, then choose **one** of the following:
+
+   | Verdict | Meaning | Next Action |
+   |---------|---------|-------------|
+   | **Save** | Unique, specific, well-scoped | Proceed to Step 6 |
+   | **Improve then Save** | Valuable but needs refinement | List improvements → revise → re-evaluate (once) |
+   | **Absorb into [X]** | Should be appended to an existing skill | Show target skill and additions → Step 6 |
+   | **Drop** | Trivial, redundant, or too abstract | Explain reasoning and stop |
+
+**Guideline dimensions** (informing the verdict, not scored):
+
+- **Specificity & Actionability**: Contains code examples or commands that are immediately usable
+- **Scope Fit**: Name, trigger conditions, and content are aligned and focused on a single pattern
+- **Uniqueness**: Provides value not covered by existing skills (informed by checklist results)
+- **Reusability**: Realistic trigger scenarios exist in future sessions
+
+6. **Verdict-specific confirmation flow**
+
+- **Improve then Save**: Present the required improvements + revised draft + updated checklist/verdict after one re-evaluation; if the revised verdict is **Save**, save after user confirmation, otherwise follow the new verdict
+- **Save**: Present save path + checklist results + 1-line verdict rationale + full draft → save after user confirmation
+- **Absorb into [X]**: Present target path + additions (diff format) + checklist results + verdict rationale → append after user confirmation
+- **Drop**: Show checklist results + reasoning only (no confirmation needed)
+
+7. Save / Absorb to the determined location
+
+   **For Save:** Create two files under the chosen root:
+   - `[root]/[pattern-name]/SKILL.md` — the skill content
+   - `[root]/[pattern-name]/.provenance.json` — provenance metadata
+
+   **For Absorb:** Append content to the existing `SKILL.md` (no new directory needed — the existing skill's `.provenance.json` is preserved as-is).
+
+## Output Format for Step 5
+
+```
+### Checklist
+- [x] skills/ grep: no overlap (or: overlap found → details)
+- [x] MEMORY.md: no overlap (or: overlap found → details)
+- [x] Existing skill append: new file appropriate (or: should append to [X])
+- [x] Reusability: confirmed (or: one-off → Drop)
+
+### Verdict: Save / Improve then Save / Absorb into [X] / Drop
+
+**Rationale:** (1-2 sentences explaining the verdict)
+```
+
+## Design Rationale
+
+This version replaces the previous 5-dimension numeric scoring rubric (Specificity, Actionability, Scope Fit, Non-redundancy, Coverage scored 1-5) with a checklist-based holistic verdict system. Modern frontier models (Opus 4.6+) have strong contextual judgment — forcing rich qualitative signals into numeric scores loses nuance and can produce misleading totals. The holistic approach lets the model weigh all factors naturally, producing more accurate save/drop decisions while the explicit checklist ensures no critical check is skipped.
+
+## Notes
+
+- Don't extract trivial fixes (typos, simple syntax errors)
+- Don't extract one-time issues (specific API outages, etc.)
+- Focus on patterns that will save time in future sessions
+- Keep skills focused — one pattern per skill
+- When the verdict is Absorb, append to the existing skill rather than creating a new file

package/commands/learn.md

@@ -0,0 +1,104 @@
+# /learn - Extract Reusable Patterns
+
+Analyze the current session and extract any patterns worth saving as skills.
+
+## Trigger
+
+Run `/learn` at any point during a session when you've solved a non-trivial problem.
+
+## What to Extract
+
+Look for:
+
+1. **Error Resolution Patterns**
+   - What error occurred?
+   - What was the root cause?
+   - What fixed it?
+   - Is this reusable for similar errors?
+
+2. **Debugging Techniques**
+   - Non-obvious debugging steps
+   - Tool combinations that worked
+   - Diagnostic patterns
+
+3. **Workarounds**
+   - Library quirks
+   - API limitations
+   - Version-specific fixes
+
+4. **Project-Specific Patterns**
+   - Codebase conventions discovered
+   - Architecture decisions made
+   - Integration patterns
+
+## Output Format
+
+Create a skill directory and TWO files:
+
+### File 1: `~/.claude/skills/[pattern-name]/SKILL.md`
+
+```markdown
+---
+name: [pattern-name]
+description: >-
+  [One sentence: what this skill is about and when it applies].
+  TRIGGER when: [specific conditions that should activate this skill].
+  DO NOT TRIGGER when: [conditions where this skill does NOT apply].
+origin: learned
+tags: [tag1, tag2]
+---
+
+# [Descriptive Pattern Name]
+
+[Brief overview of what this skill covers.]
+
+## When to Activate
+
+[Describe the exact scenarios where Claude should reference this skill.
+Be specific — include context clues, error messages, or user phrases
+that signal this skill is relevant.]
+
+## Solution / Pattern
+
+[The core technique, pattern, or workaround.
+Include code examples inline whenever applicable.]
+
+## Example
+
+\`\`\`[lang]
+// Practical, complete example demonstrating the solution
+\`\`\`
+
+## Notes
+
+[Caveats, version-specific constraints, related resources, or
+conditions where this pattern may not hold.]
+```
+
+### File 2: `~/.claude/skills/[pattern-name]/.provenance.json`
+
+```json
+{
+  "source": "claude-code-session",
+  "created_at": "[ISO 8601 timestamp, e.g. 2026-04-08T10:00:00Z]",
+  "confidence": 0.8,
+  "author": "learn-command"
+}
+```
+
+## Process
+
+1. Review the session for extractable patterns
+2. Identify the most valuable/reusable insight
+3. Draft both files (SKILL.md + .provenance.json)
+4. Ask user to confirm before saving
+5. Save to `~/.claude/skills/[pattern-name]/`
+
+## Notes
+
+- Don't extract trivial fixes (typos, simple syntax errors)
+- Don't extract one-time issues (specific API outages, etc.)
+- Focus on patterns that will save time in future sessions
+- Keep skills focused — one pattern per skill
+- The `description` field MUST include TRIGGER / DO NOT TRIGGER conditions: this is what enables auto-activation in Claude Code
+- The `name` field must be lowercase and hyphenated (e.g., `fix-jenv-path`, `react-state-lift`)

package/commands/loop-start.md

@@ -0,0 +1,32 @@
+# Loop Start Command
+
+Start a managed autonomous loop pattern with safety defaults.
+
+## Usage
+
+`/loop-start [pattern] [--mode safe|fast]`
+
+- `pattern`: `sequential`, `continuous-pr`, `rfc-dag`, `infinite`
+- `--mode`:
+  - `safe` (default): strict quality gates and checkpoints
+  - `fast`: reduced gates for speed
+
+## Flow
+
+1. Confirm repository state and branch strategy.
+2. Select loop pattern and model tier strategy.
+3. Enable required hooks/profile for the chosen mode.
+4. Create loop plan and write runbook under `.claude/plans/`.
+5. Print commands to start and monitor the loop.
+
+## Required Safety Checks
+
+- Verify tests pass before first loop iteration.
+- Ensure `ECC_HOOK_PROFILE` is not disabled globally.
+- Ensure loop has explicit stop condition.
+
+## Arguments
+
+$ARGUMENTS:
+- `<pattern>` optional (`sequential|continuous-pr|rfc-dag|infinite`)
+- `--mode safe|fast` optional

package/commands/loop-status.md

@@ -0,0 +1,24 @@
+# Loop Status Command
+
+Inspect active loop state, progress, and failure signals.
+
+## Usage
+
+`/loop-status [--watch]`
+
+## What to Report
+
+- active loop pattern
+- current phase and last successful checkpoint
+- failing checks (if any)
+- estimated time/cost drift
+- recommended intervention (continue/pause/stop)
+
+## Watch Mode
+
+When `--watch` is present, refresh status periodically and surface state changes.
+
+## Arguments
+
+$ARGUMENTS:
+- `--watch` optional

package/commands/model-route.md

@@ -0,0 +1,26 @@
+# Model Route Command
+
+Recommend the best model tier for the current task by complexity and budget.
+
+## Usage
+
+`/model-route [task-description] [--budget low|med|high]`
+
+## Routing Heuristic
+
+- `haiku`: deterministic, low-risk mechanical changes
+- `sonnet`: default for implementation and refactors
+- `opus`: architecture, deep review, ambiguous requirements
+
+## Required Output
+
+- recommended model
+- confidence level
+- why this model fits
+- fallback model if first attempt fails
+
+## Arguments
+
+$ARGUMENTS:
+- `[task-description]` optional free-text
+- `--budget low|med|high` optional

package/commands/multi-backend.md

@@ -0,0 +1,31 @@
+# /multi-backend
+
+> 本文件由 `scripts/build-platform-artifacts.js` 生成，请勿手改。
+
+## 用途
+
+针对多服务、多模块或多数据边界的后端任务做编排。
+
+## 主责角色
+
+- `planner`
+
+## 期望输入
+
+- 服务边界
+- 接口与数据影响
+- 依赖与发布约束
+
+## 标准输出
+
+- 后端子任务拆解
+- 依赖顺序
+- 验证与发布注意项
+
+输出字段定义与交付结构见 [team-command-output-contracts.md](../docs/runbooks/team-command-output-contracts.md)。
+
+## 默认流程
+
+1. 先拆服务和模块边界，再拆验证与发布链。
+2. 必要时联动 architecture、database 和 language specialists。
+3. 结果回落到主团队交付链。

package/commands/multi-execute.md

@@ -0,0 +1,315 @@
+# Execute - Multi-Model Collaborative Execution
+
+Multi-model collaborative execution - Get prototype from plan → Claude refactors and implements → Multi-model audit and delivery.
+
+$ARGUMENTS
+
+---
+
+## Core Protocols
+
+- **Language Protocol**: Use **English** when interacting with tools/models, communicate with user in their language
+- **Code Sovereignty**: External models have **zero filesystem write access**, all modifications by Claude
+- **Dirty Prototype Refactoring**: Treat Codex/Gemini Unified Diff as "dirty prototype", must refactor to production-grade code
+- **Stop-Loss Mechanism**: Do not proceed to next phase until current phase output is validated
+- **Prerequisite**: Only execute after user explicitly replies "Y" to `/ccg:plan` output (if missing, must confirm first)
+
+---
+
+## Multi-Model Call Specification
+
+**Call Syntax** (parallel: use `run_in_background: true`):
+
+```
+# Resume session call (recommended) - Implementation Prototype
+Bash({
+  command: "~/.claude/bin/codeagent-wrapper {{LITE_MODE_FLAG}}--backend <codex|gemini> {{GEMINI_MODEL_FLAG}}resume <SESSION_ID> - \"$PWD\" <<'EOF'
+ROLE_FILE: <role prompt path>
+<TASK>
+Requirement: <task description>
+Context: <plan content + target files>
+</TASK>
+OUTPUT: Unified Diff Patch ONLY. Strictly prohibit any actual modifications.
+EOF",
+  run_in_background: true,
+  timeout: 3600000,
+  description: "Brief description"
+})
+
+# New session call - Implementation Prototype
+Bash({
+  command: "~/.claude/bin/codeagent-wrapper {{LITE_MODE_FLAG}}--backend <codex|gemini> {{GEMINI_MODEL_FLAG}}- \"$PWD\" <<'EOF'
+ROLE_FILE: <role prompt path>
+<TASK>
+Requirement: <task description>
+Context: <plan content + target files>
+</TASK>
+OUTPUT: Unified Diff Patch ONLY. Strictly prohibit any actual modifications.
+EOF",
+  run_in_background: true,
+  timeout: 3600000,
+  description: "Brief description"
+})
+```
+
+**Audit Call Syntax** (Code Review / Audit):
+
+```
+Bash({
+  command: "~/.claude/bin/codeagent-wrapper {{LITE_MODE_FLAG}}--backend <codex|gemini> {{GEMINI_MODEL_FLAG}}resume <SESSION_ID> - \"$PWD\" <<'EOF'
+ROLE_FILE: <role prompt path>
+<TASK>
+Scope: Audit the final code changes.
+Inputs:
+- The applied patch (git diff / final unified diff)
+- The touched files (relevant excerpts if needed)
+Constraints:
+- Do NOT modify any files.
+- Do NOT output tool commands that assume filesystem access.
+</TASK>
+OUTPUT:
+1) A prioritized list of issues (severity, file, rationale)
+2) Concrete fixes; if code changes are needed, include a Unified Diff Patch in a fenced code block.
+EOF",
+  run_in_background: true,
+  timeout: 3600000,
+  description: "Brief description"
+})
+```
+
+**Model Parameter Notes**:
+- `{{GEMINI_MODEL_FLAG}}`: When using `--backend gemini`, replace with `--gemini-model gemini-3-pro-preview` (note trailing space); use empty string for codex
+
+**Role Prompts**:
+
+| Phase | Codex | Gemini |
+|-------|-------|--------|
+| Implementation | `~/.claude/.ccg/prompts/codex/architect.md` | `~/.claude/.ccg/prompts/gemini/frontend.md` |
+| Review | `~/.claude/.ccg/prompts/codex/reviewer.md` | `~/.claude/.ccg/prompts/gemini/reviewer.md` |
+
+**Session Reuse**: If `/ccg:plan` provided SESSION_ID, use `resume <SESSION_ID>` to reuse context.
+
+**Wait for Background Tasks** (max timeout 600000ms = 10 minutes):
+
+```
+TaskOutput({ task_id: "<task_id>", block: true, timeout: 600000 })
+```
+
+**IMPORTANT**:
+- Must specify `timeout: 600000`, otherwise default 30 seconds will cause premature timeout
+- If still incomplete after 10 minutes, continue polling with `TaskOutput`, **NEVER kill the process**
+- If waiting is skipped due to timeout, **MUST call `AskUserQuestion` to ask user whether to continue waiting or kill task**
+
+---
+
+## Execution Workflow
+
+**Execute Task**: $ARGUMENTS
+
+### Phase 0: Read Plan
+
+`[Mode: Prepare]`
+
+1. **Identify Input Type**:
+   - Plan file path (e.g., `.claude/plan/xxx.md`)
+   - Direct task description
+
+2. **Read Plan Content**:
+   - If plan file path provided, read and parse
+   - Extract: task type, implementation steps, key files, SESSION_ID
+
+3. **Pre-Execution Confirmation**:
+   - If input is "direct task description" or plan missing `SESSION_ID` / key files: confirm with user first
+   - If cannot confirm user replied "Y" to plan: must confirm again before proceeding
+
+4. **Task Type Routing**:
+
+   | Task Type | Detection | Route |
+   |-----------|-----------|-------|
+   | **Frontend** | Pages, components, UI, styles, layout | Gemini |
+   | **Backend** | API, interfaces, database, logic, algorithms | Codex |
+   | **Fullstack** | Contains both frontend and backend | Codex ∥ Gemini parallel |
+
+---
+
+### Phase 1: Quick Context Retrieval
+
+`[Mode: Retrieval]`
+
+**If ace-tool MCP is available**, use it for quick context retrieval:
+
+Based on "Key Files" list in plan, call `mcp__ace-tool__search_context`:
+
+```
+mcp__ace-tool__search_context({
+  query: "<semantic query based on plan content, including key files, modules, function names>",
+  project_root_path: "$PWD"
+})
+```
+
+**Retrieval Strategy**:
+- Extract target paths from plan's "Key Files" table
+- Build semantic query covering: entry files, dependency modules, related type definitions
+- If results insufficient, add 1-2 recursive retrievals
+
+**If ace-tool MCP is NOT available**, use Claude Code built-in tools as fallback:
+1. **Glob**: Find target files from plan's "Key Files" table (e.g., `Glob("src/components/**/*.tsx")`)
+2. **Grep**: Search for key symbols, function names, type definitions across the codebase
+3. **Read**: Read the discovered files to gather complete context
+4. **Task (Explore agent)**: For broader exploration, use `Task` with `subagent_type: "Explore"`
+
+**After Retrieval**:
+- Organize retrieved code snippets
+- Confirm complete context for implementation
+- Proceed to Phase 3
+
+---
+
+### Phase 3: Prototype Acquisition
+
+`[Mode: Prototype]`
+
+**Route Based on Task Type**:
+
+#### Route A: Frontend/UI/Styles → Gemini
+
+**Limit**: Context < 32k tokens
+
+1. Call Gemini (use `~/.claude/.ccg/prompts/gemini/frontend.md`)
+2. Input: Plan content + retrieved context + target files
+3. OUTPUT: `Unified Diff Patch ONLY. Strictly prohibit any actual modifications.`
+4. **Gemini is frontend design authority, its CSS/React/Vue prototype is the final visual baseline**
+5. **WARNING**: Ignore Gemini's backend logic suggestions
+6. If plan contains `GEMINI_SESSION`: prefer `resume <GEMINI_SESSION>`
+
+#### Route B: Backend/Logic/Algorithms → Codex
+
+1. Call Codex (use `~/.claude/.ccg/prompts/codex/architect.md`)
+2. Input: Plan content + retrieved context + target files
+3. OUTPUT: `Unified Diff Patch ONLY. Strictly prohibit any actual modifications.`
+4. **Codex is backend logic authority, leverage its logical reasoning and debug capabilities**
+5. If plan contains `CODEX_SESSION`: prefer `resume <CODEX_SESSION>`
+
+#### Route C: Fullstack → Parallel Calls
+
+1. **Parallel Calls** (`run_in_background: true`):
+   - Gemini: Handle frontend part
+   - Codex: Handle backend part
+2. Wait for both models' complete results with `TaskOutput`
+3. Each uses corresponding `SESSION_ID` from plan for `resume` (create new session if missing)
+
+**Follow the `IMPORTANT` instructions in `Multi-Model Call Specification` above**
+
+---
+
+### Phase 4: Code Implementation
+
+`[Mode: Implement]`
+
+**Claude as Code Sovereign executes the following steps**:
+
+1. **Read Diff**: Parse Unified Diff Patch returned by Codex/Gemini
+
+2. **Mental Sandbox**:
+   - Simulate applying Diff to target files
+   - Check logical consistency
+   - Identify potential conflicts or side effects
+
+3. **Refactor and Clean**:
+   - Refactor "dirty prototype" to **highly readable, maintainable, enterprise-grade code**
+   - Remove redundant code
+   - Ensure compliance with project's existing code standards
+   - **Do not generate comments/docs unless necessary**, code should be self-explanatory
+
+4. **Minimal Scope**:
+   - Changes limited to requirement scope only
+   - **Mandatory review** for side effects
+   - Make targeted corrections
+
+5. **Apply Changes**:
+   - Use Edit/Write tools to execute actual modifications
+   - **Only modify necessary code**, never affect user's other existing functionality
+
+6. **Self-Verification** (strongly recommended):
+   - Run project's existing lint / typecheck / tests (prioritize minimal related scope)
+   - If failed: fix regressions first, then proceed to Phase 5
+
+---
+
+### Phase 5: Audit and Delivery
+
+`[Mode: Audit]`
+
+#### 5.1 Automatic Audit
+
+**After changes take effect, MUST immediately parallel call** Codex and Gemini for Code Review:
+
+1. **Codex Review** (`run_in_background: true`):
+   - ROLE_FILE: `~/.claude/.ccg/prompts/codex/reviewer.md`
+   - Input: Changed Diff + target files
+   - Focus: Security, performance, error handling, logic correctness
+
+2. **Gemini Review** (`run_in_background: true`):
+   - ROLE_FILE: `~/.claude/.ccg/prompts/gemini/reviewer.md`
+   - Input: Changed Diff + target files
+   - Focus: Accessibility, design consistency, user experience
+
+Wait for both models' complete review results with `TaskOutput`. Prefer reusing Phase 3 sessions (`resume <SESSION_ID>`) for context consistency.
+
+#### 5.2 Integrate and Fix
+
+1. Synthesize Codex + Gemini review feedback
+2. Weigh by trust rules: Backend follows Codex, Frontend follows Gemini
+3. Execute necessary fixes
+4. Repeat Phase 5.1 as needed (until risk is acceptable)
+
+#### 5.3 Delivery Confirmation
+
+After audit passes, report to user:
+
+```markdown
+## Execution Complete
+
+### Change Summary
+| File | Operation | Description |
+|------|-----------|-------------|
+| path/to/file.ts | Modified | Description |
+
+### Audit Results
+- Codex: <Passed/Found N issues>
+- Gemini: <Passed/Found N issues>
+
+### Recommendations
+1. [ ] <Suggested test steps>
+2. [ ] <Suggested verification steps>
+```
+
+---
+
+## Key Rules
+
+1. **Code Sovereignty** – All file modifications by Claude, external models have zero write access
+2. **Dirty Prototype Refactoring** – Codex/Gemini output treated as draft, must refactor
+3. **Trust Rules** – Backend follows Codex, Frontend follows Gemini
+4. **Minimal Changes** – Only modify necessary code, no side effects
+5. **Mandatory Audit** – Must perform multi-model Code Review after changes
+
+---
+
+## Usage
+
+```bash
+# Execute plan file
+/ccg:execute .claude/plan/feature-name.md
+
+# Execute task directly (for plans already discussed in context)
+/ccg:execute implement user authentication based on previous plan
+```
+
+---
+
+## Relationship with /ccg:plan
+
+1. `/ccg:plan` generates plan + SESSION_ID
+2. User confirms with "Y"
+3. `/ccg:execute` reads plan, reuses SESSION_ID, executes implementation